Skip to main content

Code Chunk

A executable chunk of code.

!array('A ')CodeChunk!array(" has two 'source' properties, ")text!array(' and ')programmingLanguage!array(", from which it's other properties are derived during compilation (e.g. ")import!array(', ')declares!array(') or execution (e.g. ')outputs!array(').')

!array('All ')CodeChunk!array('s are required to have a ')text!array(' property, containing the actual code, and most will also specify the ')programmingLanguage!array('. If ')programmingLanguage!array(' is not specified then it defaults to the language of the previous ')CodeChunk!array(' or ')CodeExpression!array(' in the document.')

!array('The ')imports!array(' property lists the packages that a ')CodeChunk!array(' imports into the execution context. It is used by the compiler to populate the ')requires!array(' property of the document containing the chunk so that it can build an execution environment for it (e.g. a Docker container).')

!array('The ')declares!array(' property lists the variables that a ')CodeChunk!array(' declares. It is used by the compiler to build a graph of the dependencies among ')CodeChunk!array('s and ')CodeExpressions!array('. This in turn allows for reactivity. When a user changes a chunk containing a declaration, all of the other chunks or expressions that use that variable will be re-executed.')

This schema type is marked as unstable ⚠️ and is subject to change.

Properties#

Name@idTypeDescriptionInherited from
textschema:textstringThe text of the code.Code
altersstencila:altersArray of stringNames of variables that the code chunk alters. See note 1.CodeChunk
assignsstencila:assignsArray of (Variable or string)Variables that the code chunk assigns to. See note 2.CodeChunk
captionschema:captionArray of BlockContent or stringA caption for the CodeChunk. See note 3.CodeChunk
declaresstencila:declaresArray of (Variable or Function or string)Variables that the code chunk declares.CodeChunk
durationstencila:durationnumberDuration in seconds of the last execution of the chunk.CodeChunk
errorsstencila:errorsArray of CodeErrorErrors when compiling or executing the chunk.CodeChunk
exportFromstencila:exportFromstringA compilation directive giving the name of the variable to export into the content of the code block.CodeBlock
formatschema:encodingFormatstringMedia type, typically expressed using a MIME format, of the code. See note 4.Code
idschema:idstringThe identifier for this item.Entity
importTostencila:importTostringA compilation directive giving the name of the variable to import the content of the code block as.CodeBlock
importsstencila:importsArray of (SoftwareSourceCode or SoftwareApplication or string)Software packages that the code chunk importsCodeChunk
labelstencila:labelstringA short label for the CodeChunk.CodeChunk
metastencila:metaobjectMetadata associated with this item.Entity
outputsstencila:outputsArray of NodeOutputs from executing the chunk.CodeChunk
programmingLanguageschema:programmingLanguagestringThe programming language of the code.Code
readsstencila:readsArray of stringFilesystem paths that this code chunk reads from.CodeChunk
usesstencila:usesArray of (Variable or string)Names of variables that the code chunk uses (but does not alter).CodeChunk

Notes#

  1. alters : !array('This property allows users to add undetected alterations (i.e. not assignments) to this list. Chunks that alter a variable need to be inserted into the dependency graph between ')declares!array(' and ')uses
  2. assigns : !array('In languages such as Python and R we are unable to differentiate between an assignment that is a declaration and an assignment that is an alteration (a re-assignment). The "primary" compiler keeps a track of the variables declared in code chunks prior to the current chunk in the document and may treat an assignment as a declaration.')
  3. caption : !array('An array of nodes or, to be compatible with ')!array('https://schema.org/caption')!array(', a string.')
  4. format : !array('This property allows the differentiation of formats using the same programming language or variants of a programming language. An example is using ')programmingLanguage!array(' "json" and ')encodingFormat!array(' "application/ld+json" for JSON-LD code examples.')

Examples#

{
"type": "CodeChunk",
"language": "python",
"text": "print('Hello world')"
}
{
"type": "CodeChunk",
"language": "r",
"text": "superdoopa::func(\"beep\", \"boop\")\n",
"imports": [
"superdoopa"
]
}
{
"type": "CodeChunk",
"language": "python",
"text": "def greet(who: str):\n return 'Hello %s!' % who\n",
"declares": [
{
"type": "Function",
"name": "greet",
"parameters": [
{
"type": "Parameter",
"name": "who",
"schema": [
{
"type": "StringValidator"
}
]
}
]
}
]
}

Related#

Available as#

Source#

This documentation was generated from CodeChunk.schema.yaml.