@mark1russell7/coeval 0.16.0 → 0.18.0

package/README.md

@@ -29,10 +29,10 @@ A plan evaluates many times without a trace. `evaluate(machine, doc)` gives the
 | World | `lookupKind`, `Kind`, `Namespace`, `PartShape`, `ScopeRule`, `CapsRule`, `VerbEffects`, `effectsOfVerb` | The kinds, with their contracts: the shape of the parts, the type of the data, the kinds that a position permits, the names that a kind binds, the capabilities that it gives its parts, and its effects for each verb. A namespace can have a fallback kind |
 | Merges | `mergeWorlds`, `mergeMachines`, `MergeError`, `restrictWorld`, `restrictMachine` | The one merge of worlds and machines. Equal entries merge, and namespaces merge key by key. Each other clash is a conflict, unless the later part names its path in `replaces`. A restriction removes entries and their code. [`docs/COMPOSITION.md`](https://github.com/mark1russell7/coeval/blob/main/docs/COMPOSITION.md) shows each mode of composition |
 | Ladder | `ask` | The evaluator of a verb: the own entry, then the kind, then the default. Each verb has this ladder, also `deref` and `step` |
-| References | `resolve`, `HostThing`, `Navigator` | A path from a root of the context: `self`, `names`, `world`, `event` or `caps`. A step document can have computed parts, and a walker can give the code of its failure. The optional `has` of a host thing tells a field that holds `undefined` from a missing field |
+| References | `resolve`, `HostThing`, `Navigator` | A path from a root of the context: `self`, `names`, `world`, `event` or `caps`. A step document can have computed parts, and a walker can give the code of its failure. The optional `has` of a host thing, of a `deref` code and of a walker input tells a field that holds `undefined` from a missing field |
 | Plans | `prepare`, `planner`, `evaluate`, `run`, `PrepareOptions`, `EvalOptions`, `EvaluateOptions`, `RunOptions`, `PlanRunOptions` | A document compiles one time into code. An evaluator is a function or a compiler. The option `perform` of `evaluate` and `plan.evaluate` is a mock: it answers each effect at once. The option `verb` of `prepare`, `evaluate` and `run` asks the ladder for another verb than `eval`, for example `format` |
 | The run side | `run`, `Runner`, `Perform`, `Effect`, `permits`, `narrow`, `partCaps` | Effects in order, parts at the same time, capabilities that only narrow, and an abort. The kernel narrows the capabilities of each part by the contract of its kind. Each effect has a stable `address` and its `outcome` |
-| Record and replay | `recorder`, `replayer`, `ReplayLog`, `ReplayEntry`, `ReplaySettle`, `ReplayOptions`, `Journal`, `JOURNAL` | A recorder logs each effect of a run with its address and its outcome, and the order of the waits. A replayer answers each effect from the log, and a different request gives `#REPLAY!` |
+| Record and replay | `recorder`, `replayer`, `encodeLog`, `decodeLog`, `ReplayLog`, `ReplayEntry`, `ReplaySettle`, `ReplayOptions`, `ReplayLogJson`, `ReplayEntryJson`, `ReplayResultJson`, `ReplayErrorJson`, `ReplayExceptionJson`, `ReplayPartJson`, `ReplayPartsJson`, `Journal`, `JOURNAL` | A recorder logs each effect of a run with its address and its outcome, and the order of the waits. A replayer answers each effect from the log for each run, and a different request gives `#REPLAY!`. `encodeLog` writes a log as JSON for a golden file |
 | Errors | `Result`, `EvalError`, `Failure`, `failures` | An error value has a code, a reason, a place and a cause. An evaluation does not throw |
 | The static kit | `walk`, `refsOf`, `mapRefs`, `check`, `CheckOptions`, `checkWorld`, `WorldIssue` | The documents of a document in linear time, its free references, and its problems before a run, each with its place and its JSON path. A check narrows the capabilities as a run does, and it asks the hook `permits` of the machine. The hook `known` of a machine names the unknown operations. The option `verb` of `check` checks the evaluators and the declared effects of another verb. The option `types` also checks the value types. The option `run` finds a runner that can wait under a parent that cannot wait. `checkWorld` finds each kind without an evaluator for a verb of the language, before a document exists |
 | The effects | `effectsOf`, `checkLatent`, `EffectsOptions` | The effects of a document that can reach the host: the declared effects, without the effects that a mask or a rule `only` removes. A host can grant exactly these capabilities. `checkLatent` compares the latent effects that a procedure declares with its body (D27) |
@@ -40,8 +40,8 @@ A plan evaluates many times without a trace. `evaluate(machine, doc)` gives the
 | Trees | `STD_WORLD` (`panel`, `box`), `nearestWalker` | The decorated tree: each field of a node is an attribute that evaluates on demand, one time in an evaluation. A sibling is a path through the parent, and a cycle gives `#CYCLE!` with its chain |
 | The formula kit | `formulaMachine`, `FormulaProfile`, `formulaKnown`, `formulaFacts` | The shared constructs `lit`, `ref`, `record`, `list`, `let`, `fn`, `call`, `if`, `and`, `or`, and the namespaces `ops` and `ext`. A profile gives the rules of a language, for example how the errors of two parts combine. A language extends the kit through the merge. An address gives a thing, not its value |
 | The codec of values | `encodeValue`, `decodeValue`, `decodeDomain`, `DomainCodec`, `STD_EXT` | A host value as one term document. JSON stays as it is. `ext.number`, `ext.undefined` and `ext.domain` hold the other values. A domain gives its codec (D40) |
-| The syntax kit | `parse`, `print`, `syntaxFormat`, `SyntaxProfile`, `SyntaxOperator`, `SyntaxIssue`, `STD_SYNTAX` | One parser and one printer for the text of a language. A profile gives the operators, the literals, the references and the calls. `parse` gives documents or issues with spans, and `print` gives text that `parse` reads back (D41) |
-| One meaning | `agree`, `reference`, `formulaDefinitions`, `STD_DEFINITIONS`, `generate`, `TierInput` | A reference interpreter that compiles nothing, and `agree`, which compares a plan with it and with the second tier of a language. Each tier gets the mock `perform` and the `verb` of `agree`. `generate` builds random documents from the kind contracts |
+| The syntax kit | `parse`, `print`, `syntaxFormat`, `SyntaxProfile`, `SyntaxOperator`, `SyntaxIssue`, `STD_SYNTAX`, `WORLD_SYNTAX` | One parser and one printer for the text of a language. A profile gives the operators, the literals, the references and the calls. `parse` gives documents or issues with spans, and `print` gives text that `parse` reads back (D41). `WORLD_SYNTAX` is the profile of `STD_WORLD` (D64) |
+| One meaning | `agree`, `reference`, `formulaDefinitions`, `STD_DEFINITIONS`, `generate`, `TierInput` | A reference interpreter that compiles nothing, and `agree`, which compares a plan with it and with the second tier of a language. Each tier gets the mock `perform` and the `verb` of `agree`. `generate` builds random documents from the kind contracts. `agreeRun` compares runs, and the free reads of the plan and of the reference run. The option `reads` of `reference` and `referenceRun` records the reads of the reference (D67) |
 | Conformance | `conforms`, `ConformOptions`, `Finding`, `Obligation`, `ConformProbe` | The obligations of host code, examined for one evaluator or runner with probe parts and a probe runtime. Each finding names the obligation, the reason and a probe that shows it (D36) |
 | Early cutoff | `sameResult` | A safe equality of two results for a schedule. Plain JSON compares by structure, and each other object only as itself. Two errors need the same code, reason and place |
 | Reads | `verifyReads`, `Read`, `ReadsCheck`, `VerifyOptions` | The option `reads` of an evaluation records each path that it resolves, with what the path reached. `verifyReads` resolves each free read again in a new context, and it tells if the old result stays valid (D26) |
@@ -79,9 +79,14 @@ const machine = mergeMachines(formulaMachine(profile), syntaxFormat(algebra)); /
 
 - A larger `prec` binds more tightly. `assoc` is `left` (the default), `right`, `none` or `flat`. A `flat` chain gives one document with each term.
 - `kind` is the type of the document, with dots between the keys. A call `name(args)` applies `ops.name`, and a call form in `calls.forms` makes a construct.
+- `header.bind` is the symbol of a header name, for example `=` in `total = 2 + 3`. A form name can have dots, for example `math.product`.
+- `args` of a form tells how its arguments make the value. `named` reads `panel(width: 300)` as a record, and `literal` reads `text("big")` as data.
+- A step in parentheses after a dot is a document, for example `self.parent.(nearest(type: "panel")).width`.
+- `literals.envelopes` names the kinds of the data envelopes, and `wrap` of a form names the arguments that take a document. A literal there gets its envelope, thus `list(1)` is `list(number(1))`.
 - A bare name is a path from `refs.bare`. A name in `refs.roots` starts a path. `refs.patterns` add other references, for example `A1`, with `read` and `write`.
 - An issue of `parse` has `offset`, `length` and `message`. Show it at its span in an editor.
 - Test your profile with a round trip: `parse(print(doc))` gives `doc` again. `STD_SYNTAX` is the standard profile of the formula kit.
+- `WORLD_SYNTAX` is the profile of `STD_WORLD`, for example `seq(a = 1 + 2, log(a))`. Is your world the standard world with more kinds? Spread `WORLD_SYNTAX` and add your forms to `calls.forms`.
 
 ## Check the code of a language