entelechy-languageGenerated

Generated from the source

Data comes from cargo +nightly doc --output-format json.

Layer: frontend · Lines of code: 6,722 · Integration test files: 0

Brief

Minimal.ent Kernel language frontend: lexer, parser, AST

Description

Entelechy language frontend (L5).

One grammar, two file roles: a .ent file holds Kernels; a .esn file is a graph that uses libraries, declares inputs and outputs, and places nodes, each referencing a Kernel by id or carrying one inline.

use "kernels/";

input photo: Image;

node gray: image.grayscale@1 {
 source <- photo;
 amount = 1.0;
}
node trail: kernel {
 requires { field.read; field.write; }
 input current: Image <- gray.result;
 input previous: Image <~ trail.result from gray.result;
 output result: Image;
 compute {... }
}

output result <- trail.result;
```rust

Wiring sits at the consumer: `port <- source` reads this evaluation's
value, `port <~ source from initial` the previous commit's. A source is
a graph input or `node.port`.

Kernel syntax:

```text
kernel image.grayscale@1 {
 requires { field.read; field.write; }
 input source: Image;
 param amount: Float = 1.0;
 output result: Image;
 fn luma(c: Vec4) -> Float {
 return c.r * 0.2126 + c.g * 0.7152 + c.b * 0.0722;
 }
 compute {
 let c = sample(source);
 let g = luma(c);
 return mix(c, vec4(g, g, g, c.a), amount);
 }
}
```rust

| | |
| --- | --- |
| Internal dependencies | [`entelechy-abi`](/en/reference/crates/entelechy-abi/) |
| External dependencies | — |
| Source | [`crates/frontend/language`](https://github.com/Fynn-3D/entelechy/tree/main/crates/frontend/language) |

## Modules

| Name | Brief |
| --- | --- |
| `doc` | What a document says about what it declares: the `///` lines directly above a declaration are its doc. They are comments to the grammar: the text, not the parse, holds them. |

## Structs

| Name | Brief |
| --- | --- |
| [`doc::KernelDocs`](#dockerneldocs) | What a Kernel's source says of it and of each of its ports and params. |
| [`PackageDecl`](#packagedecl) | `package name@version { language = N; ir = N; }`: a package manifest. |
| [`Document`](#document) | A whole file. For a `.esn` the file is the graph; for a `.ent` only `kernels` is populated; a package's `package.esn` has `package`. |
| [`Outline`](#outline) | Where each statement of a document sits in its text: what an edit names and the bytes it replaces. |
| [`Statement`](#statement) | One top-level statement: its kind, the name it declares, and its bytes. |
| [`NodeBlock`](#nodeblock) | Where a node's `{... }` and the members in it were written. |
| [`NodeMemberAt`](#nodememberat) | Where one member of a node's block was written. |
| [`PresentDecl`](#presentdecl) | `to name` after an output, a bare name: the Host device its Field goes to. The language knows no device; the Host's table of them does (`entelechy_documents::devices`). |
| [`WriteDecl`](#writedecl) | `to "file"`, `to bytes "file"` or `to files "dir/"` after an output: the file, relative to the document, the output's Field is written to, or the directory its operations act in. |
| [`Held`](#held) | The declarations a Kernel holds, by the names it knows them by: its own, its document's, and those it inherits, each of these knowing where it was written. |
| [`Own`](#own) | What a document declares itself, which a name it uses reaches before any used document's declaration of the name. |
| [`Use`](#use) | `use "path";`: a file of Kernels, or a directory when it ends with `/`. |
| [`NodeDecl`](#nodedecl) | `node name: kernel@1 {... }` or `node name: kernel [id@1] {... }`. |
| [`SourceRef`](#sourceref) | `name` (a graph input) or `node.port`. |
| [`Span`](#span) | A position in the source, 1-based; line 0 (the default) is no place, for what belongs to the document as a whole. |
| [`Spanned`](#spanned) | A value with the position it came from. |
| [`Kernel`](#kernel) | A parsed Kernel. |
| [`GroupDecl`](#groupdecl) | `group N {... }`: how many elements a group holds, each a lane of it, `lane()` its place, `exchange(v, k)` lane `k`'s `v` at that point. |
| [`PrefixDecl`](#prefixdecl) | `prefix with combine {... }`: the rule an element's value meets everything before it with. |
| [`ScatterDecl`](#scatterdecl) | `scatter over input into base with combine {... }`. |
| [`CarryDecl`](#carrydecl) | The carried value of a scan. |
| [`MergeDecl`](#mergedecl) | `merge(a, b) {... }`: the fold of a reduce Kernel. Both arguments and the result have the output's element type. |
| [`TypeAlias`](#typealias) | `type Name = Shape<Element>;`: a transparent alias of a port type. |
| [`Origin`](#origin) | Where a declaration a Kernel inherits was written: the document, as the loader names it, and the name it was written with, which the Kernel may know it by under another. |
| [`StructDecl`](#structdecl) | `struct Name { field: Type;... }` |
| [`PortDecl`](#portdecl) | `input name: Type;` or `output name: Type;`, with wiring on inline Kernel inputs: `input name: Type <- source;`. |
| [`FramesDecl`](#framesdecl) | `frames "dir/" at N`: a directory's files in name order, one per frame at `rate` frames per second of session time. |
| [`RequireDecl`](#requiredecl) | `require name: condition;`: a comparison of counts over the graph's parameters and the window, which must hold for the graph to run. |
| [`ParamDecl`](#paramdecl) | `param name: Type = default;` |
| [`FnDecl`](#fndecl) | `fn name(arg: Type,...) -> Type {... }` |
| [`Block`](#block) | `let` bindings ending in a result, written `return expr;` or as a tail expression, in any block. |
| [`Expr`](#expr) | An expression. |
| [`MatchArm`](#matcharm) | One arm of a `match`: the values it takes and what it yields. |
| [`ParseError`](#parseerror) | A parse failure with a position. |
| [`Definition`](#definition) | One thing a document defines: where its name is written, what it is, its name, and what it takes and gives as written. |

## Enumerations

| Name | Brief |
| --- | --- |
| [`StatementKind`](#statementkind) | The kinds of top-level statement. |
| [`NodeKind`](#nodekind) | How a node gets its Kernel. |
| [`NodeMember`](#nodemember) | One line inside a reference node's block. |
| [`BindingDecl`](#bindingdecl) | Wiring attached to an inline Kernel's `input` line. |
| [`BinaryOp`](#binaryop) | Binary operators. |
| [`ExprKind`](#exprkind) | Expression forms. |

## Functions

| Function | Brief |
| --- | --- |
| [`fn with_doc(text: &str, range: Range<usize>) -> Range<usize>`](https://github.com/Fynn-3D/entelechy/blob/main/crates/frontend/language/src/doc.rs#L26) | `range` widened back over the `///` lines directly above it, so a declaration cut out of its document carries its doc. |
| [`fn kernel_docs(source: &str) -> KernelDocs`](https://github.com/Fynn-3D/entelechy/blob/main/crates/frontend/language/src/doc.rs#L55) | The docs of the first Kernel in `source`; empty when it does not parse. |
| [`fn on_a_deep_stack<T: Send>(work: impl FnOnce() -> T + Send) -> T`](https://github.com/Fynn-3D/entelechy/blob/main/crates/frontend/language/src/lib.rs#L791) | Runs `work` on a thread with `DEEP_STACK` of stack and waits for it; runs it here when this thread is one already or none can be spawned. Reading and compiling go through here, so the nesting limit is the same whichever thread asks. |
| [`fn definitions(document: &Document) -> Vec<Definition>`](https://github.com/Fynn-3D/entelechy/blob/main/crates/frontend/language/src/lib.rs#L1018) | What `document` defines, in the order its names are written: its own functions, structs and aliases, its Kernels (and theirs), its scene's inputs, params, outputs and nodes. |

## Constants

| Name | Type | Value | Brief |
| --- | --- | --- | --- |
| `LANGUAGE_VERSION` | `u32` | `3` | The version of the Kernel language and the document format. |
| `MAX_NESTING` | `usize` | `256` | How deep an expression or block may nest, counting enclosing nodes and chained operators (`a + b + c` is three deep at `c`). A deeper document is refused with an error, so no Kernel can exhaust the compiling thread's stack. |
| `DEEP_STACK` | `usize` | `_` | The stack of a thread that reads or compiles a document: room for a tree `MAX_NESTING` deep through every recursive pass, in a debug build too. Reserved, committed only as touched. |

## Re-exports

`quoted`, `did_you_mean`, `edit_distance`, `nearest`, `suggestion`, `RESERVED`, `outline`, `parse`, `parse_document`, `parse_literal`, `Reached`, `renamed_type`, `Declarations`, `Qualified`, `Source`, `qualified`, `scope`, `written_name`

### doc::KernelDocs

<small>[crates/frontend/language/src/doc.rs#L46](https://github.com/Fynn-3D/entelechy/blob/main/crates/frontend/language/src/doc.rs#L46)</small>

What a Kernel's source says of it and of each of its ports and params.

**Properties**

| Name | Type | Description |
| --- | --- | --- |
| `doc` | `Option<String>` | The Kernel's own. |
| `ports` | `Vec<(String, String)>` | Each documented input, output, memory or param, by name. |

<small>Implemented traits: `Clone`, `Debug`, `Default`, `Eq`, `PartialEq`, `StructuralPartialEq`</small>

---

### PackageDecl

<small>[crates/frontend/language/src/lib.rs#L73](https://github.com/Fynn-3D/entelechy/blob/main/crates/frontend/language/src/lib.rs#L73)</small>

`package name@version { language = N; ir = N; }`: a package manifest.

**Properties**

| Name | Type | Description |
| --- | --- | --- |
| `id` | `Spanned<String>` | The package's id, `name@version`. |
| `language` | `u32` | The least language version it needs. |
| `ir` | `u32` | The least IR version it needs. |

<small>Implemented traits: `Clone`, `Debug`, `Eq`, `PartialEq`, `StructuralPartialEq`</small>

---

### Document

<small>[crates/frontend/language/src/lib.rs#L85](https://github.com/Fynn-3D/entelechy/blob/main/crates/frontend/language/src/lib.rs#L85)</small>

A whole file. For a `.esn` the file is the graph; for a `.ent` only
`kernels` is populated; a package's `package.esn` has `package`.

**Properties**

| Name | Type | Description |
| --- | --- | --- |
| `package` | `Option<PackageDecl>` | The package this document is the manifest of, if it is one. |
| `uses` | `Vec<Use>` | Files or directories whose Kernels this document uses. |
| `structs` | `Vec<StructDecl>` | Top-level struct types, seen by every Kernel before its own. |
| `types` | `Vec<TypeAlias>` | Top-level port type aliases, shared the same way. |
| `functions` | `Vec<FnDecl>` | Top-level functions, shared the same way; one with a Field parameter is instantiated per port it is called with. |
| `kernels` | `Vec<Kernel>` | Kernels defined at the top level, document structs already prepended. |
| `inputs` | `Vec<PortDecl>` | External images the caller supplies: `input name: Image;`. |
| `params` | `Vec<ParamDecl>` | Graph parameters: `param name: Type = default;`, overridable by a parent graph or the caller. |
| `requires` | `Vec<RequireDecl>` | What the graph's parameters must hold: `require name: a <= b;`. |
| `outputs` | `Vec<(Spanned<String>, SourceRef)>` | Named results: `output name <- source;`. |
| `writes` | `Vec<WriteDecl>` | Outputs also written to a file: `output name <- source to "file";`. |
| `presents` | `Vec<PresentDecl>` | Outputs a Host device takes: `output name <- source to sound;`. |
| `nodes` | `Vec<NodeDecl>` | Nodes in document order. |

**Methods**

| Function | Description |
| --- | --- |
| `fn mentions(&self) -> BTreeSet<String>` | Every name this document's own code mentions, called or named: its functions, structs and types, its Kernels (inline in its nodes too), its inputs and params, its requirements, its nodes' values and the types they fill. A name it does not mention, it cannot reach for, whether or not it sees it. |
| `fn source_refs(&self) -> Vec<&SourceRef>` | Every source reference the document writes, in no set order: node wiring, inline Kernel inputs, outputs and input fallbacks. Where a reference found wanting after lowering is found again. |
| `fn resolve(&mut self, used: (&[StructDecl], &[TypeAlias], &[FnDecl]))` | Puts the declarations a document's `use` items bring in (see `scope`) in front of every Kernel's own and its document's, the Kernel's own the innermost: see `scope::resolve`. |
| `fn unqualify(&mut self, qualified: &Qualified)` | Each name this document writes qualified by a package (`random::fbm2`) written by the name the declaration it reaches holds, as `scope` found it: done before its functions are checked or it is resolved. |

<small>Implemented traits: `Clone`, `Debug`, `PartialEq`, `StructuralPartialEq`</small>

---

### Outline

<small>[crates/frontend/language/src/lib.rs#L119](https://github.com/Fynn-3D/entelechy/blob/main/crates/frontend/language/src/lib.rs#L119)</small>

Where each statement of a document sits in its text: what an edit
names and the bytes it replaces.

**Properties**

| Name | Type | Description |
| --- | --- | --- |
| `statements` | `Vec<Statement>` | Top-level statements in document order. |

<small>Implemented traits: `Clone`, `Debug`, `Default`, `Eq`, `PartialEq`, `StructuralPartialEq`</small>

---

### Statement

<small>[crates/frontend/language/src/lib.rs#L126](https://github.com/Fynn-3D/entelechy/blob/main/crates/frontend/language/src/lib.rs#L126)</small>

One top-level statement: its kind, the name it declares, and its bytes.

**Properties**

| Name | Type | Description |
| --- | --- | --- |
| `kind` | `StatementKind` | What it declares. |
| `name` | `String` | The name it declares as written (a `use`'s path, a Kernel's id); empty for `package`. |
| `range` | `Range<usize>` | From its first token to its last, the `;` or `}` included. |
| `block` | `Option<NodeBlock>` | A reference node's block of members. |

<small>Implemented traits: `Clone`, `Debug`, `Eq`, `PartialEq`, `StructuralPartialEq`</small>

---

### NodeBlock

<small>[crates/frontend/language/src/lib.rs#L186](https://github.com/Fynn-3D/entelechy/blob/main/crates/frontend/language/src/lib.rs#L186)</small>

Where a node's `{... }` and the members in it were written.

**Properties**

| Name | Type | Description |
| --- | --- | --- |
| `open` | `usize` | The byte of its `{`. |
| `close` | `usize` | The byte of its `}`. |
| `members` | `Vec<NodeMemberAt>` | Its members in order. |

<small>Implemented traits: `Clone`, `Debug`, `Eq`, `PartialEq`, `StructuralPartialEq`</small>

---

### NodeMemberAt

<small>[crates/frontend/language/src/lib.rs#L197](https://github.com/Fynn-3D/entelechy/blob/main/crates/frontend/language/src/lib.rs#L197)</small>

Where one member of a node's block was written.

**Properties**

| Name | Type | Description |
| --- | --- | --- |
| `name` | `String` | The parameter or port it sets or wires. |
| `range` | `Range<usize>` | From its first token to its `;`. |

<small>Implemented traits: `Clone`, `Debug`, `Eq`, `PartialEq`, `StructuralPartialEq`</small>

---

### PresentDecl

<small>[crates/frontend/language/src/lib.rs#L208](https://github.com/Fynn-3D/entelechy/blob/main/crates/frontend/language/src/lib.rs#L208)</small>

`to name` after an output, a bare name: the Host device its Field goes
to. The language knows no device; the Host's table of them does
(`entelechy_documents::devices`).

**Properties**

| Name | Type | Description |
| --- | --- | --- |
| `output` | `String` | The output presented. |
| `device` | `Spanned<String>` | The device, as written. |

<small>Implemented traits: `Clone`, `Debug`, `Eq`, `PartialEq`, `StructuralPartialEq`</small>

---

### WriteDecl

<small>[crates/frontend/language/src/lib.rs#L219](https://github.com/Fynn-3D/entelechy/blob/main/crates/frontend/language/src/lib.rs#L219)</small>

`to "file"`, `to bytes "file"` or `to files "dir/"` after an output:
the file, relative to the document, the output's Field is written to,
or the directory its operations act in.

**Properties**

| Name | Type | Description |
| --- | --- | --- |
| `output` | `String` | The output written. |
| `path` | `Spanned<String>` | The file. |
| `bytes` | `bool` | Written as bytes, one per `Rows<Int>` element; otherwise in the format the file's extension names. |
| `files` | `bool` | The Field is a list of operations on the files under the directory `path`: each written, removed or renamed. |

<small>Implemented traits: `Clone`, `Debug`, `Eq`, `PartialEq`, `StructuralPartialEq`</small>

---

### Held

<small>[crates/frontend/language/src/lib.rs#L289](https://github.com/Fynn-3D/entelechy/blob/main/crates/frontend/language/src/lib.rs#L289)</small>

The declarations a Kernel holds, by the names it knows them by: its
own, its document's, and those it inherits, each of these knowing
where it was written.

**Properties**

| Name | Type | Description |
| --- | --- | --- |
| `functions` | `&'a [FnDecl]` | Its functions. |
| `structs` | `&'a [StructDecl]` | Its structs. |
| `types` | `&'a [TypeAlias]` | Its types. |

**Methods**

| Function | Description |
| --- | --- |
| `fn of(kernel: &'a Kernel) -> Self` | What `kernel` holds. |
| `fn origin_of(&self, name: &str) -> Option<&'a Origin>` | Where the declaration the Kernel knows as `name` was written, when another document than the Kernel's; an instance of a function taking a Field is named for its function, `name<binding>`. |
| `fn written(&self, text: &str) -> String` | `text` with each name the Kernel knows an inherited declaration by written as that declaration was written, and each name a document does not see (`written_name`) as it wrote it. |

<small>Implemented traits: `Clone`, `Copy`, `Debug`</small>

---

### Own

<small>[crates/frontend/language/src/lib.rs#L357](https://github.com/Fynn-3D/entelechy/blob/main/crates/frontend/language/src/lib.rs#L357)</small>

What a document declares itself, which a name it uses reaches before
any used document's declaration of the name.

**Properties**

| Name | Type | Description |
| --- | --- | --- |
| `functions` | `&'a [FnDecl]` | Its functions. |
| `structs` | `&'a [StructDecl]` | Its structs. |
| `types` | `&'a [TypeAlias]` | Its types. |
| `document` | `Option<&'a Document>` | The document, whose own code says which names it reaches for (`Document::mentions`); none, and every name is taken as mentioned. |

**Methods**

| Function | Description |
| --- | --- |
| `fn of(document: &'a Document) -> Self` | What `document` declares itself. |

<small>Implemented traits: `Clone`, `Copy`, `Debug`</small>

---

### Use

<small>[crates/frontend/language/src/lib.rs#L384](https://github.com/Fynn-3D/entelechy/blob/main/crates/frontend/language/src/lib.rs#L384)</small>

`use "path";`: a file of Kernels, or a directory when it ends with `/`.

**Properties**

| Name | Type | Description |
| --- | --- | --- |
| `path` | `Spanned<String>` | The path as written, relative to the document. |

<small>Implemented traits: `Clone`, `Debug`, `Eq`, `PartialEq`, `StructuralPartialEq`</small>

---

### NodeDecl

<small>[crates/frontend/language/src/lib.rs#L391](https://github.com/Fynn-3D/entelechy/blob/main/crates/frontend/language/src/lib.rs#L391)</small>

`node name: kernel@1 {... }` or `node name: kernel [id@1] {... }`.

**Properties**

| Name | Type | Description |
| --- | --- | --- |
| `name` | `Spanned<String>` | Node name. |
| `kind` | `NodeKind` | What the node executes. |
| `members` | `Vec<NodeMember>` | Members of a reference node's block; empty for an inline Kernel, which wires on its `input` lines. |

<small>Implemented traits: `Clone`, `Debug`, `PartialEq`, `StructuralPartialEq`</small>

---

### SourceRef

<small>[crates/frontend/language/src/lib.rs#L479](https://github.com/Fynn-3D/entelechy/blob/main/crates/frontend/language/src/lib.rs#L479)</small>

`name` (a graph input) or `node.port`.

**Properties**

| Name | Type | Description |
| --- | --- | --- |
| `node` | `Option<String>` | The node, when the reference is `node.port`. |
| `name` | `String` | The graph input name or the port. |
| `span` | `Span` | Where it was written. |

<small>Implemented traits: `Clone`, `Debug`, `Eq`, `PartialEq`, `StructuralPartialEq`</small>

---

### Span

<small>[crates/frontend/language/src/lib.rs#L491](https://github.com/Fynn-3D/entelechy/blob/main/crates/frontend/language/src/lib.rs#L491)</small>

A position in the source, 1-based; line 0 (the default) is no place,
for what belongs to the document as a whole.

**Properties**

| Name | Type | Description |
| --- | --- | --- |
| `line` | `u32` | Line number. |
| `column` | `u32` | Column number in characters. |

**Methods**

| Function | Description |
| --- | --- |
| `fn is_placed(self) -> bool` | Whether it names a place in the source. |

<small>Implemented traits: `Clone`, `Copy`, `Debug`, `Default`, `Display`, `Eq`, `PartialEq`, `StructuralPartialEq`</small>

---

### Spanned

<small>[crates/frontend/language/src/lib.rs#L513](https://github.com/Fynn-3D/entelechy/blob/main/crates/frontend/language/src/lib.rs#L513)</small>

A value with the position it came from.

**Properties**

| Name | Type | Description |
| --- | --- | --- |
| `value` | `T` | The value. |
| `span` | `Span` | Where it was written. |

<small>Implemented traits: `Clone`, `Debug`, `Eq`, `PartialEq`, `StructuralPartialEq`</small>

---

### Kernel

<small>[crates/frontend/language/src/lib.rs#L522](https://github.com/Fynn-3D/entelechy/blob/main/crates/frontend/language/src/lib.rs#L522)</small>

A parsed Kernel.

**Properties**

| Name | Type | Description |
| --- | --- | --- |
| `range` | `Range<usize>` | Byte range of the whole `kernel... }` item in its document. |
| `id` | `Option<Spanned<String>>` | The raw id text, e.g. `image.grayscale@1`; `None` for an anonymous inline Kernel. |
| `domain` | `Option<Expr>` | `domain = expr;`, allowed only in an inline node Kernel. |
| `domain_range` | `Option<Range<usize>>` | Byte range of the `domain = expr;` statement in its document. |
| `requires` | `Vec<Spanned<String>>` | Declared capability names. |
| `budget` | `Option<Spanned<u32>>` | `budget N;`: the loop iterations an element may run. |
| `inputs` | `Vec<PortDecl>` | Inputs in declaration order. |
| `params` | `Vec<ParamDecl>` | Parameters in declaration order. |
| `outputs` | `Vec<PortDecl>` | Outputs in declaration order. |
| `memories` | `Vec<PortDecl>` | Memories in declaration order: `memory ram: Rows<Int>;`, a port an ordered Kernel reads and writes step by step. |
| `structs` | `Vec<StructDecl>` | Struct types in declaration order. |
| `types` | `Vec<TypeAlias>` | Port type aliases in declaration order. |
| `functions` | `Vec<FnDecl>` | Helper functions in declaration order. |
| `over` | `Option<Spanned<String>>` | `over name`: the input a scan, scatter, prefix or reduction walks, one body run per element of it, after its mode's word. |
| `compute` | `Block` | The per-element body. |
| `merge` | `Option<MergeDecl>` | `merge(a, b) {... }`: a reduction's fold of two results. |
| `carry` | `Option<CarryDecl>` | `scan over input with name = init {... }`: a scan's value carried through the elements in order. |
| `scatter` | `Option<ScatterDecl>` | `scatter over input into base with combine {... }`: a scatter, whose `compute` yields an address and a value per walked element. |
| `prefix` | `Option<PrefixDecl>` | `prefix over input with combine {... }`: a prefix fold. |
| `group` | `Option<GroupDecl>` | `group N {... }`: elements in groups of `N` that hand each other values through `exchange`. |

**Methods**

| Function | Description |
| --- | --- |
| `fn reached(&self) -> Reached<'_>` | The declarations this Kernel reaches from its own parts (`Kernel::roots`); then through each function reached, its signature and body, and each struct or type reached, its fields and target. |
| `fn trimmed(&self) -> Kernel` | This Kernel holding only the declarations it reaches (`Kernel::reached`): it compiles to what it compiled to, and keeps none of the rest of its document. |

<small>Implemented traits: `Clone`, `Debug`, `PartialEq`, `StructuralPartialEq`</small>

---

### GroupDecl

<small>[crates/frontend/language/src/lib.rs#L574](https://github.com/Fynn-3D/entelechy/blob/main/crates/frontend/language/src/lib.rs#L574)</small>

`group N {... }`: how many elements a group holds, each a lane of it,
`lane()` its place, `exchange(v, k)` lane `k`'s `v` at that point.

**Properties**

| Name | Type | Description |
| --- | --- | --- |
| `size` | `Spanned<u32>` | The lanes in a group, 1 to 256. |
| `span` | `Span` | Where `group` was written. |

<small>Implemented traits: `Clone`, `Debug`, `PartialEq`, `StructuralPartialEq`</small>

---

### PrefixDecl

<small>[crates/frontend/language/src/lib.rs#L584](https://github.com/Fynn-3D/entelechy/blob/main/crates/frontend/language/src/lib.rs#L584)</small>

`prefix with combine {... }`: the rule an element's value meets
everything before it with.

**Properties**

| Name | Type | Description |
| --- | --- | --- |
| `combine` | `Spanned<String>` | `sum`, `min`, or `max`. |
| `span` | `Span` | Where `prefix` was written. |

<small>Implemented traits: `Clone`, `Debug`, `PartialEq`, `StructuralPartialEq`</small>

---

### ScatterDecl

<small>[crates/frontend/language/src/lib.rs#L593](https://github.com/Fynn-3D/entelechy/blob/main/crates/frontend/language/src/lib.rs#L593)</small>

`scatter over input into base with combine {... }`.

**Properties**

| Name | Type | Description |
| --- | --- | --- |
| `into` | `Spanned<String>` | The input port the output starts from. |
| `combine` | `Spanned<String>` | `sum`, `min`, `max`, or `last`. |
| `span` | `Span` | Where `scatter` was written. |

<small>Implemented traits: `Clone`, `Debug`, `PartialEq`, `StructuralPartialEq`</small>

---

### CarryDecl

<small>[crates/frontend/language/src/lib.rs#L604](https://github.com/Fynn-3D/entelechy/blob/main/crates/frontend/language/src/lib.rs#L604)</small>

The carried value of a scan.

**Properties**

| Name | Type | Description |
| --- | --- | --- |
| `name` | `Spanned<String>` | Name of the carried value inside the body. |
| `init` | `Expr` | Its value before the first element; evaluated once. |
| `span` | `Span` | Where `scan` was written. |

<small>Implemented traits: `Clone`, `Debug`, `PartialEq`, `StructuralPartialEq`</small>

---

### MergeDecl

<small>[crates/frontend/language/src/lib.rs#L616](https://github.com/Fynn-3D/entelechy/blob/main/crates/frontend/language/src/lib.rs#L616)</small>

`merge(a, b) {... }`: the fold of a reduce Kernel. Both arguments and
the result have the output's element type.

**Properties**

| Name | Type | Description |
| --- | --- | --- |
| `a` | `Spanned<String>` | Name of the first value. |
| `b` | `Spanned<String>` | Name of the second value. |
| `body` | `Block` | Body yielding the merged value. |
| `span` | `Span` | Where `merge` was written. |

<small>Implemented traits: `Clone`, `Debug`, `PartialEq`, `StructuralPartialEq`</small>

---

### TypeAlias

<small>[crates/frontend/language/src/lib.rs#L629](https://github.com/Fynn-3D/entelechy/blob/main/crates/frontend/language/src/lib.rs#L629)</small>

`type Name = Shape<Element>;`: a transparent alias of a port type.

**Properties**

| Name | Type | Description |
| --- | --- | --- |
| `name` | `Spanned<String>` | Alias name; must start with an uppercase letter. |
| `target` | `Spanned<String>` | The port type it stands for, as written, e.g. `Grid<Tile>`. |
| `origin` | `Option<Origin>` | Where it was written, when another document than the Kernel's. |

**Methods**

| Function | Description |
| --- | --- |
| `fn variants(&self) -> Option<Vec<(&str, i32)>>` | The variants an `enum` names, in order, each with its number; `None` for a port type. |

<small>Implemented traits: `Clone`, `Debug`, `Eq`, `PartialEq`, `StructuralPartialEq`</small>

---

### Origin

<small>[crates/frontend/language/src/lib.rs#L642](https://github.com/Fynn-3D/entelechy/blob/main/crates/frontend/language/src/lib.rs#L642)</small>

Where a declaration a Kernel inherits was written: the document, as the
loader names it, and the name it was written with, which the Kernel may
know it by under another.

**Properties**

| Name | Type | Description |
| --- | --- | --- |
| `document` | `Arc<str>` | The document it is written in. |
| `name` | `String` | The name it is written with. |

<small>Implemented traits: `Clone`, `Debug`, `Eq`, `PartialEq`, `StructuralPartialEq`</small>

---

### StructDecl

<small>[crates/frontend/language/src/lib.rs#L670](https://github.com/Fynn-3D/entelechy/blob/main/crates/frontend/language/src/lib.rs#L670)</small>

`struct Name { field: Type;... }`

**Properties**

| Name | Type | Description |
| --- | --- | --- |
| `name` | `Spanned<String>` | Struct name; must start with an uppercase letter. |
| `fields` | `Vec<(Spanned<String>, Spanned<String>)>` | Fields as `(name, type)`; an array type is written `[Type; N]`. |
| `origin` | `Option<Origin>` | Where it was written, when another document than the Kernel's. |

<small>Implemented traits: `Clone`, `Debug`, `Eq`, `PartialEq`, `StructuralPartialEq`</small>

---

### PortDecl

<small>[crates/frontend/language/src/lib.rs#L682](https://github.com/Fynn-3D/entelechy/blob/main/crates/frontend/language/src/lib.rs#L682)</small>

`input name: Type;` or `output name: Type;`, with wiring on inline
Kernel inputs: `input name: Type <- source;`.

**Properties**

| Name | Type | Description |
| --- | --- | --- |
| `name` | `Spanned<String>` | Port name. |
| `ty` | `Spanned<String>` | Type name as written. |
| `binding` | `Option<BindingDecl>` | Wiring, only on inline Kernel inputs. |
| `file` | `Option<Spanned<String>>` | Document inputs only: a file read, `= "atlas.ppm"`. |
| `text` | `Option<Spanned<String>>` | Document inputs only: text held as character codes, `= text "ENTELECHY"`. |
| `frames` | `Option<FramesDecl>` | Document inputs only: a directory read frame by frame, `= frames "clip/" at 30`. |
| `bytes` | `Option<Spanned<String>>` | Document inputs only: a file read as bytes, one per element, `= bytes "level.bin"`. |
| `checks` | `Option<Spanned<String>>` | Document inputs only: what the language finds wrong in the documents of a file or a directory, as text, `= checks "src/"`. |
| `files` | `Option<Spanned<String>>` | Document inputs only: every file under a directory, its path and its bytes, `= files "project/"`. |
| `outline` | `Option<Spanned<String>>` | Document inputs only: what the documents of a file or a directory define, as text, `= outline "src/"`. |
| `device` | `Option<Spanned<String>>` | Document inputs only: a Host device it reads, a bare name after `=` (`= clipboard`, `= progress`). The language knows no device; the Host's table does (`entelechy_documents::devices`). |
| `otherwise` | `Option<SourceRef>` | What a file input reads while its file is unreadable: `... else fresh.result`. |
| `binding_range` | `Option<Range<usize>>` | Byte range of the wiring (`<- source`, `<~ source from initial`) in the document. |

<small>Implemented traits: `Clone`, `Debug`, `Eq`, `PartialEq`, `StructuralPartialEq`</small>

---

### FramesDecl

<small>[crates/frontend/language/src/lib.rs#L723](https://github.com/Fynn-3D/entelechy/blob/main/crates/frontend/language/src/lib.rs#L723)</small>

`frames "dir/" at N`: a directory's files in name order, one per frame
at `rate` frames per second of session time.

**Properties**

| Name | Type | Description |
| --- | --- | --- |
| `dir` | `Spanned<String>` | The directory, as written. |
| `rate` | `u32` | Frames a second. |

<small>Implemented traits: `Clone`, `Debug`, `Eq`, `PartialEq`, `StructuralPartialEq`</small>

---

### RequireDecl

<small>[crates/frontend/language/src/lib.rs#L733](https://github.com/Fynn-3D/entelechy/blob/main/crates/frontend/language/src/lib.rs#L733)</small>

`require name: condition;`: a comparison of counts over the graph's
parameters and the window, which must hold for the graph to run.

**Properties**

| Name | Type | Description |
| --- | --- | --- |
| `name` | `Spanned<String>` | Its name. |
| `condition` | `Expr` | The comparison as written. |

<small>Implemented traits: `Clone`, `Debug`, `PartialEq`, `StructuralPartialEq`</small>

---

### ParamDecl

<small>[crates/frontend/language/src/lib.rs#L742](https://github.com/Fynn-3D/entelechy/blob/main/crates/frontend/language/src/lib.rs#L742)</small>

`param name: Type = default;`

**Properties**

| Name | Type | Description |
| --- | --- | --- |
| `name` | `Spanned<String>` | Parameter name. |
| `ty` | `Spanned<String>` | Type name as written. |
| `default` | `Expr` | Default value expression. |
| `default_range` | `Range<usize>` | Byte range of the default expression in the document. |

<small>Implemented traits: `Clone`, `Debug`, `PartialEq`, `StructuralPartialEq`</small>

---

### FnDecl

<small>[crates/frontend/language/src/lib.rs#L755](https://github.com/Fynn-3D/entelechy/blob/main/crates/frontend/language/src/lib.rs#L755)</small>

`fn name(arg: Type,...) -> Type {... }`

**Properties**

| Name | Type | Description |
| --- | --- | --- |
| `name` | `Spanned<String>` | Function name. |
| `generics` | `Vec<Spanned<String>>` | Type parameters as written, `fn twice<T>(v: T) -> T`. |
| `args` | `Vec<(Spanned<String>, Spanned<String>)>` | Arguments as `(name, type)`. |
| `ret` | `Spanned<String>` | Return type name as written. |
| `body` | `Arc<Block>` | Body, shared: every Kernel that inherits the function holds the one body. |
| `origin` | `Option<Origin>` | Where it was written, when another document than the Kernel's. |

**Methods**

| Function | Description |
| --- | --- |
| `fn renamed(&self, name: String, rename: &dyn Fn(&str) -> Option<String>) -> FnDecl` | This function named `name`, each call in its body to a name `rename` maps called by the new name instead. The body is shared when nothing in it changes. |
| `fn retyped(&self, rename: &dyn Fn(&str) -> Option<String>) -> FnDecl` | This function with each struct or type name `rename` maps, in its signature and its body (a struct built, an enum's variant), named by the new name instead. The body is shared when nothing in it changes. |

<small>Implemented traits: `Clone`, `Debug`, `PartialEq`, `StructuralPartialEq`</small>

---

### Block

<small>[crates/frontend/language/src/lib.rs#L821](https://github.com/Fynn-3D/entelechy/blob/main/crates/frontend/language/src/lib.rs#L821)</small>

`let` bindings ending in a result, written `return expr;` or as a tail
expression, in any block.

**Properties**

| Name | Type | Description |
| --- | --- | --- |
| `lets` | `Vec<(Spanned<String>, Expr)>` | Bindings in order. |
| `result` | `Expr` | The resulting expression. |

<small>Implemented traits: `Clone`, `Debug`, `PartialEq`, `StructuralPartialEq`</small>

---

### Expr

<small>[crates/frontend/language/src/lib.rs#L873](https://github.com/Fynn-3D/entelechy/blob/main/crates/frontend/language/src/lib.rs#L873)</small>

An expression.

**Properties**

| Name | Type | Description |
| --- | --- | --- |
| `kind` | `ExprKind` | The expression. |
| `span` | `Span` | Where it starts. |

<small>Implemented traits: `Clone`, `Debug`, `PartialEq`, `StructuralPartialEq`</small>

---

### MatchArm

<small>[crates/frontend/language/src/lib.rs#L969](https://github.com/Fynn-3D/entelechy/blob/main/crates/frontend/language/src/lib.rs#L969)</small>

One arm of a `match`: the values it takes and what it yields.

**Properties**

| Name | Type | Description |
| --- | --- | --- |
| `values` | `Vec<Spanned<i32>>` | The `Int` values, as written, `1 \| 2 \| 3`. |
| `variants` | `Vec<(Spanned<String>, Spanned<String>)>` | The variants named, `Phase.Idle \| Phase.Walk`, as enum and variant. |
| `body` | `Block` | The arm's block: `{ lets; value }`, or a bare expression. |

<small>Implemented traits: `Clone`, `Debug`, `PartialEq`, `StructuralPartialEq`</small>

---

### ParseError

<small>[crates/frontend/language/src/lib.rs#L980](https://github.com/Fynn-3D/entelechy/blob/main/crates/frontend/language/src/lib.rs#L980)</small>

A parse failure with a position.

**Properties**

| Name | Type | Description |
| --- | --- | --- |
| `span` | `Span` | Where the problem was detected. |
| `message` | `String` | What went wrong. |

<small>Implemented traits: `Clone`, `Debug`, `Display`, `Eq`, `Error`, `PartialEq`, `StructuralPartialEq`</small>

---

### Definition

<small>[crates/frontend/language/src/lib.rs#L1002](https://github.com/Fynn-3D/entelechy/blob/main/crates/frontend/language/src/lib.rs#L1002)</small>

One thing a document defines: where its name is written, what it is,
its name, and what it takes and gives as written.

**Properties**

| Name | Type | Description |
| --- | --- | --- |
| `span` | `Span` | Where the name is written. |
| `kind` | `&'static str` | `fn`, `kernel`, `struct`, `type`, `input`, `param`, `output` or `node`. |
| `name` | `String` | The name; a Kernel's id. |
| `signature` | `String` | A function's arguments and result, a Kernel's ports, a struct's fields, an alias's type, an input's or a param's type, a node's Kernel, graph or type; empty for an output. |

<small>Implemented traits: `Clone`, `Debug`, `Eq`, `PartialEq`, `StructuralPartialEq`</small>

---

### StatementKind

<small>[crates/frontend/language/src/lib.rs#L140](https://github.com/Fynn-3D/entelechy/blob/main/crates/frontend/language/src/lib.rs#L140)</small>

The kinds of top-level statement.

**Variants**

| Name | Description |
| --- | --- |
| `Use` | `use "path";` |
| `Package` | `package name@version {... }` |
| `Struct` | `struct Name {... }` |
| `Type` | `type Name =...;` |
| `Fn` | `fn name(...) {... }` |
| `Kernel` | `kernel id@version {... }` |
| `Input` | `input name: Type...;` |
| `Param` | `param name: Type = value;` |
| `Require` | `require name: condition;` |
| `Output` | `output name <- source...;` |
| `Node` | `node name:...` |

**Methods**

| Function | Description |
| --- | --- |
| `fn keyword(self) -> &'static str` | The keyword that begins it. |

<small>Implemented traits: `Clone`, `Copy`, `Debug`, `Eq`, `PartialEq`, `StructuralPartialEq`</small>

---

### NodeKind

<small>[crates/frontend/language/src/lib.rs#L403](https://github.com/Fynn-3D/entelechy/blob/main/crates/frontend/language/src/lib.rs#L403)</small>

How a node gets its Kernel.

**Variants**

| Name | Description |
| --- | --- |
| `Reference(Spanned<String>)` | A published Kernel, by id as written. |
| `Inline(Box<Kernel>)` | A Kernel written in place, published under its id if it has one; the loader names an anonymous one after the document and node. |
| `SubGraph(Spanned<String>)` | Another `.esn` document as a node: `node fx: graph "path";`, wired and set like a Kernel. |
| `Fill(Spanned<String>)` | A filled Field of a type: zeros, or `value = 0.5;`; its element a scalar or vector, or an alias of one. |
| `Font(Spanned<String>)` | A font file's glyphs as the Host reads them: `node g: font "x.ttf" { codes &lt;- c.result; }`, its outputs `glyphs`, `outlines` and `metrics` for the characters `codes` holds. |
| `Files(Spanned<String>)` | A directory's files as the Host lists and reads them: `node d: files "dir/" { paths &lt;- p.result; }`, its outputs `listing` (every file's path and size) and `opened` (the files `paths` names). |
| `Fields { ty: Spanned<String>, dir: Spanned<String> }` | A directory's Field files of one element as the Host reads them off the frames: `node near: Rows&lt;Vertex&gt; fields "chunks/" { paths &lt;- p.result; }`, its outputs `result` (the files `paths` names that are in, their elements in the order named) and `ranges` (where each path's are). |

<small>Implemented traits: `Clone`, `Debug`, `PartialEq`, `StructuralPartialEq`</small>

---

### NodeMember

<small>[crates/frontend/language/src/lib.rs#L438](https://github.com/Fynn-3D/entelechy/blob/main/crates/frontend/language/src/lib.rs#L438)</small>

One line inside a reference node's block.

**Variants**

| Name | Description |
| --- | --- |
| `Set(Spanned<String>, Expr)` | `name = expr;`: a parameter value, or the reserved `domain`. |
| `Bind(Spanned<String>, SourceRef)` | `port <- source;` |
| `Carry(Spanned<String>, Spanned<String>)` | `carry port <- output;`: with `times = N;`, each time after the first reads the previous time's output. |
| `Previous { port: Spanned<String>, source: SourceRef, initial: SourceRef, migration: Option<Spanned<String>> }` | `port <~ source from initial [migrate kernel.id@v];` |

<small>Implemented traits: `Clone`, `Debug`, `PartialEq`, `StructuralPartialEq`</small>

---

### BindingDecl

<small>[crates/frontend/language/src/lib.rs#L462](https://github.com/Fynn-3D/entelechy/blob/main/crates/frontend/language/src/lib.rs#L462)</small>

Wiring attached to an inline Kernel's `input` line.

**Variants**

| Name | Description |
| --- | --- |
| `Now(SourceRef)` | `<- source` |
| `Previous { source: SourceRef, initial: SourceRef, migration: Option<Spanned<String>> }` | `<~ source from initial [migrate kernel.id@v]` |

<small>Implemented traits: `Clone`, `Debug`, `Eq`, `PartialEq`, `StructuralPartialEq`</small>

---

### BinaryOp

<small>[crates/frontend/language/src/lib.rs#L830](https://github.com/Fynn-3D/entelechy/blob/main/crates/frontend/language/src/lib.rs#L830)</small>

Binary operators.

**Variants**

| Name | Description |
| --- | --- |
| `Add` | `+` |
| `Sub` | `-` |
| `Mul` | `*` |
| `Div` | `/` |
| `Rem` | `%`: the remainder, truncated like `/` |
| `Less` | `<` |
| `LessEqual` | `<=` |
| `Greater` | `>` |
| `GreaterEqual` | `>=` |
| `Equal` | `==` |
| `NotEqual` | `!=` |
| `And` | `&&` |
| `Or` | `\|\|` |
| `BitAnd` | `&` on integers |
| `BitOr` | `\|` on integers |
| `BitXor` | `^` on integers |
| `Shl` | `<<` on integers |
| `Shr` | `>>` on integers, arithmetic |
| `Ushr` | `>>>` on integers, logical |

<small>Implemented traits: `Clone`, `Copy`, `Debug`, `Eq`, `PartialEq`, `StructuralPartialEq`</small>

---

### ExprKind

<small>[crates/frontend/language/src/lib.rs#L882](https://github.com/Fynn-3D/entelechy/blob/main/crates/frontend/language/src/lib.rs#L882)</small>

Expression forms.

**Variants**

| Name | Description |
| --- | --- |
| `Float(f64)` | A float literal such as `1.0`, exact as written: a `Float`, or a `Double` where one is wanted. |
| `Int(i64)` | An integer literal such as `8`: an `Int`, or a `Long` where one is wanted or the value needs 64 bits. |
| `Double(f64)` | A float literal written with `d`, such as `0.1d`: a `Double`. |
| `Long(i64)` | An integer literal written with `l`, such as `8l`: a `Long`. |
| `Bool(bool)` | `true` or `false`. |
| `Name(String)` | A reference to an input, parameter, argument, or binding. |
| `Call(String, Vec<Expr>)` | A call to a builtin, intrinsic, or helper function. |
| `Member(Box<Expr>, String)` | Component access such as `c.r`, or a struct field such as `hit.distance`. |
| `Array(Vec<Expr>)` | `[a, b, c]`: an array of the listed elements, all of one type. |
| `Repeat(Box<Expr>, Spanned<u32>)` | `[value; n]`: an array of `n` copies of a value. |
| `Each(Spanned<u32>, Box<Block>)` | `[each n { body }]`: an array built element by element, the body run once per element with `index()` its position. |
| `Subscript(Box<Expr>, Box<Expr>)` | `array[index]`: the element at an `Int` index, clamped into the array; a literal index is checked when compiled. |
| `Struct { name: Spanned<String>, base: Option<Box<Expr>>, fields: Vec<(Spanned<String>, Expr)> }` | `Name { field: expr,..base }`. |
| `Record(Vec<(Spanned<String>, Expr)>)` | `{ name: expr,... }`: each output once by name, the result of a multi-output Kernel's `compute`. |
| `Neg(Box<Expr>)` | Negation. |
| `Not(Box<Expr>)` | Logical not. |
| `Binary(BinaryOp, Box<Expr>, Box<Expr>)` | Binary arithmetic, comparison, or logic. |
| `If { condition: Box<Expr>, then: Box<Block>, otherwise: Box<Block> }` | `if condition { then } else { otherwise }`. |
| `Match { scrutinee: Box<Expr>, arms: Vec<MatchArm>, otherwise: Option<Box<Block>> }` | `match value { 1 => a, 2 \| 3 => {... }, _ => b }` on an `Int`, or `match phase { Phase.Idle => a, Phase.Walk => b }` naming an enum's variants. |
| `Break(Box<Expr>)` | `break expr;` in a loop body: the loop ends after this iteration with that value. |
| `Loop { count: Box<Expr>, name: Spanned<String>, init: Box<Expr>, until: Option<Box<Expr>>, body: Box<Block> }` | `loop count with name = init until done { body }`. |

<small>Implemented traits: `Clone`, `Debug`, `PartialEq`, `StructuralPartialEq`</small>

---