@stencila/schema

{ "title": "CodeChunk", "@id": "stencila:CodeChunk", "extends": "CodeBlock", "category": "code", "role": "secondary", "status": "unstable", "description": "A executable chunk of code.", "$comment": "A `CodeChunk` has two 'source' properties, `text` and `programmingLanguage`, from which it's other properties\nare derived during compilation (e.g. `import`, `declares`) or execution (e.g. `outputs`).\n\nAll `CodeChunk`s are required to have a `text` property, containing the actual code,\nand most will also specify the `programmingLanguage`. If `programmingLanguage` is not specified\nthen it defaults to the language of the previous `CodeChunk` or `CodeExpression` in the document.\n\nThe `imports` property lists the packages that a `CodeChunk` imports into the execution context.\nIt is used by the compiler to populate the `requires` property of the document containing the\nchunk so that it can build an execution environment for it (e.g. a Docker container).\n\nThe `declares` property lists the variables that a `CodeChunk` declares.\nIt is used by the compiler to build a graph of the dependencies among `CodeChunk`s and `CodeExpressions`.\nThis in turn allows for reactivity. When a user changes a chunk containing a declaration,\nall of the other chunks or expressions that use that variable will be re-executed.\n", "properties": { "type": { "@id": "schema:type", "description": "The name of the type.", "type": "string", "enum": [ "CodeChunk" ], "default": "CodeChunk", "from": "Entity" }, "id": { "@id": "schema:id", "description": "The identifier for this item.", "type": "string", "from": "Entity" }, "meta": { "@id": "stencila:meta", "description": "Metadata associated with this item.", "type": "object", "from": "Entity" }, "programmingLanguage": { "@id": "schema:programmingLanguage", "description": "The programming language of the code.", "type": "string", "from": "Code" }, "format": { "@id": "schema:encodingFormat", "aliases": [ "encoding", "encodingFormat" ], "description": "Media type, typically expressed using a MIME format, of the code.", "$comment": "This property allows the differentiation of formats using the same programming language\nor variants of a programming language. An example is using `programmingLanguage` \"json\" and\n`encodingFormat` \"application/ld+json\" for JSON-LD code examples.\n", "type": "string", "from": "Code" }, "text": { "@id": "schema:text", "description": "The text of the code.", "type": "string", "from": "Code" }, "exportFrom": { "@id": "stencila:exportFrom", "aliases": [ "export" ], "description": "A compilation directive giving the name of the variable to export\ninto the content of the code block.\n", "type": "string", "from": "CodeBlock" }, "importTo": { "@id": "stencila:importTo", "aliases": [ "export" ], "description": "A compilation directive giving the name of the variable to import\nthe content of the code block as.\n", "type": "string", "from": "CodeBlock" }, "caption": { "@id": "schema:caption", "description": "A caption for the CodeChunk.", "$comment": "An array of nodes or, to be compatible with https://schema.org/caption,\na string.\n", "anyOf": [ { "type": "array", "items": { "$ref": "BlockContent.schema.json" } }, { "type": "string" } ], "from": "CodeChunk" }, "label": { "@id": "stencila:label", "description": "A short label for the CodeChunk.", "type": "string", "from": "CodeChunk" }, "imports": { "@id": "stencila:imports", "description": "Software packages that the code chunk imports", "type": "array", "items": { "anyOf": [ { "$ref": "SoftwareSourceCode.schema.json" }, { "$ref": "SoftwareApplication.schema.json" }, { "type": "string" } ] }, "from": "CodeChunk", "isArray": true, "isPlural": true, "aliases": [ "import" ] }, "declares": { "@id": "stencila:declares", "description": "Variables that the code chunk declares.", "type": "array", "items": { "anyOf": [ { "$ref": "Variable.schema.json" }, { "$ref": "Function.schema.json" }, { "type": "string" } ] }, "from": "CodeChunk", "isArray": true, "isPlural": true, "aliases": [ "declare" ] }, "assigns": { "@id": "stencila:assigns", "description": "Variables that the code chunk assigns to.", "type": "array", "items": { "anyOf": [ { "$ref": "Variable.schema.json" }, { "type": "string" } ] }, "$comment": "In languages such as Python and R we are unable\nto differentiate between an assignment that\nis a declaration and an assignment that is an alteration\n(a re-assignment).\nThe \"primary\" compiler keeps a track of the variables\ndeclared in code chunks prior to the current chunk in the\ndocument and may treat an assignment as a declaration.\n", "from": "CodeChunk", "isArray": true, "isPlural": true, "aliases": [ "assign" ] }, "alters": { "@id": "stencila:alters", "description": "Names of variables that the code chunk alters.", "type": "array", "items": { "type": "string" }, "$comment": "This property allows users to add undetected\nalterations (i.e. not assignments) to this list. Chunks that alter a variable\nneed to be inserted into the dependency graph between `declares` and `uses`\n", "from": "CodeChunk", "isArray": true, "isPlural": true, "aliases": [ "alter" ] }, "uses": { "@id": "stencila:uses", "description": "Names of variables that the code chunk uses (but does not alter).", "type": "array", "items": { "anyOf": [ { "$ref": "Variable.schema.json" }, { "type": "string" } ] }, "from": "CodeChunk", "isArray": true, "isPlural": true, "aliases": [ "use" ] }, "reads": { "@id": "stencila:reads", "description": "Filesystem paths that this code chunk reads from.", "type": "array", "items": { "type": "string" }, "from": "CodeChunk", "isArray": true, "isPlural": true, "aliases": [ "read" ] }, "outputs": { "@id": "stencila:outputs", "description": "Outputs from executing the chunk.", "type": "array", "items": { "$ref": "Node.schema.json" }, "from": "CodeChunk", "isArray": true, "isPlural": true, "aliases": [ "output" ] }, "errors": { "@id": "stencila:errors", "description": "Errors when compiling or executing the chunk.", "type": "array", "items": { "$ref": "CodeError.schema.json" }, "from": "CodeChunk", "isArray": true, "isPlural": true, "aliases": [ "error" ] }, "duration": { "@id": "stencila:duration", "description": "Duration in seconds of the last execution of the chunk.", "type": "number", "minimum": 0, "from": "CodeChunk" } }, "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" } ] } ] } ] } ], "file": "CodeChunk.schema.yaml", "children": [], "descendants": [], "$schema": "http://json-schema.org/draft-07/schema#", "$id": "https://schema.stenci.la/v1/CodeChunk.schema.json", "source": "https://github.com/stencila/schema/blob/master/schema/CodeChunk.schema.yaml", "type": "object", "propertyAliases": { "encoding": "format", "encodingFormat": "format", "export": "importTo", "import": "imports", "declare": "declares", "assign": "assigns", "alter": "alters", "use": "uses", "read": "reads", "output": "outputs", "error": "errors" }, "additionalProperties": false, "required": [ "type", "text" ] }