entelechy-sceneGenerated

Layer: frontend · Lines of code: 4,349 · Integration test files: 2

Brief

Entelechy scene documents:.esn lowered into the Graph model, sub-graphs flattened, inline Kernels handed to the loader

Description

Scene documents: a parsed .esn lowered into the Graph model, with sub-graphs flattened in place.

The frontend half of composition: this crate reads and checks what was written (nodes, wiring, domains, times, placed sub-graphs, inline Kernels) and hands the loader the inline Kernels to publish. The caller supplies files through a Loader.


Internal dependencies	`entelechy-abi`, `entelechy-compiler`, `entelechy-graph`, `entelechy-ir`, `entelechy-language`
External dependencies	—
Source	`crates/frontend/scene`

Modules

Name	Brief
`domain`	A node’s written `domain`, accepted into the Graph’s `DomainExpr`: the subset of the expression language a domain may use.
`edit`	Edits of a document’s text by what it declares: a statement by kind and name, or a node’s member by node and member, is replaced, added or removed, changing only its bytes. The caller checks the result.

Structs

Name	Brief
`domain::Function`	One function a `domain` may call, as `help` shows it.
`edit::Edit`	One edit: the target’s new text, the whole statement or member declaring exactly what the target names, or `None` to remove it. A new target is added after the last of its kind.
`edit::EditError`	Why an edit failed, and which one.
`DocumentError`	A document does not parse or does not describe a valid graph.
`InlineKernel`	A Kernel written inside a node, for the loader to publish.
`Asset`	An external a document reads from a file.
`Write`	A file output: `output name <- source to "file";`.
`Feed`	An input a Host device feeds: `input name: Type = device;`. The device is a name the Host’s table knows (`entelechy_documents::devices`); the scene knows none.
`Present`	An output a Host device takes: `output name <- source to device;`. The device is a name the Host’s table knows (`entelechy_documents::devices`); the scene knows none.
`Files`	A scene’s file contract: inputs read from files, directories read as frames, and outputs written. The session carries them out.
`FontNode`	A `font` node: `node g: font "x.ttf" { codes <- c.result; }`. It is three externals the session fills, `glyphs`, `outlines` and `metrics` in the layouts `entelechy import` writes a font’s Fields in, read as `g.glyphs` and the others.
`FilesNode`	A `files` node: `node d: files "dir/" { paths <- p.result; }`. It is two externals the session fills: `listing`, every file under the directory that is not ignored, its path and size, and `opened`, the files `paths` named when last evaluated, their bytes, in the layouts of `entelechy_formats::directory`; read as `d.listing` and `d.opened`.
`FieldsNode`	A `fields` node: `node near: Rows<Vertex> fields "chunks/" { paths <- p.result; }`. It is two externals the session fills: `result`, the elements of the Field files `paths` named when last evaluated that are in, in the order named, and `ranges`, a row a path, where its elements start in `result` and how many there are (-1 and 0 for one not in); read as `near.result` and `near.ranges`.
`Lowered`	A lowered document: the graph plus everything the loader must publish and watch.

Enumerations

Name	Brief
`edit::Target`	What an edit names.

Functions

Function	Brief
`fn functions() -> Vec<Function>`	Every function a `domain` may call; a domain is also numbers, parameters by name, and `+ - * / <<`.
`fn domain_expr(expr: &Expr) -> Result<DomainExpr, DocumentError>`	Accepts the subset of the expression language a domain may use.
`fn requirement(decl: &RequireDecl) -> Result<Requirement, DocumentError>`	A written `require` accepted: two counts compared, over numbers, the graph’s parameters, `window()` and `scale()`; a node’s ports it has none of.
`fn edit(document: &str, edits: &[Edit]) -> Result<String, EditError>`	`document` with `edits` made in order, all or none: the error names the first that fails.
`fn publishable_text(document: &str, kernel: &Kernel, id: &KernelId, edits: Vec<(Range<usize>, String)>) -> String`	An inline Kernel’s text as `publish` takes it: the node’s Kernel with its `domain` statement and input wiring removed, graph-param defaults replaced by `edits` (document byte ranges and their text), and the node’s id written in when it has none.
`fn anonymous_id(document: &str, node: &str) -> KernelId`	An anonymous inline Kernel’s id: document and node names, lowercased with unsupported characters replaced, at version 1.
`fn parse(text: &str) -> Result<Graph, DocumentError>`	Parses a `.esn` document that references published Kernels only. Inline Kernels and sub-graphs take `load`.
`fn from_document(document: &Document, name: &str) -> Result<Lowered, DocumentError>`	Lowers a parsed document that places no sub-graphs into a Graph named `name`, reporting inline Kernels for the loader to publish. Anonymous inline Kernels are named by `anonymous_id`.
`fn load(document: &Document, text: &str, name: &str, base: &Path, loader: &mut Loader<'_>) -> Result<Lowered, DocumentError>`	Lowers a parsed document into a Graph, loading its sub-graphs through `loader` (paths resolved against `base`) and flattening them in place: nodes prefixed with the placing node’s name, inputs and params taken from the parent.
`fn load_with(document: &Document, text: &str, name: &str, base: &Path, loader: &mut Loader<'_>, declare: &mut Declare<'_>) -> Result<Lowered, DocumentError>`	Loads like `load`, also resolving every document’s `use` items through `declare` for all its Kernels.
`fn load_with_params(document: &Document, text: &str, name: &str, base: &Path, loader: &mut Loader<'_>, declare: &mut Declare<'_>, overrides: &BTreeMap<String, Value>) -> Result<Lowered, DocumentError>`	As `load_with`, with parameter overrides a node’s `times` may read.
`fn print(graph: &Graph) -> String`	A graph written as a scene document. One that places no graph lowers back to the same graph; a placed graph’s nodes are named by their path (`title.advances`), which shows the plan and does not read back. A file input is written as a caller-supplied image.
`fn literal_text(value: &Value) -> String`	Renders a value in the literal grammar shared with `.ent`.

Constants

Name	Type	Value	Brief
`FONT_OUTPUTS`	`[&str; 3]`	`_`	A font node’s outputs, in order.
`FILES_OUTPUTS`	`[&str; 2]`	`_`	A files node’s outputs, in order.
`FIELDS_OUTPUTS`	`[&str; 2]`	`_`	A fields node’s outputs, in order.
`MAX_PLACED`	`usize`	`_`	The most nodes one scene places, every level of `times` and sub-graph placement together, bounding the loader’s memory and work.

Type aliases

Name	Type	Brief
`Loader`	`dyn FnMut(&Path) -> Result<(PathBuf, String), String>`	Reads a document at a path a placement writes: where the file is (one path for one file, however it is written or reached) and its text.
`Declare`	`dyn FnMut(&Path, &[Use], Own<'_>) -> Result<Declarations, String>`	Resolves a document’s `use` items, given its directory and what it declares itself, to the structs, type aliases and functions every Kernel of the document sees, and the names it writes qualified by a package. The caller reads the files.

Re-exports

StatementKind, domain_expr

domain::Function

crates/frontend/scene/src/domain.rs#L11

One function a domain may call, as help shows it.

Properties

Name	Type	Description
`name`	`&'static str`	Its name.
`shape`	`&'static str`	How it is written.
`doc`	`&'static str`	What it gives.
`example`	`&'static str`	A `domain` written with it, which `domain_expr` accepts.

Implemented traits: Clone, Debug

edit::Edit

crates/frontend/scene/src/edit.rs#L36

One edit: the target’s new text, the whole statement or member declaring exactly what the target names, or None to remove it. A new target is added after the last of its kind.

Properties

Name	Type	Description
`target`	`Target`	What it changes.
`text`	`Option<String>`	Its new text, or `None` to remove it.

Implemented traits: Clone, Debug, Eq, PartialEq, StructuralPartialEq

edit::EditError

crates/frontend/scene/src/edit.rs#L45

Why an edit failed, and which one.

Properties

Name	Type	Description
`index`	`usize`	The edit’s place in the list, from 0.
`message`	`String`	What is wrong.

Implemented traits: Clone, Debug, Display, Eq, Error, PartialEq, StructuralPartialEq

DocumentError

crates/frontend/scene/src/lib.rs#L75

A document does not parse or does not describe a valid graph.

Properties

Name	Type	Description
`span`	`Span`	Where the problem is.
`message`	`String`	What is wrong.

Implemented traits: Clone, Debug, Display, Eq, Error, From, PartialEq, StructuralPartialEq

InlineKernel

crates/frontend/scene/src/lib.rs#L121

A Kernel written inside a node, for the loader to publish.

Properties

Name	Type	Description
`node`	`NodeId`	The flattened node that carries it.
`id`	`KernelId`	The id it publishes as: its own, or an anonymous one.
`kernel`	`Kernel`	The parsed Kernel, with graph-param defaults resolved to literals.
`text`	`String`	Its source text.
`document`	`PathBuf`	The document it was written in.

Implemented traits: Clone, Debug, PartialEq, StructuralPartialEq

Asset

crates/frontend/scene/src/lib.rs#L136

An external a document reads from a file.

Properties

Name	Type	Description
`name`	`String`	The input’s name.
`path`	`PathBuf`	The file, resolved against the document’s directory.
`ty`	`String`	The type, aliases resolved: it decides how a picture file comes in and how the Field keeps it (`Grid<Vec4 as unorm8>`).
`bytes`	`bool`	Whether the file comes in as its bytes, one per element of a `Rows<Int>`.

Implemented traits: Clone, Debug, Eq, PartialEq, StructuralPartialEq

Write

crates/frontend/scene/src/lib.rs#L151

A file output: output name <- source to "file";.

Properties

Name	Type	Description
`output`	`String`	The output’s name.
`path`	`PathBuf`	The file, resolved against the document’s directory.
`bytes`	`bool`	Whether the Field goes out as its bytes, one per element of a `Rows<Int>`, instead of in the extension’s format.
`files`	`bool`	Whether the Field is a list of operations on the files under the directory `path` (`to files "dir/"`).

Implemented traits: Clone, Debug, Eq, PartialEq, StructuralPartialEq

Feed

crates/frontend/scene/src/lib.rs#L168

An input a Host device feeds: input name: Type = device;. The device is a name the Host’s table knows (entelechy_documents::devices); the scene knows none.

Properties

Name	Type	Description
`input`	`String`	The input’s name.
`device`	`String`	The device, as written.
`ty`	`String`	The input’s type, aliases resolved: the device gives one structure.
`at`	`Span`	Where the device’s name is written: a fault in it is said there.

Implemented traits: Clone, Debug, Eq, PartialEq, StructuralPartialEq

Present

crates/frontend/scene/src/lib.rs#L183

An output a Host device takes: output name <- source to device;. The device is a name the Host’s table knows (entelechy_documents::devices); the scene knows none.

Properties

Name	Type	Description
`output`	`String`	The output’s name.
`device`	`String`	The device, as written.
`at`	`Span`	Where the device’s name is written: a fault in it is said there.

Implemented traits: Clone, Debug, Eq, PartialEq, StructuralPartialEq

Files

crates/frontend/scene/src/lib.rs#L195

A scene’s file contract: inputs read from files, directories read as frames, and outputs written. The session carries them out.

Properties

Name	Type	Description
`assets`	`Vec<Asset>`	Externals read from files, loaded and watched by the session.
`sequences`	`Vec<(String, PathBuf, String, u32)>`	Externals read frame by frame from a directory: name, resolved directory, type as written, and frames per second of session time.
`checks`	`Vec<(String, PathBuf)>`	Externals holding what the language finds wrong in the documents of a file or a directory, as text: name, resolved path. The session checks them again when one changes.
`files`	`Vec<(String, PathBuf)>`	Externals holding every file under a directory, its path and its bytes: name, resolved directory. The session reads them again when one changes, or which there are.
`outlines`	`Vec<(String, PathBuf)>`	Externals holding what the documents of a file or a directory define, as text: name, resolved path. The session reads them again when one changes.
`feeds`	`Vec<Feed>`	Externals a Host device feeds, the root’s only: `= clipboard`, `= progress`. The session reads each again when its device changes.
`writes`	`Vec<Write>`	The root document’s file outputs, written after a committed evaluation that changed them.
`presented`	`Vec<Present>`	The root document’s outputs a Host device takes, one an output.
`fonts`	`Vec<FontNode>`	Font nodes, at every level: the session reads their fonts and gives each the glyphs of the characters its `codes` held when last evaluated.
`file_nodes`	`Vec<FilesNode>`	Files nodes, at every level: the session lists their directories and gives each the files its `paths` named when last evaluated.
`field_nodes`	`Vec<FieldsNode>`	Fields nodes, at every level: the session reads, off the frames, the Field files each node’s `paths` named when last evaluated.

Methods

Function	Description
`fn fed_by(&self, device: &str) -> Vec<String>`	The inputs device `device` feeds, by name.

Implemented traits: Clone, Debug, Default, Eq, PartialEq, StructuralPartialEq

FontNode

crates/frontend/scene/src/lib.rs#L249

A font node: node g: font "x.ttf" { codes <- c.result; }. It is three externals the session fills, glyphs, outlines and metrics in the layouts entelechy import writes a font’s Fields in, read as g.glyphs and the others.

Properties

Name	Type	Description
`node`	`String`	The node’s id, placed.
`path`	`PathBuf`	The font file, resolved against the document’s directory.
`codes`	`Source`	Where the characters wanted come from, read as last evaluated.
`outputs`	`Vec<(String, String)>`	Each output’s port and the external that holds it.

Implemented traits: Clone, Debug, Eq, PartialEq, StructuralPartialEq

FilesNode

crates/frontend/scene/src/lib.rs#L269

A files node: node d: files "dir/" { paths <- p.result; }. It is two externals the session fills: listing, every file under the directory that is not ignored, its path and size, and opened, the files paths named when last evaluated, their bytes, in the layouts of entelechy_formats::directory; read as d.listing and d.opened.

Properties

Name	Type	Description
`node`	`String`	The node’s id, placed.
`dir`	`PathBuf`	The directory, resolved against the document’s directory.
`paths`	`Source`	Where the paths wanted come from, read as last evaluated.
`outputs`	`Vec<(String, String)>`	Each output’s port and the external that holds it.

Implemented traits: Clone, Debug, Eq, PartialEq, StructuralPartialEq

FieldsNode

crates/frontend/scene/src/lib.rs#L290

A fields node: node near: Rows<Vertex> fields "chunks/" { paths <- p.result; }. It is two externals the session fills: result, the elements of the Field files paths named when last evaluated that are in, in the order named, and ranges, a row a path, where its elements start in result and how many there are (-1 and 0 for one not in); read as near.result and near.ranges.

Properties

Name	Type	Description
`node`	`String`	The node’s id, placed.
`dir`	`PathBuf`	The directory, resolved against the document’s directory.
`ty`	`String`	The type of `result`, aliases resolved: `Rows` of the element.
`paths`	`Source`	Where the paths wanted come from, read as last evaluated.
`outputs`	`Vec<(String, String)>`	Each output’s port and the external that holds it.

Implemented traits: Clone, Debug, Eq, PartialEq, StructuralPartialEq

Lowered

crates/frontend/scene/src/lib.rs#L309

A lowered document: the graph plus everything the loader must publish and watch.

Properties

Name	Type	Description
`graph`	`Graph`	The graph.
`files`	`Files`	The document’s file contract, carried out by the session.
`inline`	`Vec<InlineKernel>`	Inline Kernels from every level, in document order.
`uses`	`Vec<(PathBuf, bool)>`	`use` targets from every level, resolved, with whether the path named a directory.
`documents`	`Vec<PathBuf>`	Sub-graph documents that were loaded, resolved.

Implemented traits: Clone, Debug, PartialEq, StructuralPartialEq

edit::Target

crates/frontend/scene/src/edit.rs#L14

What an edit names.

Variants

Name	Description
`Statement { kind: StatementKind, name: String }`	A top-level statement by kind and declared name (a Kernel’s id as written, a `use`’s path).
`Member { node: String, member: String }`	A member of a node’s block, by the parameter or port it sets.

Implemented traits: Clone, Debug, Display, Eq, PartialEq, StructuralPartialEq