entelechy-documentsGenerated

Generated from the source

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

Layer: interface · Lines of code: 11,358 · Integration test files: 0

Brief

Entelechy documents: the scene and libraries a session runs, the Kernels they publish, the Graph they lower to, and the files they read and write

Description

The documents a session runs: one .esn scene and the .ent libraries it uses, what they publish, the Graph they lower to, and the files they read and write.

Four parts each own their state and reach the others only through what they are handed: the scene reads documents and lowers the Graph; the ledger knows which document published which Kernel; the inputs own the Fields a scene’s inputs hold; and source resolution is stateless. The store is where documents are read from, the history what changed them.

Nothing here runs a Kernel: entelechy-session opens the backends, keeps the runtime and evaluator, and orders the parts’ sync.

Internal dependencies	entelechy-compiler, entelechy-formats, entelechy-graph, entelechy-import, entelechy-ir, entelechy-kernel, entelechy-language, entelechy-rules, entelechy-scene
External dependencies	—
Source	crates/interface/documents

Modules

Name	Brief
check	entelechy check: a document checked through a store, without a session.
devices	The Host’s devices a scene’s outputs go to and its inputs are fed by: output name <- source to device;, input name: Type = device;. The language knows no device; this table is the one place that does, each with the structure of Field it takes and gives. A device comes with a primitive of the Host’s IO, never for one scene’s sake.
history	What changed the world, and where it came from. A position is the revision, moved by every change but running (publish, retire, scene read, param, state written or reset), and the frames committed since. Changes and refused attempts are remembered with their origin, within fixed bounds, newest kept. Kernel sources and the scene’s document texts are kept once by digest, so a generation the registry released and a document’s earlier version stay readable. Whole worlds are snapshots, kept by whoever took them.
ignore	What a directory’s listing leaves out, as git does: the rules of every .gitignore on the way to a file, each relative to its own directory. A line is a pattern, # a comment, ! taking a pattern back; a pattern ending / matches directories alone; one with a / elsewhere is held to the .gitignore’s directory, one without matches a name at any depth; * and ? match within a part, [...] one of a set, ** any parts. The last rule that matches decides, and a directory left out is not walked, so nothing under it comes back.
inputs	The Fields a scene’s inputs hold: a file (reread on change), a directory frame chosen by time, a text as character codes, or a caller binding. Inputs own their Host handles and release each one they replace or forget. A data table (.csv, .json) is read as the Kernel reading the input lays out its element, and read again when that layout changes.
kernels	The ledger of which document published which Kernel. The runtime owns the Kernels; the scene reads the documents.
overrides	Where a scene’s file-backed inputs read and its outputs write, as the person running it says (--input name=path, --output name=path, a folder chosen in a player): the path a document writes for an input or an output replaced by the caller’s, the source’s kind kept. The scene’s own text is unchanged; the caller resolves the source.
package	What a package is to the session that reads it: the parts of a package directory and how a scene reaches one by name, each kept by the code that reads it: the manifest and the Kernels by the sources, the presets by the scene’s lowering, the directories a name is looked for in by the session’s options. help’s packages section answers this table; tests/package.rs holds a package to it.
reads	What a session may read. Where reads are held (an agent composes the scene), every read the session makes goes through Held: the path is resolved as the store follows it, links and .. included, and read only where it lands inside a readable directory. Documents, placed graphs, inputs and frames are all read there, so no reader checks apart from the others.
scene	The scene from its documents: the root .esn, its sub-graphs and libraries, their shared declarations, the lowered Graph, and caller params. The scene reads documents; the ledger (Kernels) publishes their Kernels.
sources	Source resolution: what a use reaches (a file, a directory of .ent, or a package beside the document or in the store’s Store::packages), inherited declarations, and where a missing name is declared. Stateless; reads through the given store.
spread	Work spread over the cores: each item mapped on whichever thread is free, the results in the items’ order. Where one core is all there is, or no thread can be spawned (a page), each is mapped in turn here.
store	Where a session’s documents are. Every session read and write goes through a Store: the Disk, or Memory, files the caller handed in (a page). The caller chooses; the session behaves the same.
writes	A scene’s file outputs (output name <- source to "file";). The session writes each once the evaluation that changed it is confirmed, whole, into an allowed directory; an output to files "dir/" is a list of operations on the files under the directory, each done once when the list changes: a write where writes are allowed, a removal or a rename where removals are too.

Structs

Name	Brief
check::Checked	What checking a document found: the lines to report, in order.
devices::Port	A structure of Field a device takes or gives.
devices::Device	A device: what an output gives it (takes) and what it feeds an input (gives), either or both.
history::Record	A change and where the world was when it happened.
history::Attempt	A refused attempt, which changed nothing.
history::History	The session’s memory of change.
inputs::TableElement	The element a data table input is read as: the name of each number it holds and the layout, as the Kernel reading the input lays them out; and how its port keeps them, narrow where it says so (Int as u8).
inputs::Declared	What a scene declares of its inputs: its graph, the files and directories they are read from, and the element each data table is read as (table_elements).
inputs::Inputs	The inputs of a scene and the Fields they hold.
kernels::Kernels	The ledger of published Kernels by the document that owns each.
kernels::Kept	A copy of the ledger to restore whole (Kernels::put_back).
kernels::Written	A Kernel as its document writes it: unoptimized, with where each value is written.
overrides::Overrides	Paths given for a scene’s inputs and outputs, by name.
package::Part	One part of a package, as the session reads it.
reads::Reads	The directories a session may read under.
reads::Held	A store whose reads are held to Reads.
scene::Scene	A scene document and what was built from it.
scene::Kept	The running scene, kept to be put back whole (Scene::put_back).
store::Stamp	A file’s version as read; it changes whenever the file does.
store::Parsed	Documents parsed once per stamp: a document read again unchanged is not parsed again; and what is worked out of them once, by content, for every session reading through the store.
store::Disk	The process’s file system, and the directories packages are found in by name, as whoever opened the session gave them.
store::Memory	Files handed in by the caller, kept in memory. A path is its name with . and .. folded; a directory is any path a file is under; every file has one name.
store::Kept	A store whose writes are kept beside base and never reach it: each file written, removed or renamed through it is held here, everything else read as base has it. What a replay that allows writes runs over, so a run changes nothing on disk and every run starts from the same files.
store::Overlay	A store seen through texts not yet written: each of texts read as if it stood at its path (new files and the directories they would make included), everything else as base has it. What a compose of several documents is checked against before any reaches base; nothing is written through it.
writes::Writes	The directories writes may land in, and what was last written.
SourcePlace	Where in its document a Kernel’s failure is written.
Refusal	A change of several documents refused: the document at fault and why.
Diagnostic	What is wrong with a document, and where when known. The position is data an interface hands an agent as is.
Fix	A change that mends a diagnostic: using written as a use item of document (use "{using}";), so the document sees what it names.

Enumerations

Name	Brief
history::Origin	How a change arrived. The session holds no identities.
history::Change	What changed.
overrides::Kind	What a source reads or writes: one file, or a directory.
store::Kind	What is at a path.
Allowance	What the person running a session allows its scene beyond its own directory. Only a command line grants it; the scene never does.
Event	Something the session observed while synchronizing with the filesystem.

Traits

Name	Brief
store::Later	A file being read off the caller’s thread (Store::read_later).
store::Arrived	A file read whole, held where it was read into, its bytes taken as they are needed.
store::Store	Files by path, read and written whole.

Functions

Function	Brief
fn large(module: &Validated) -> Option<String>	What makes a Kernel large, when it is (LARGE): the words it carries through its branches, the structs they are, and the functions that carry most, each with the calls that reach it.
fn large_past(module: &Validated, limit: u64) -> Option<String>	large, past limit words.
fn idle(store: &dyn Store, graph: &Graph, published: impl IntoIterator<Item = (PathBuf, Vec<KernelId>)>) -> Vec<(PathBuf, Vec<KernelId>)>	The Kernels each document of a scene publishes that no node of its graph uses, by document: each is compiled and prepared with the scene all the same. A package’s are left out: they are its verbs, used or not.
fn check_document(store: &dyn Store, path: &Path, show_ir: bool) -> Checked	Checks that the document at path parses, lowers with what it reaches, compiles with the documents it uses, binds each node to its Kernel’s ports (entelechy_graph::binding_fault), and orders its graph. show_ir also reports each Kernel’s accounted IR.
fn check_document_with(store: &dyn Store, path: &Path, show_ir: bool, overrides: &Overrides) -> Checked	check_document, the scene’s inputs and outputs placed as overrides say (--input, --output): a name it does not read or write from a file is a problem.
fn first_counted_against(module: &Module) -> bool	Whether module compares its element with its first input’s count (element() < count(first), as a join of two rows does): a test that, run over that input (a node with no domain), is always decided the same way.
fn defaulted_domain(node: &Node, manifest: &Manifest, counted: bool) -> Option<String>	What to say of a node with no domain, which runs over its first input, when its Kernel compares its element with that input’s count (counted): the elements past it, which such a test is for, are never run, as a join’s second input would not be.
fn named(name: &str) -> Result<&'static Device, String>	The device named name, or why there is none: the nearest name the table knows, when one is near.
fn fault(name: &str, shape: Shape, schema: &Schema) -> Option<String>	Why device name does not take a Field of shape and schema from an output, or None when it does.
fn feed_fault(name: &str, ty: &str) -> Option<String>	Why device name does not feed an input declared ty, or None when it does.
fn declared(ty: &str, bytes: bool) -> Option<(Shape, Option<Schema>)>	The shape and, where the element is one of the language’s own kept as its words, the element layout of a Field declared ty (aliases resolved): Image is a Grid of Vec4; with bytes, a Rows of Int unless the element says how its bytes are kept.
fn digest(text: &str) -> u64	A text’s FNV-1a digest, stable across builds and platforms. It names a document’s version and a Kernel’s source.
fn table_elements(graph: Option<&Graph>, runtime: &Runtime) -> BTreeMap<String, TableElement>	For each scene input a node reads, the element the first node reading it (in the graph’s order) lays it out as; an input no published Kernel reads has none.
fn kind_of(files: &Files, name: &str) -> Option<Kind>	What the input or output name of files reads or writes: a file or a directory; None where none is named so.
fn parse_binding(flag: &str, binding: &str) -> Result<(String, PathBuf), String>	name=path, as --input and --output take it.
fn lock(reads: &Mutex<Reads>) -> MutexGuard<'_, Reads>	The reads, whatever a panicking holder left.
fn read_document(store: &dyn Store, path: &Path) -> Result<String, String>	A document’s text: the file at path, else, for a path through a package’s name, the file inside that package.
fn locate_document(store: &dyn Store, path: &Path) -> Result<(PathBuf, String), String>	A placed document: where its file is (its canonical path, one for one file however a placement writes or reaches it, said from the working directory when it lies under it) and its text.
fn file_at(store: &dyn Store, path: &Path) -> PathBuf	Where a file or directory named by path is: there, else, for a path through a package’s name (text.entpkg/font.png), inside that package; a document’s and every read’s alike (placed_reads).
fn package_manifest(store: &dyn Store, manifest: &Path) -> Result<PackageDecl, String>	A checked package manifest: it declares a package whose language and IR versions this Entelechy supports.
fn used_documents(store: &dyn Store, base: &Path, uses: &[Use]) -> Result<Vec<PathBuf>, String>	Every document a use list reaches, recursively, each once, dependencies first. A name is one package: two packages of one name in the reach are refused, naming both.
fn declarations_for(store: &dyn Store, base: &Path, uses: &[Use], own: Own<'_>) -> Result<Declarations, String>	The declarations a document’s use items bring in, recursively. Functions, structs and types are scoped by document: a name reaches what its own document declares, or else the one declaration of that name in the documents it uses (an identical struct or type declared by several is one). own is what the document that uses declares itself; each declaration it sees by a name keeps the name, and any other of that name is renamed name@path (see scoped and scoped_types), each gathered declaration naming what its own document sees.
fn declarations_within(store: &dyn Store, origin: Option<&Path>, base: &Path, uses: &[Use], own: Own<'_>) -> Result<Declarations, String>	As declarations_for, for a document at origin, so a use back to it reports as a cycle.
fn named_id(kernel: &Kernel) -> Result<KernelId, Diagnostic>	The id a Kernel outside a node names for itself.
fn map<T: Sync, R: Send>(items: &[T], f: impl Fn(&T) -> R + Sync) -> Vec<R>	f of each item, in the items’ order, on as many threads as there are cores.
fn parse_allow(text: &str) -> Result<Allowance, String>	Parses an allowance given on a command line: file.read=<dir>, file.write=<dir>, file.delete=<dir>, clipboard.read or clipboard.write.

Constants

Name	Type	Value	Brief
check::LARGE	u64	5_000	The words a Kernel may carry through its branches before it is said to be large (entelechy_ir::carried): a device’s compiler takes long over more (seconds, past in proportion), or fails on it.
devices::CLIPBOARD	&str	"clipboard"	The system clipboard: text, put on it after a commit that changed it, and read from it when it changes.
devices::PROGRESS	&str	"progress"	The Kernels the session watches preparing and the scene they are for.
devices::SOUND	&str	"sound"	The sound card: a frame’s samples.
devices::POINTER	&str	"pointer"	The system’s pointer: its picture.
devices::POINTER_TIP	&str	"pointer_tip"	The pixel of the pointer’s picture it points with.
devices::DEVICES	[Device; 5]	_	Every device, in the order a refusal lists them.
inputs::COPY_LEAST	u64	_	The fewest bytes of an input’s Host copy that are let go once the input is on a device.
package::LAYOUT	[Part; 6]	_	The parts of a package directory, and how one is found by name.
sources::PACKAGE_VERSION	u32	1	The format of an .entpkg archive and of a package’s manifest.

Type aliases

Name	Type	Brief
sources::Declarations	Declarations	Declarations a document shares: structs, type aliases, functions.
store::FetchFn	dyn Fn(&Path, usize, &mut [u8]) -> Result<usize> + Send + Sync	Reads a file kept elsewhere into out from byte from on, answering the bytes read (fewer where the file ends first), or an error. A read from the start reads the file anew; one further on may be answered from what the last read of that file found, as such a file does not change.
store::FetchLaterFn	dyn Fn(&Path) -> Box<dyn Later> + Send + Sync	Starts reading a file kept elsewhere off the caller’s thread (Store::read_later).

Re-exports

paths_spelled

check::Checked

crates/interface/documents/src/check.rs#L119

What checking a document found: the lines to report, in order.

Properties

Name	Type	Description
lines	Vec<(bool, String)>	Each line, and whether it is a problem.
fixes	Vec<(String, Fix)>	The change that mends a problem, by the problem’s line, where one change does.

Methods

Function	Description
fn problems(&self) -> usize	How many problems were found.

Implemented traits: Debug, Default

---

devices::Port

crates/interface/documents/src/devices.rs#L10

A structure of Field a device takes or gives.

Properties

Name	Type	Description
says	&'static str	What it is, as a refusal says it.

Methods

Function	Description
fn fits(&self, shape: Shape, schema: &Schema) -> bool	Whether a Field of shape and schema is one.

---

devices::Device

crates/interface/documents/src/devices.rs#L26

A device: what an output gives it (takes) and what it feeds an input (gives), either or both.

Properties

Name	Type	Description
name	&'static str	Its name, as a scene writes it after to or =.
takes	Option<Port>	What an output gives it; None when no output goes to it.
gives	Option<Port>	What it feeds an input; None when no input reads it.
every_frame	bool	Whether it shows what it takes every frame (the window’s company), rather than carrying it out once after a commit.

---

history::Record

crates/interface/documents/src/history.rs#L112

A change and where the world was when it happened.

Properties

Name	Type	Description
revision	u64	The revision it made.
after_frames	u64	How many frames the revision before it ran.
wall	u64	Seconds since the Unix epoch.
origin	Origin	Where it came from.
change	Change	What it was.

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

---

history::Attempt

crates/interface/documents/src/history.rs#L127

A refused attempt, which changed nothing.

Properties

Name	Type	Description
revision	u64	The revision it was refused at.
frame	u64	The frame within it.
wall	u64	Seconds since the Unix epoch.
origin	Origin	Where it came from.
subject	String	The document or Kernel it was about.
why	String	Why.
source	Option<u64>	The source it tried, by digest, when it sent one.

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

---

history::History

crates/interface/documents/src/history.rs#L146

The session’s memory of change.

Methods

Function	Description
fn position(&self) -> (u64, u64)	The world’s position: its revision and the frames run in it.
fn ran(&mut self)	An evaluation committed.
fn taken_back(&mut self, frames: u64)	Evaluations answered as committed were taken back.
fn published(&mut self, id: &KernelId, to: Generation, source: &str, origin: Origin)	A Kernel was published with source.
fn retired(&mut self, id: &KernelId, origin: Origin)	A Kernel left.
fn scene(&mut self, text: &str, loaded: &[(PathBuf, String)], origin: Origin)	The scene rebuilt from text, with its other documents loaded; the texts are kept, the others’ only when new to their path.
fn documents(&mut self, written: &[(PathBuf, String)], origin: Origin)	Documents a compose wrote, whose texts are kept.
fn changed(&mut self, change: Change, origin: Origin)	Anything else that changed the world.
fn refused(&mut self, subject: String, why: String, source: Option<&str>, origin: Origin)	An attempt refused.
fn changes(&self, since: u64) -> impl Iterator<Item = &Record>	The changes after since, oldest first.
fn attempts(&self, since: u64) -> impl Iterator<Item = &Attempt>	The attempts refused at or after revision since, oldest first.
fn scene_text(&self, digest: u64) -> Option<&str>	A scene document a remembered change loaded, by digest; Kernel sources are excluded.
fn document_text(&self, path: &Path, digest: u64, scene: bool) -> Option<&str>	A text the document at path had, by digest, when a remembered compose wrote it or a remembered scene change loaded it.
fn source_of(&self, id: &KernelId, generation: Generation) -> Option<&str>	The source a Kernel had at generation, when a remembered change published it.

Implemented traits: Clone, Default

---

inputs::TableElement

crates/interface/documents/src/inputs/mod.rs#L42

The element a data table input is read as: the name of each number it holds and the layout, as the Kernel reading the input lays them out; and how its port keeps them, narrow where it says so (Int as u8).

Methods

Function	Description
fn takes(&self, schema: &Schema) -> bool	Whether a Field of schema is what the Kernel reading the input takes.

Implemented traits: Clone, Debug, PartialEq, StructuralPartialEq

---

inputs::Declared

crates/interface/documents/src/inputs/mod.rs#L59

What a scene declares of its inputs: its graph, the files and directories they are read from, and the element each data table is read as (table_elements).

Properties

Name	Type	Description
graph	Option<&'a Graph>	The scene’s graph, when one is built.
files	&'a Files	The files and directories its inputs are read from.
tables	&'a BTreeMap<String, TableElement>	The element each data table is read as.
unread	&'a [PathBuf]	Files read as absent, whatever the disk holds: what a replay’s scene saved for itself and has not written in this run.

---

inputs::Inputs

crates/interface/documents/src/inputs/mod.rs#L190

The inputs of a scene and the Fields they hold.

Methods

Function	Description
fn chunk_handles(&self) -> impl Iterator<Item = (String, Handle)> + '_	The Field of each file in that a fields node holds to join, by the node and the file’s path: near: b.field.
fn field_node_saw(&self, node: &FieldsNode, handle: Handle) -> bool	Whether fields node node last read its paths from handle.
fn give_field_paths(&mut self, store: &dyn Store, readable: &dyn Fn(&Path) -> Result<(), String>, node: &FieldsNode, handle: Handle, paths: Result<Vec<String>, String>, runtime: &mut Runtime)	Gives fields node node the paths paths spell (read from the Field handle): a file no longer named is let go, one newly named asked for, taken in by a sync once it is in. Refused whole, the paths before staying, where a path is not one under the directory or is not readable; reported by the next sync.
fn file_node_saw(&self, node: &FilesNode, handle: Handle) -> bool	Whether files node node last read its paths from handle.
fn give_paths(&mut self, store: &dyn Store, readable: &dyn Fn(&Path) -> Result<(), String>, node: &FilesNode, handle: Handle, paths: Result<Vec<String>, String>, host: &mut Host)	Gives files node node the paths paths spell (read from the Field handle): the files they name read again when they differ from the last; what fails is reported by the next sync.
fn font_saw(&self, font: &FontNode, handle: Handle) -> bool	Whether font node font was last given handle’s characters.
fn give_codes(&mut self, font: &FontNode, handle: Handle, codes: Result<Vec<i32>, String>, host: &mut Host)	Gives font node font the characters codes (read from the Field handle): its glyphs again when they differ from the last; what fails is reported by the next sync.
fn select_frames(&mut self, store: &dyn Store, host: &mut Host, time: f64)	Loads frame floor(time * rate), wrapping, for each frames input. An unreadable frame is reported by the next sync and the input keeps its frame.
fn set_background(&mut self, enabled: bool)	Makes checks after an input’s first off the frames: each is taken in by the first sync after it is done, the text held until then. As the session’s replacements, never in a replay or a run, which take every check in at once.
fn handles(&self) -> &BTreeMap<String, Handle>	The Field each input holds, by name.
fn watched(&self) -> impl Iterator<Item = PathBuf> + '_	The files and directories the inputs are read from.
fn hold(&mut self, host: &mut Host, name: &str, handle: Handle)	Makes handle what input name holds, releasing what it held.
fn holds(&self, name: &str) -> bool	Whether name holds a Field.
fn sync(&mut self, store: &Arc<dyn Store>, declared: &Declared<'_>, readable: &dyn Fn(&Path) -> Result<(), String>, runtime: &mut Runtime, events: &mut Vec<Event>) -> Vec<Handle>	Syncs inputs to what the scene declares: reads new or changed files, lists directories, writes texts, forgets undeclared inputs. Answers the inputs read now that went on the device as they were read, their Host copies let go (put_on_device).
fn start_fed_over(&mut self, files: &Files, host: &mut Host)	Forgets what the frames gave the font and files nodes, as a scene just opened holds them: each font node the glyphs of no codes; each files node no paths, its directory listed again and its opened empty at the next sync; each fields node no paths.
fn take_frame_events(&mut self) -> Vec<Event>	Frame failures since the last call.

Implemented traits: Default

---

kernels::Kernels

crates/interface/documents/src/kernels.rs#L87

The ledger of published Kernels by the document that owns each.

Methods

Function	Description
fn refused(&self, id: &KernelId) -> Option<&str>	Why id’s document could not publish it, when it was refused.
fn owner(&self, id: &KernelId) -> Option<&Path>	The document that publishes id, if a document does.
fn keep(&self) -> Kept	A copy to restore, beside the runtime’s registry, when a published change is refused.
fn put_back(&mut self, kept: Kept, runtime: &mut Runtime)	Restores what Kernels::keep kept, discarding pending changes.
fn ids_of(&self, path: &Path) -> Vec<KernelId>	The Kernels document path has published.
fn documents(&self) -> Vec<PathBuf>	Every document that has published, or tried to.
fn stamps(&self) -> impl Iterator<Item = (&Path, Option<Stamp>)>	Every document with the stamp it was last read at.
fn preparing(&self) -> bool	Whether a change is still being prepared, to publish at a later sync.
fn retire_kernel(&mut self, id: &KernelId, runtime: &mut Runtime) -> bool	Retires a Kernel of any owner; returns whether it was registered.
fn unoptimized(&self, id: &KernelId, source: &str) -> Option<Written>	The Kernel its document holds compiled unoptimized, where each value is written, and the document it is written in, when the version running is the one the document wrote (source, the version’s); None when no document owns it, a source published apart replaced it, or it fails to compile alone.

Implemented traits: Default

---

kernels::Kept

crates/interface/documents/src/kernels.rs#L212

A copy of the ledger to restore whole (Kernels::put_back).

---

kernels::Written

crates/interface/documents/src/kernels.rs#L909

A Kernel as its document writes it: unoptimized, with where each value is written.

Methods

Function	Description
fn compiled(kernel: &Kernel, id: &KernelId, path: Option<PathBuf>) -> Option<Written>	kernel, published as id, compiled unoptimized, written in path.
fn module(&self) -> &Validated	The module it compiled to.
fn place_of(&self, function: Option<&str>, value: ValueId) -> Option<SourcePlace>	Where the failure a trace found is written: its value value in the function it failed in, function (None the entry).

---

overrides::Overrides

crates/interface/documents/src/overrides.rs#L12

Paths given for a scene’s inputs and outputs, by name.

Properties

Name	Type	Description
inputs	BTreeMap<String, PathBuf>	Inputs: a file-backed input reads the path given; an external the scene leaves to its caller is bound to the file (Session::bind_external).
outputs	BTreeMap<String, PathBuf>	Outputs written to files write to the path given.

Methods

Function	Description
fn is_empty(&self) -> bool	Whether nothing is given.
fn apply(&self, files: &mut Files, externals: &[String]) -> Result<Vec<(String, PathBuf)>, String>	files with each input and output given here reading and writing the path given; a files node is given its directory by its id. An input given that no file-backed input is named must be one of externals (the caller binds it); returned so. Any other name given is refused, naming the scene’s file-backed inputs and outputs.

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

---

package::Part

crates/interface/documents/src/package.rs#L9

One part of a package, as the session reads it.

Properties

Name	Type	Description
name	&'static str	Its name.
shape	&'static str	How it is written or where it lies.
doc	&'static str	What the session makes of it, one or two sentences.

---

reads::Reads

crates/interface/documents/src/reads.rs#L16

The directories a session may read under.

Methods

Function	Description
fn restrict(&mut self) -> Result<(), String>	Holds reads to the documents’ directories, the package directories and those Reads::allow allowed. Callable only before the first sync, so the readable set is the first-loaded scene’s directories.
fn allow(&mut self, store: &dyn Store, dir: &Path) -> Result<(), String>	Allows files in dir and under it to be read.
fn revoke(&mut self, store: &dyn Store, dir: &Path)	Takes back reads from dir that Reads::allow gave.
fn wants_directories(&self) -> bool	Whether a sync is to hand Reads::settle the scene’s directories: where reads are held, until they are fixed. Where they are not, no read is checked against them, so they are not worked out at all.
fn settle(&mut self, store: &dyn Store, read_from: &[PathBuf])	Takes the directories the scene’s documents are in or use and its inputs read from, once a sync has read it; where reads are held, only the first time, and where they are not, never, as nothing is checked against them.
fn check(&self, store: &dyn Store, path: &Path) -> Result<(), String>	Whether path may be read: where it resolves to is inside a directory the first-loaded scene’s documents are in or use or its inputs read from, a package directory, or an allowed directory.

Implemented traits: Debug, Default

---

reads::Held

crates/interface/documents/src/reads.rs#L149

A store whose reads are held to Reads.

Methods

Function	Description
fn new(inner: Arc<dyn Store>, reads: Arc<Mutex<Reads>>) -> Self	inner, read where reads allows.

Implemented traits: Store

---

scene::Scene

crates/interface/documents/src/scene.rs#L23

A scene document and what was built from it.

Methods

Function	Description
fn new(store: Arc<dyn Store>, root: &Path, library: Option<&Path>) -> Self	A scene read through store, its documents under root, with library, when given, added to the document’s uses.
fn read_from(&self) -> Vec<PathBuf>	The directories the scene reads: the root’s, its placed graphs’, each used directory, each used file’s parent, and the parent of every document those use in turn, with the package it lies in.
fn store(&self) -> &Arc<dyn Store>	Where its documents are read from.
fn root(&self) -> &Path	The directory its documents are under.
fn text(&self) -> Option<&str>	The root’s text the running graph was lowered from.
fn placed(&self) -> impl Iterator<Item = (&Path, Option<Stamp>)>	The graph documents the running scene places, with the stamp each was read at.
fn files(&self) -> &Files	The scene’s file inputs and outputs, where the caller places them.
fn written(&self) -> &Files	The scene’s file inputs and outputs as its documents write them.
fn bound(&self) -> &[(String, PathBuf)]	Externals the caller binds to files (crate::overrides::Overrides).
fn overrides(&self) -> &Overrides	The parameters and bindings set from outside the document.
fn place(&mut self, overrides: Overrides) -> Result<(), String>	Places the scene’s inputs and outputs as overrides say, the running scene’s at once and every scene read after; refused, nothing changes. Before a scene is read, kept for its first read.
fn graph(&self) -> Option<&Graph>	The running graph, once a scene has loaded.
fn shared_graph(&self) -> Option<&Arc<Graph>>	The running graph, shared: the evaluator knows it unchanged while it holds it.
fn params(&self) -> &BTreeMap<String, Value>	The graph’s parameters as they now stand.
fn declared_param(&self, name: &str) -> Result<Option<&GraphParam>, String>	The param name a loaded scene declares; one it does not is refused, saying why. None before a scene loads, which holds any.
fn set_param(&mut self, name: &str, value: Value) -> Result<(), String>	Overrides a graph parameter; see Session::set_param.
fn clear_params(&mut self)	Drops every parameter override, each back at the scene’s default; a param that sizes the graph relowers the document on the next sync.
fn sync(&mut self, kernels: &mut Kernels, runtime: &mut Runtime, events: &mut Vec<Event>, readable: &dyn Fn(&Path) -> Result<(), String>, apart: bool)	Reads every changed document the root reaches and hands their Kernels to kernels. A changed library rereads the root, whose Kernels inherit its declarations. apart lets a changed root be lowered on another thread, said by a later sync; otherwise it is lowered here, and one lowered apart is waited for.
fn check(&self, text: &str, readable: &dyn Fn(&Path) -> Result<(), String>, granted: &dyn Fn(&Validated) -> Result<(), Diagnostic>) -> Result<(), Diagnostic>	Whether text as the root lowers to a complete graph and all its own Kernels compile and are granted. Writes, publishes and runs nothing; see Session::check_scene.
fn check_in(&self, store: &dyn Store, text: &str, readable: &dyn Fn(&Path) -> Result<(), String>, granted: &dyn Fn(&Validated) -> Result<(), Diagnostic>) -> Result<(), Diagnostic>	Scene::check, its documents read from store.
fn keep(&self) -> Kept	A copy of the running scene, for a refused change to restore from memory.
fn put_back(&mut self, kept: Kept, stamp: Option<Stamp>)	Restores the scene Scene::keep kept, the root read at stamp, regardless of the text on disk; drops any staged scene.
fn take_superseded(&mut self) -> bool	Whether a staged scene was superseded since the last call.
fn waiting(&self) -> bool	Whether a staged scene waits for its Kernels, or documents it uses compile off the frames before it is read again.
fn wait(&mut self, kernels: &mut Kernels, runtime: &mut Runtime, events: &mut Vec<Event>)	Waits until every prepared change, the scene’s included, has published or been refused.
fn compiling(&self) -> bool	Whether library documents are being read and compiled on another thread, to publish at a later sync.
fn land_lowering(&mut self, kernels: &mut Kernels, runtime: &mut Runtime, events: &mut Vec<Event>)	Waits for a root being lowered on another thread and reads it on, so what is judged by the newest scene read does not hang on the thread’s timing.
fn wait_compiled(&mut self)	Waits until the library documents being compiled, and the root being lowered, are done, for the next sync to publish.
fn prepare_source(&self, source: &str, kernels: &Kernels, runtime: &Runtime) -> Result<Candidate, Diagnostic>	Prepares a one-Kernel document unpublished; see Session::prepare_source.
fn compile_source(&self, source: &str, kernels: &Kernels) -> Result<Validated, Diagnostic>	Compiles a one-Kernel document as Scene::prepare_source does.
fn resolve_source(&self, source: &str) -> Result<Kernel, Diagnostic>	source, one Kernel, as Scene::compile_source reads it: its own and used declarations, then the scene’s shared ones.

---

scene::Kept

crates/interface/documents/src/scene.rs#L87

The running scene, kept to be put back whole (Scene::put_back).

---

store::Stamp

crates/interface/documents/src/store.rs#L21

A file’s version as read; it changes whenever the file does.

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

---

store::Parsed

crates/interface/documents/src/store.rs#L188

Documents parsed once per stamp: a document read again unchanged is not parsed again; and what is worked out of them once, by content, for every session reading through the store.

Implemented traits: Clone, Debug, Default

---

store::Disk

crates/interface/documents/src/store.rs#L300

The process’s file system, and the directories packages are found in by name, as whoever opened the session gave them.

Methods

Function	Description
fn with_packages(packages: Vec<PathBuf>) -> Self	The file system, finding packages by name in packages.

Implemented traits: Clone, Debug, Default, Store

---

store::Memory

crates/interface/documents/src/store.rs#L608

Files handed in by the caller, kept in memory. A path is its name with . and .. folded; a directory is any path a file is under; every file has one name.

Methods

Function	Description
fn with_fetch(fetch: Arc<FetchFn>) -> Self	A store whose files may be kept elsewhere, read through fetch.
fn fetching_later(self, later: Arc<FetchLaterFn>) -> Self	This store reading its files kept elsewhere off the caller’s thread through later (Store::read_later).
fn put(&self, path: &Path, bytes: Vec<u8>)	Puts a file at path; the next sync reads it as a changed file.
fn put_elsewhere(&self, path: &Path, bytes: usize)	Puts a file of bytes bytes at path whose bytes stay where they are kept, read through the store’s fetch whenever the file is; the next sync reads it as a changed file.

Implemented traits: Debug, Default, Store

---

store::Kept

crates/interface/documents/src/store.rs#L796

A store whose writes are kept beside base and never reach it: each file written, removed or renamed through it is held here, everything else read as base has it. What a replay that allows writes runs over, so a run changes nothing on disk and every run starts from the same files.

Methods

Function	Description
fn new(base: Arc<dyn Store>) -> Self	base, its writes to be kept.

Implemented traits: Store

---

store::Overlay

crates/interface/documents/src/store.rs#L975

A store seen through texts not yet written: each of texts read as if it stood at its path (new files and the directories they would make included), everything else as base has it. What a compose of several documents is checked against before any reaches base; nothing is written through it.

Methods

Function	Description
fn new(base: &'a dyn Store, texts: &[(PathBuf, String)]) -> Self	base seen through texts.

Implemented traits: Store

---

writes::Writes

crates/interface/documents/src/writes.rs#L20

The directories writes may land in, and what was last written.

Methods

Function	Description
fn allow(&mut self, store: &dyn Store, dir: &Path) -> Result<(), String>	Allows writes into the existing directory dir and under it.
fn allow_deletes(&mut self, store: &dyn Store, dir: &Path) -> Result<(), String>	Allows files in the existing directory dir and under it to be removed and renamed.
fn revoke(&mut self, store: &dyn Store, dir: &Path)	Takes back writes, removals and renames in dir that Writes::allow and Writes::allow_deletes gave.
fn allow_file(&mut self, store: &dyn Store, path: &Path) -> Result<(), String>	Allows a write to the one file path, wherever it is.
fn ask(&mut self, writes: &[Write], outputs: &[(String, Handle)], runtime: &Runtime)	Asks for the words of each output written to a file that the evaluation just made changed, outputs as it left them by name: the copy waits behind that evaluation’s work alone, so once it is confirmed (Writes::after) the words are in hand and writing them waits for no frame made since.
fn after(&mut self, store: &dyn Store, writes: &[Write], outputs: &[(String, Handle)], runtime: &mut Runtime, names: &dyn Fn(&str) -> Result<Vec<String>, String>)	Writes every output a confirmed evaluation changed, outputs as it left them by name; names gives an output’s element’s numbers by name, which a data table names its columns by.
fn author(&self, store: &dyn Store, path: &Path) -> Option<&str>	The output that wrote the file at path, while the file is as it wrote it.
fn take_events(&mut self) -> Vec<Event>	What was written or refused since the last call.
fn place(&self, store: &dyn Store, path: &Path) -> Result<PathBuf, String>	Where a caller’s write to path (save, export) lands, if it is an allowed file or inside an allowed directory. .. and links are resolved before the test.

Implemented traits: Default

---

SourcePlace

crates/interface/documents/src/lib.rs#L39

Where in its document a Kernel’s failure is written.

Properties

Name	Type	Description
path	PathBuf	The document.
line	u32	Its line, 1-based.
column	u32	Its column in characters, 1-based.
function	Option<String>	The function it is in, None the Kernel’s body.

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

---

Refusal

crates/interface/documents/src/lib.rs#L102

A change of several documents refused: the document at fault and why.

Properties

Name	Type	Description
path	PathBuf	The document, by its one name.
diagnostic	Diagnostic	Why, and where in it.

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

---

Diagnostic

crates/interface/documents/src/lib.rs#L112

What is wrong with a document, and where when known. The position is data an interface hands an agent as is.

Properties

Name	Type	Description
message	String	What is wrong.
at	Option<(u32, u32)>	Line and column, from 1, when the problem has a place.
fix	Option<Box<Fix>>	The change that mends it, when one change does: data an agent hands back as a compose.

Methods

Function	Description
fn new(message: impl Into<String>) -> Self	A diagnostic with no place.
fn at(span: Span, message: impl Into<String>) -> Self	A diagnostic at a place in its document; one whose span is no place has none.

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

---

Fix

crates/interface/documents/src/lib.rs#L125

A change that mends a diagnostic: using written as a use item of document (use "{using}";), so the document sees what it names.

Properties

Name	Type	Description
document	PathBuf	The document to change, by its one name.
using	String	The path its new use item names, spelled as the document would.
text	Option<String>	The document whole with the item added, when the refused change wrote it: what is on disk is not what the change asked for.

Methods

Function	Description
fn item(&self) -> String	The use item the fix adds.

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

---

history::Origin

crates/interface/documents/src/history.rs#L32

How a change arrived. The session holds no identities.

Variants

Name	Description
Document(PathBuf)	A document the session reads, changed on disk.
Protocol(String)	A protocol request’s channel: stdin, socket 3, websocket 4.
Local	The program running the session: a command line, a window’s keys.
Output(String)	The scene itself: its output of this name wrote the document after a committed evaluation, and the document is as it wrote it.

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

---

history::Change

crates/interface/documents/src/history.rs#L46

What changed.

Variants

Name	Description
Published { id: KernelId, from: Option<Generation>, to: Generation, source: u64 }	A Kernel was published.
Retired { id: KernelId, from: Option<Generation> }	A Kernel left the registry.
Scene { document: u64, documents: Vec<(PathBuf, u64)> }	The scene graph was rebuilt from a document version (History::source), with the other documents of the scene it loaded at versions not remembered before.
Documents { written: Vec<(PathBuf, u64)> }	Documents of the scene were written by a compose, each by its one name and its text, by digest (History::source).
Param { name: String }	A graph param was set.
Written { node: String, port: String }	A port’s committed state was written from outside.
Reset	Committed state was forgotten.
ResetPort { node: String, port: String }	One port’s committed state was forgotten.
Restored { revision: u64, laws: bool }	A snapshot’s world was restored.

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

---

overrides::Kind

crates/interface/documents/src/overrides.rs#L23

What a source reads or writes: one file, or a directory.

Variants

Name	Description
File	A file (= "a.field", bytes "a.txt", to "a.png").
Directory	A directory (files, checks and outline on a directory, frames, to files).

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

---

store::Kind

crates/interface/documents/src/store.rs#L12

What is at a path.

Variants

Name	Description
File	A file.
Dir	A directory.

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

---

Allowance

crates/interface/documents/src/lib.rs#L63

What the person running a session allows its scene beyond its own directory. Only a command line grants it; the scene never does.

Variants

Name	Description
FileRead(PathBuf)	Inputs may be read from files in this directory and under it.
FileWrite(PathBuf)	Outputs may be written to files in this directory and under it.
FileDelete(PathBuf)	Files in this directory and under it may be removed and renamed by an output to files.
ClipboardRead	An input = clipboard may read the system’s clipboard.
ClipboardWrite	An output to clipboard may write the system’s clipboard.

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

---

Event

crates/interface/documents/src/lib.rs#L204

Something the session observed while synchronizing with the filesystem.

Variants

Name	Description
Preparing { path: PathBuf, id: KernelId }	A changed Kernel compiled and is being prepared; the running version stays until a later sync publishes the replacement.
Published { path: PathBuf, id: KernelId, generation: Generation }	A Kernel was compiled and published.
Rejected { path: PathBuf, error: Diagnostic }	A changed Kernel was refused; the previous version stays.
Retired { path: PathBuf, id: KernelId }	A Kernel disappeared from its document.
SceneLoaded	The scene document was re-read and its graph rebuilt.
Text { name: String, chars: usize }	An input’s text was written into the Host as rows of character codes.
Loaded { name: String, path: PathBuf, detail: String }	An input’s file was read into the Host.
SceneRejected(Diagnostic)	The changed scene document was refused; the previous graph stays.
Absent { name: String, path: PathBuf }	An input’s file is absent; the input reads its fallback.
Wrote { output: String, path: PathBuf, bytes: usize }	An output was written to its file after a committed evaluation.
Removed { output: String, path: PathBuf }	A file was removed by an output’s operations.
Renamed { output: String, from: PathBuf, to: PathBuf }	A file was renamed by an output’s operations.
WriteRefused { output: String, path: PathBuf, why: String }	An output’s write was refused; said once until the reason changes or a write succeeds.
Routed { node: String, backend: &'static str, why: String }	A node runs off the session’s main backend, and why. Said once per placement change.
Large { path: PathBuf, id: KernelId, why: String }	A Kernel just published is large (large): what it carries through its branches, the structs and the functions that carry most. Said for each version published so.
Unrun { node: String, why: String }	A node with no domain whose Kernel compares its element with its first input’s count, so the elements past that count, which the test is for, are never run (check::defaulted_domain). Said once when the scene loads, and again when it changes.
BroughtUnchanged { output: String, path: PathBuf, bytes: usize, frames: u32 }	A large output written to a file was brought to the Host as a new Field on each of frames evaluations in a row and found each time to be the file as it stands: the node it reads runs every time and makes the same, and each time costs the Field fetched, encoded and hashed. Said once, until the output is written or left as it was.
Idle { path: PathBuf, ids: Vec<KernelId> }	Kernels a document of the scene publishes and no node uses, each compiled and prepared all the same. Said when the scene loads, and again when they change.

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

---

store::Later

crates/interface/documents/src/store.rs#L56

A file being read off the caller’s thread (Store::read_later).

Methods

Function	Description
fn poll(&mut self) -> Option<Result<Box<dyn Arrived>>>	The file once it is in, or why it is not; None while it is still on its way. Answers once.

---

store::Arrived

crates/interface/documents/src/store.rs#L64

A file read whole, held where it was read into, its bytes taken as they are needed.

Methods

Function	Description
fn len(&self) -> usize	Its length in bytes.
fn is_empty(&self) -> bool	Whether it holds no bytes.
fn start(&self, bytes: usize) -> Vec<u8>	Its first bytes bytes, or all of it when it is shorter.
fn words(&self, from: usize) -> (Vec<u32>, usize)	Its bytes from from on as little-endian words, the last padded with zeros, and how many bytes they are.

---

store::Store

crates/interface/documents/src/store.rs#L115

Files by path, read and written whole.

Methods

Function	Description
fn read(&self, path: &Path) -> Result<Vec<u8>>	The file’s bytes.
fn read_start(&self, path: &Path, bytes: usize) -> Result<Vec<u8>>	The file’s first bytes bytes, or all of it when shorter: what its header says, before the rest is read.
fn read_words(&self, path: &Path, from: usize) -> Result<(Vec<u32>, usize)>	The file’s bytes from from on as little-endian words, the last padded with zeros, and how many bytes they are: a body of words read as words, never held as bytes beside them where the store can read it a piece at a time.
fn read_later(&self, path: &Path) -> Box<dyn Later>	Reads the file off the caller’s thread where the store can, else now: what the caller asks after says when it is in.
fn write(&self, path: &Path, bytes: &[u8]) -> Result<()>	Replaces the file atomically, making the directories it needs.
fn remove(&self, path: &Path) -> Result<()>	Removes the file.
fn rename(&self, from: &Path, to: &Path) -> Result<()>	Renames the file from to to, making the directories to needs.
fn remove_empty(&self, dir: &Path) -> Result<()>	Removes the directory when it holds nothing; leaves it otherwise.
fn kind(&self, path: &Path) -> Option<Kind>	What is at path, if anything.
fn list(&self, dir: &Path) -> Result<Vec<PathBuf>>	What a directory holds, unordered.
fn stamp(&self, path: &Path) -> Option<Stamp>	The file’s stamp now, if it exists.
fn canonical(&self, path: &Path) -> Result<PathBuf>	The file’s one name under any spelling; an error when absent.
fn whole(&self, path: &Path) -> PathBuf	path made whole: absolute where the store has a current directory, . and .. folded, links unread.
fn packages(&self) -> &[PathBuf]	The directories a use by name looks for a package in, in order; none unless the store was given some.
fn parsed(&self) -> Option<&Parsed>	Where the store keeps documents it has parsed, if it keeps them.
fn stamps_directories(&self) -> bool	Whether a directory’s stamp changes whenever what it holds does (an entry added, removed or renamed).
fn sync_begins(&self)	A sync begins, or another run that walks the same files from every document (a check): until it ends, the store may answer a path’s kind, stamp and resolved path as it first found them. A file changed meanwhile is seen by the next run. Runs nest; the last to end ends them.
fn sync_ends(&self)	The run ends: every path is looked at afresh.

---