@mark1russell7/coeval 0.16.0 → 0.17.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +9 -4
- package/build/index.d.ts +522 -171
- package/build/index.d.ts.map +1 -1
- package/build/index.js +2352 -296
- package/build/index.js.map +1 -1
- package/package.json +1 -1
- package/src/agree.ts +128 -16
- package/src/conform.ts +49 -5
- package/src/deref.ts +76 -11
- package/src/evaluate.ts +113 -19
- package/src/facts.ts +113 -78
- package/src/formula.ts +55 -10
- package/src/index.ts +23 -1
- package/src/merge.ts +46 -14
- package/src/reference.ts +90 -14
- package/src/replay.ts +964 -18
- package/src/static.ts +2 -2
- package/src/stdlib.ts +55 -2
- package/src/syntax.ts +357 -52
- package/src/types.ts +443 -16
package/build/index.d.ts
CHANGED
|
@@ -348,8 +348,31 @@ interface Context {
|
|
|
348
348
|
readonly event: Thing;
|
|
349
349
|
readonly caps: readonly Cap[];
|
|
350
350
|
}
|
|
351
|
-
/**
|
|
352
|
-
|
|
351
|
+
/**
|
|
352
|
+
* The code of a `deref` evaluator: it answers one step of a path on a document of its kind. A field that holds
|
|
353
|
+
* `undefined` also gives `undefined`. The optional function `has` of the code tells the two cases apart
|
|
354
|
+
* (DEREF.KIND-UNDEFINED). A host gives the code a `has` with `Object.assign(code, { has })`.
|
|
355
|
+
*/
|
|
356
|
+
interface DerefCode {
|
|
357
|
+
/**
|
|
358
|
+
* This function answers one step on a document.
|
|
359
|
+
*
|
|
360
|
+
* @param doc - The document.
|
|
361
|
+
* @param key - The key of the step.
|
|
362
|
+
* @returns What the step reaches, or `undefined` when it reaches nothing.
|
|
363
|
+
*/
|
|
364
|
+
(doc: Envelope, key: Key): Thing | undefined;
|
|
365
|
+
/**
|
|
366
|
+
* This optional function tells if a document has a field for a key. The kernel asks it only when the code gives
|
|
367
|
+
* `undefined`. Then `true` tells that the field holds `undefined`. A code without `has` reads `undefined` as a
|
|
368
|
+
* missing field, as a host thing does (DEREF.HOST-UNDEFINED).
|
|
369
|
+
*
|
|
370
|
+
* @param doc - The document.
|
|
371
|
+
* @param key - The key of the step.
|
|
372
|
+
* @returns `true` when the document has the field.
|
|
373
|
+
*/
|
|
374
|
+
readonly has?: (doc: Envelope, key: Key) => boolean;
|
|
375
|
+
}
|
|
353
376
|
/**
|
|
354
377
|
* The result of a step document: what it reached, or the reason of a failure. A failure can give its code, for
|
|
355
378
|
* example `#REF!` for a position outside a space. The default code is `#N/A`.
|
|
@@ -370,13 +393,24 @@ interface WalkInput {
|
|
|
370
393
|
readonly here: Thing;
|
|
371
394
|
readonly context: Context;
|
|
372
395
|
/**
|
|
373
|
-
* This function answers one step on a thing, through the ladder.
|
|
396
|
+
* This function answers one step on a thing, through the ladder. A field that holds `undefined` also gives
|
|
397
|
+
* `undefined`. The function `has` tells the two cases apart (DEREF.WALKER-UNDEFINED).
|
|
374
398
|
*
|
|
375
399
|
* @param thing - The thing.
|
|
376
400
|
* @param key - The key.
|
|
377
401
|
* @returns What the step reaches, or `undefined`.
|
|
378
402
|
*/
|
|
379
403
|
deref(thing: Thing, key: Key): Thing | undefined;
|
|
404
|
+
/**
|
|
405
|
+
* This optional function tells if a step on a thing reaches a field, through the ladder. A walker needs it only
|
|
406
|
+
* when `deref` gives `undefined`. Then `true` tells that the field holds `undefined` (DEREF.WALKER-UNDEFINED).
|
|
407
|
+
* Each resolution of the kernel gives it. The function asks the ladder again, thus a host thing answers the step again.
|
|
408
|
+
*
|
|
409
|
+
* @param thing - The thing.
|
|
410
|
+
* @param key - The key.
|
|
411
|
+
* @returns `true` when the step reaches a field, also a field that holds `undefined`.
|
|
412
|
+
*/
|
|
413
|
+
has?(thing: Thing, key: Key): boolean;
|
|
380
414
|
/**
|
|
381
415
|
* This optional function records one hop inside the walk (HOP.EACH-STEP). The resolution gives it only when it
|
|
382
416
|
* records hops. The hop of the whole walk comes after these hops, as before.
|
|
@@ -564,6 +598,23 @@ interface Domain {
|
|
|
564
598
|
* standard extension `ext.domain`. A domain without a codec has no such document.
|
|
565
599
|
*/
|
|
566
600
|
readonly codec?: DomainCodec;
|
|
601
|
+
/**
|
|
602
|
+
* The full list of the members of the domain, when the domain holds few values, for example `true` and `false` of
|
|
603
|
+
* `bool` (TYPE.FITS-FINITE). `fits` reads it: a base type with a list fits a type that holds each member of the list.
|
|
604
|
+
* The language keeps the list complete: each member of the domain is in the list. A value that fails a test of the
|
|
605
|
+
* domain does not count. The check reads a list of at most 64 values.
|
|
606
|
+
*/
|
|
607
|
+
readonly values?: readonly unknown[];
|
|
608
|
+
/**
|
|
609
|
+
* The covers of the domain (TYPE.FITS-COVER, D85). A cover is a list of domains under this domain, and its domains
|
|
610
|
+
* together hold each member of this domain. An example is a domain of negative numbers and a domain of the other
|
|
611
|
+
* numbers as a cover of `number`. `fits` reads it: a base type fits a union when each domain of a cover fits it.
|
|
612
|
+
*
|
|
613
|
+
* A split of a record also narrows a field of the domain to each domain of a cover (D90).
|
|
614
|
+
* The language keeps each cover true, and `fits` trusts it, as it trusts `values`. A cover that is empty, or that
|
|
615
|
+
* names this domain or a name that is not under it, does not count.
|
|
616
|
+
*/
|
|
617
|
+
readonly covers?: readonly (readonly string[])[];
|
|
567
618
|
}
|
|
568
619
|
/**
|
|
569
620
|
* The codec of a domain: it writes a member of the domain as JSON, and it reads the JSON again (D40). Both functions
|
|
@@ -628,9 +679,33 @@ export declare function member(value: unknown, type: ValueType, domains?: Readon
|
|
|
628
679
|
* field is `unknown`.
|
|
629
680
|
* - A function fits when it has the same or fewer parameters, each expected parameter fits its parameter, and its
|
|
630
681
|
* result fits.
|
|
631
|
-
*
|
|
632
|
-
*
|
|
633
|
-
*
|
|
682
|
+
* - The finite rule comes after these rules (TYPE.FITS-FINITE). A type with at most 64 members fits when each member
|
|
683
|
+
* is a member of `expected`. Thus `bool` fits `{ "one": [true, false] }`.
|
|
684
|
+
* - A base type has few members when its domain or a parent declares `values`, as `null`, `undefined` and `bool` do.
|
|
685
|
+
* A union, a `one`, a closed record of such types and a list of `never` also have few members.
|
|
686
|
+
* - The cover rule comes next (TYPE.FITS-COVER, D85). A base type fits a union or a `one` when each domain of a cover
|
|
687
|
+
* fits. The cover is in `covers` of a domain of its line. Each domain of a cover is under the covered
|
|
688
|
+
* domain. Thus a cover of `number` by `neg` and `nonneg` gives `number` a fit against `neg | nonneg`.
|
|
689
|
+
* - The split rule comes last (D84). An open record, or a closed record with more than 64 members, splits a field with
|
|
690
|
+
* few members over a union. A closed record also splits over a `one`. Each record of the split narrows the field to
|
|
691
|
+
* one member, and each record must fit.
|
|
692
|
+
* Thus `{ "record": { "a": "bool" } }` fits a union of a record for each value of `a`.
|
|
693
|
+
* - A split also narrows a field of a record in a field, by its path (TYPE.FITS-PATH, D89). The fields of the record
|
|
694
|
+
* split first, then the paths of each next depth, in the order of the keys. A path goes into a record without a
|
|
695
|
+
* finite list. Thus `{a: {x: bool}}` fits the union of `{a: {x: true}}` and `{a: {x: false}}`.
|
|
696
|
+
* - A type split comes after each value split (TYPE.FITS-SPLIT-TYPE, D90). A field of a base type with a valid cover in
|
|
697
|
+
* its line splits into the domains of the first such cover. A field of a union without a finite list splits into its
|
|
698
|
+
* members. A case that does not fit splits again at its path, by the same rules. A base type there uses only a
|
|
699
|
+
* cover of its own domain. Thus `{a: number}` fits `{a: neg} | {a: nonneg}` when `neg` and `nonneg` cover `number`.
|
|
700
|
+
*
|
|
701
|
+
* The relation is sound: a member of `found` is a member of `expected` when no `unknown` is in the types
|
|
702
|
+
* (TYPE.FITS-SOUND). The finite rule trusts `values`, and the cover rule trusts `covers`. Thus a list without a member
|
|
703
|
+
* or a false cover makes the relation unsound for that domain.
|
|
704
|
+
*
|
|
705
|
+
* The relation is not complete. A split builds at most 64 records, with each split inside its work at each depth. A
|
|
706
|
+
* type split uses one cover of a field, not each cover of its line. A domain without `values` gets no finite rule, and
|
|
707
|
+
* neither does a type with more than 64 members that is not a record. The cover rule tests at most 64 domains of
|
|
708
|
+
* covers. The function does not throw.
|
|
634
709
|
*
|
|
635
710
|
* @param found - The type that a part has.
|
|
636
711
|
* @param expected - The type that the position needs.
|
|
@@ -1542,9 +1617,12 @@ interface StaticRead {
|
|
|
1542
1617
|
readonly address: boolean;
|
|
1543
1618
|
/** The path of the reference: its root and its steps. */
|
|
1544
1619
|
readonly path: readonly Json[];
|
|
1545
|
-
/**
|
|
1620
|
+
/**
|
|
1621
|
+
* The keys from the root document to the reference document, through the parts. A read of an equation has the
|
|
1622
|
+
* place of the first document of its tree kind (FACTS.EQUATIONS).
|
|
1623
|
+
*/
|
|
1546
1624
|
readonly place: readonly Key[];
|
|
1547
|
-
/** The keys from the root JSON value to the reference document. */
|
|
1625
|
+
/** The keys from the root JSON value to the reference document, or to the document of the kind for an equation. */
|
|
1548
1626
|
readonly at: readonly Key[];
|
|
1549
1627
|
}
|
|
1550
1628
|
/** The static facts of one document (D24). They depend only on the document and the machine, not on a context. */
|
|
@@ -1592,9 +1670,11 @@ interface FactsOptions {
|
|
|
1592
1670
|
*
|
|
1593
1671
|
* - `reads`: each free reference, with the root and the keys of its path. A read under a lazy part has the mark
|
|
1594
1672
|
* `lazy`, for example a read in a branch of `if`. A read after a step document has `exact: false`. A kind that
|
|
1595
|
-
* declares `reads` adds a read of each of its roots at each document of the kind.
|
|
1673
|
+
* declares `reads` adds a read of each of its roots at each document of the kind. The first document of a tree
|
|
1674
|
+
* kind also gets the lazy reads of the equations of its kind (FACTS.EQUATIONS). A read from `self` or from a name
|
|
1675
|
+
* of a rung is not one of them, because it is not free (READS.EQUATION).
|
|
1596
1676
|
* - `side` and `effects`: from the contract of each kind.
|
|
1597
|
-
* - `pure`: each kind declares `pure`, and the document has no effect and is not volatile.
|
|
1677
|
+
* - `pure`: each kind declares `pure`, also in an equation, and the document has no effect and is not volatile.
|
|
1598
1678
|
* - `volatile`: a kind, an operation or a step document declares `volatile`, or the host marks a read.
|
|
1599
1679
|
*
|
|
1600
1680
|
* The hook `facts` of the machine answers for a name that a fallback kind covers, for example an operation. Its
|
|
@@ -1762,9 +1842,11 @@ interface Journal {
|
|
|
1762
1842
|
*
|
|
1763
1843
|
* @param all - The address of the `all`.
|
|
1764
1844
|
* @param waiting - The indices of the items that wait.
|
|
1845
|
+
* @param before - The number of the waits of this `all` that settled before this call. The kernel gives it, thus a
|
|
1846
|
+
* replayer keeps no state of a run (RUN.REPLAY-RUNS). An older copy of the kernel does not give it.
|
|
1765
1847
|
* @returns The index of an item that waits, or `undefined` for the order of the host.
|
|
1766
1848
|
*/
|
|
1767
|
-
readonly next?: (all: string, waiting: readonly number[]) => number | undefined;
|
|
1849
|
+
readonly next?: (all: string, waiting: readonly number[], before?: number) => number | undefined;
|
|
1768
1850
|
}
|
|
1769
1851
|
/**
|
|
1770
1852
|
* The runtime of one evaluation or run. Compiled code gets it with the context, and asks it to resolve paths and
|
|
@@ -2350,25 +2432,34 @@ export declare class MergeError extends Error {
|
|
|
2350
2432
|
*/
|
|
2351
2433
|
constructor(conflicts: readonly MergeConflict[]);
|
|
2352
2434
|
}
|
|
2353
|
-
/** What `extendDomain` adds to a domain: more parents,
|
|
2435
|
+
/** What `extendDomain` adds to a domain: more parents, the types of more steps, and more covers. */
|
|
2354
2436
|
interface DomainExtension {
|
|
2355
2437
|
/** The names of the parents to add. A member of the domain then also passes the test of each new parent. */
|
|
2356
2438
|
readonly under?: readonly string[];
|
|
2357
2439
|
/** The types of the steps to add. A step with the key of an earlier step replaces its type. */
|
|
2358
2440
|
readonly steps?: Readonly<Record<string, ValueType>>;
|
|
2441
|
+
/**
|
|
2442
|
+
* The covers to add (TYPE.FITS-COVER, D85). A cover that the domain has already does not change. The language that
|
|
2443
|
+
* adds a cover keeps it true, because `fits` trusts it.
|
|
2444
|
+
*/
|
|
2445
|
+
readonly covers?: readonly (readonly string[])[];
|
|
2359
2446
|
}
|
|
2360
2447
|
/**
|
|
2361
|
-
* This function makes a part of a merge that adds parents or
|
|
2362
|
-
* example is a domain of another language. The part reads the domain from the merge before it
|
|
2363
|
-
* copy with the same test and
|
|
2364
|
-
*
|
|
2448
|
+
* This function makes a part of a merge that adds parents, steps or covers to a domain of an earlier part
|
|
2449
|
+
* (TYPE.PARENTS). An example is a domain of another language. The part reads the domain from the merge before it
|
|
2450
|
+
* (`prev`). It gives a copy with the same test, summary, codec and list of values, and it names `["domains", name]`
|
|
2451
|
+
* in `replaces` (D17).
|
|
2452
|
+
* A domain of the kernel that the earlier parts do not name comes from `STD_DOMAINS`.
|
|
2453
|
+
*
|
|
2454
|
+
* An extension does not change the codec. Thus each member keeps its document (D80).
|
|
2365
2455
|
*
|
|
2366
2456
|
* A new parent adds its test to the domain (TYPE.MEMBER). Thus `fits` stays sound, but a value that fails the test of
|
|
2367
2457
|
* the parent is no longer a member. The language that adds the parent keeps the signatures of the other language
|
|
2368
|
-
* true. A
|
|
2458
|
+
* true. A new parent of a domain in a cover of another domain can make that cover false (D85). A name without a
|
|
2459
|
+
* domain gives an empty part, and `typeIssues` reports each use of that name.
|
|
2369
2460
|
*
|
|
2370
2461
|
* @param name - The name of the domain.
|
|
2371
|
-
* @param more - The parents and the
|
|
2462
|
+
* @param more - The parents, the steps and the covers to add.
|
|
2372
2463
|
* @returns The part, as a function of the merge before it.
|
|
2373
2464
|
*/
|
|
2374
2465
|
export declare function extendDomain(name: string, more: DomainExtension): (prev: Machine) => MachinePart;
|
|
@@ -2565,12 +2656,222 @@ export declare function partsOf(world: World, value: unknown, declaredType?: str
|
|
|
2565
2656
|
*/
|
|
2566
2657
|
export declare function pathMatches(path: readonly Key[], pattern: readonly Key[]): boolean;
|
|
2567
2658
|
//#endregion
|
|
2659
|
+
//#region src/syntax.d.ts
|
|
2660
|
+
/** The place of an operator: before its term, between two terms, or after its term. */
|
|
2661
|
+
type SyntaxFixity = "prefix" | "infix" | "postfix";
|
|
2662
|
+
/**
|
|
2663
|
+
* The grouping of a chain of one infix operator. `left` reads `a - b - c` as `(a - b) - c`, and `right` reads
|
|
2664
|
+
* `a ^ b ^ c` as `a ^ (b ^ c)`. `none` refuses a chain. `flat` reads a chain as one document with each term.
|
|
2665
|
+
*/
|
|
2666
|
+
type SyntaxAssoc = "left" | "right" | "none" | "flat";
|
|
2667
|
+
/** One operator of a syntax profile. */
|
|
2668
|
+
interface SyntaxOperator {
|
|
2669
|
+
/** The text of the operator, for example `+`, `<>` or `and`. A word operator is a plain name. */
|
|
2670
|
+
readonly symbol: string;
|
|
2671
|
+
/** The place of the operator. */
|
|
2672
|
+
readonly fixity: SyntaxFixity;
|
|
2673
|
+
/** The precedence. A larger number binds more tightly. */
|
|
2674
|
+
readonly prec: number;
|
|
2675
|
+
/** The grouping of a chain of an infix operator. The default is `left`. */
|
|
2676
|
+
readonly assoc?: SyntaxAssoc;
|
|
2677
|
+
/** The type of the document that the operator makes, with dots between the keys, for example `ops.add` or `and`. */
|
|
2678
|
+
readonly kind: string;
|
|
2679
|
+
}
|
|
2680
|
+
/** The literal rules of a syntax profile. */
|
|
2681
|
+
interface SyntaxLiterals {
|
|
2682
|
+
/** `false` removes the decimal numbers. The default is `true`. */
|
|
2683
|
+
readonly numbers?: boolean;
|
|
2684
|
+
/** `true` puts a minus sign right before a digit into the number, where a term starts. The default is `true`. */
|
|
2685
|
+
readonly signed?: boolean;
|
|
2686
|
+
/** The texts: the quote and the escape of a quote. `false` removes the texts. The default is `"` with backslashes. */
|
|
2687
|
+
readonly strings?: false | {
|
|
2688
|
+
readonly quote?: "\"" | "'";
|
|
2689
|
+
readonly escape?: "backslash" | "double";
|
|
2690
|
+
};
|
|
2691
|
+
/** The words that are literals, with their values. The default is `true`, `false` and `null`. */
|
|
2692
|
+
readonly words?: Readonly<Record<string, unknown>>;
|
|
2693
|
+
/**
|
|
2694
|
+
* The kinds of the data envelopes of a text, a number and a truth value, with dots between the keys (K159, D65). A
|
|
2695
|
+
* literal in a place that takes a document gets its envelope. Such a place is the whole text, the document after a
|
|
2696
|
+
* header name, or an argument that its form names in `wrap`. Thus `list(1)` gives `list(number(1))`, and `print`
|
|
2697
|
+
* writes the envelope as the bare literal there. Without this field, a literal stays bare in each place.
|
|
2698
|
+
*/
|
|
2699
|
+
readonly envelopes?: SyntaxEnvelopes;
|
|
2700
|
+
}
|
|
2701
|
+
/** The kinds of the data envelopes of the literals (K159, D65). A literal without a kind stays bare, for example `null`. */
|
|
2702
|
+
interface SyntaxEnvelopes {
|
|
2703
|
+
/** The kind of a finite number, for example `number`. */
|
|
2704
|
+
readonly number?: string;
|
|
2705
|
+
/** The kind of a text, for example `text`. */
|
|
2706
|
+
readonly text?: string;
|
|
2707
|
+
/** The kind of a truth value, for example `bool`. */
|
|
2708
|
+
readonly bool?: string;
|
|
2709
|
+
}
|
|
2710
|
+
/** A reference syntax that a pattern gives, for example the address `A1` of a cell. */
|
|
2711
|
+
interface SyntaxRefPattern {
|
|
2712
|
+
/** The pattern of the text of a reference. The parser tries it before a name. */
|
|
2713
|
+
readonly pattern: RegExp;
|
|
2714
|
+
/** This function gives the path of the reference from its text. */
|
|
2715
|
+
readonly read: (text: string) => readonly Key[];
|
|
2716
|
+
/** This function gives the text of a path, or `undefined` when the pattern does not write the path. */
|
|
2717
|
+
readonly write: (path: readonly unknown[]) => string | undefined;
|
|
2718
|
+
}
|
|
2719
|
+
/** The reference syntax of a syntax profile. */
|
|
2720
|
+
interface SyntaxRefs {
|
|
2721
|
+
/** The root of a bare name. The default is `names`. Thus `x` is the path `["names", "x"]`. */
|
|
2722
|
+
readonly bare?: string;
|
|
2723
|
+
/** The roots that the text names first, for example `self.price`. The default is `self`, `world`, `event` and `caps`. */
|
|
2724
|
+
readonly roots?: readonly string[];
|
|
2725
|
+
/** `false` removes the field steps `a.b`. The default is `true`. */
|
|
2726
|
+
readonly fields?: boolean;
|
|
2727
|
+
/** The patterns of other references. */
|
|
2728
|
+
readonly patterns?: readonly SyntaxRefPattern[];
|
|
2729
|
+
}
|
|
2730
|
+
/** A call form: a name with arguments in parentheses that makes a construct, for example `if(test, then, else)`. */
|
|
2731
|
+
interface SyntaxForm {
|
|
2732
|
+
/**
|
|
2733
|
+
* The name in the text: a plain name, or plain names with dots between them, for example `math.product` (K161). A
|
|
2734
|
+
* name with dots needs the field steps of `refs.fields`, and its first key is not a word operator.
|
|
2735
|
+
*/
|
|
2736
|
+
readonly name: string;
|
|
2737
|
+
/** The type of the document, with dots between the keys. */
|
|
2738
|
+
readonly kind: string;
|
|
2739
|
+
/**
|
|
2740
|
+
* The fields of the value, in the order of the arguments. Without them, the value is the list of the arguments. A
|
|
2741
|
+
* form `named` permits only these keys, and without them it permits each key.
|
|
2742
|
+
*/
|
|
2743
|
+
readonly fields?: readonly string[];
|
|
2744
|
+
/** The smallest number of arguments. The default is the number of the fields, or `0`. Only `list` and `fields` read it. */
|
|
2745
|
+
readonly min?: number;
|
|
2746
|
+
/**
|
|
2747
|
+
* The way that the arguments make the value (D63). The default is `fields` with fields, or `list`.
|
|
2748
|
+
*
|
|
2749
|
+
* - `list`: the value is the list of the arguments, for example `list(1, 2)`.
|
|
2750
|
+
* - `fields`: the arguments go into the fields, in order, for example `if(test, then, else)`.
|
|
2751
|
+
* - `named`: each argument is a key and a document, and the value is a record, for example `panel(width: 300)`.
|
|
2752
|
+
* - `literal`: the one argument is a literal, and the value is its data, for example `text("big")`.
|
|
2753
|
+
*/
|
|
2754
|
+
readonly args?: SyntaxFormArgs;
|
|
2755
|
+
/**
|
|
2756
|
+
* The arguments that take a document (K159, D65): `true` for each argument, or the names of some fields. A literal
|
|
2757
|
+
* in such an argument gets its data envelope of `literals.envelopes`. Without that field, `wrap` changes nothing. A
|
|
2758
|
+
* form `literal` takes no `wrap`, and a form `list` takes only `true`.
|
|
2759
|
+
*/
|
|
2760
|
+
readonly wrap?: boolean | readonly string[];
|
|
2761
|
+
}
|
|
2762
|
+
/** The way that the arguments of a call form make the value of its document (D63). */
|
|
2763
|
+
type SyntaxFormArgs = "list" | "fields" | "named" | "literal";
|
|
2764
|
+
/** The call syntax of a syntax profile. */
|
|
2765
|
+
interface SyntaxCalls {
|
|
2766
|
+
/** The operations that a call `name(args)` can name. `true` permits each name. The default is `true`. */
|
|
2767
|
+
readonly ops?: boolean | readonly string[];
|
|
2768
|
+
/** The call forms of constructs. A form wins over an operation with the same name. */
|
|
2769
|
+
readonly forms?: readonly SyntaxForm[];
|
|
2770
|
+
/** The text between two arguments. The default is `,`. */
|
|
2771
|
+
readonly separator?: string;
|
|
2772
|
+
}
|
|
2773
|
+
/** The text of the header of a document (K157, D62). */
|
|
2774
|
+
interface SyntaxHeader {
|
|
2775
|
+
/**
|
|
2776
|
+
* The symbol between a name and its document, for example `=` in `total = 2 + 3`. The text gives the document the
|
|
2777
|
+
* header `name`. Without the symbol, a document with a name has no text. The symbol is a group of symbols, and no
|
|
2778
|
+
* infix or postfix operator is the symbol or the start of it.
|
|
2779
|
+
*/
|
|
2780
|
+
readonly bind?: string;
|
|
2781
|
+
}
|
|
2782
|
+
/**
|
|
2783
|
+
* The text syntax of a language (D41): an operator table, literal rules, reference syntax and call syntax. `parse`
|
|
2784
|
+
* reads a text into a document, and `print` writes a document as text. The profile is data, thus a site, an editor
|
|
2785
|
+
* and a language read the same rules.
|
|
2786
|
+
*/
|
|
2787
|
+
interface SyntaxProfile {
|
|
2788
|
+
/** The operators. */
|
|
2789
|
+
readonly operators?: readonly SyntaxOperator[];
|
|
2790
|
+
/** The literal rules. */
|
|
2791
|
+
readonly literals?: SyntaxLiterals;
|
|
2792
|
+
/** The reference syntax. */
|
|
2793
|
+
readonly refs?: SyntaxRefs;
|
|
2794
|
+
/** The call syntax. */
|
|
2795
|
+
readonly calls?: SyntaxCalls;
|
|
2796
|
+
/** The text of the header of a document. */
|
|
2797
|
+
readonly header?: SyntaxHeader;
|
|
2798
|
+
/** The deepest nesting that `parse` accepts. The default is `256`. */
|
|
2799
|
+
readonly maxDepth?: number;
|
|
2800
|
+
}
|
|
2801
|
+
/** A problem of a text: its character offset, its length and a message. */
|
|
2802
|
+
interface SyntaxIssue {
|
|
2803
|
+
/** The 0-based character offset of the problem. */
|
|
2804
|
+
readonly offset: number;
|
|
2805
|
+
/** The number of characters of the problem. `0` marks a place between two characters. */
|
|
2806
|
+
readonly length: number;
|
|
2807
|
+
/** The message. */
|
|
2808
|
+
readonly message: string;
|
|
2809
|
+
}
|
|
2810
|
+
/** The result of `parse`: a document, or the problems of the text. */
|
|
2811
|
+
type ParseResult = {
|
|
2812
|
+
readonly ok: true;
|
|
2813
|
+
readonly doc: Json;
|
|
2814
|
+
} | {
|
|
2815
|
+
readonly ok: false;
|
|
2816
|
+
readonly issues: readonly SyntaxIssue[];
|
|
2817
|
+
};
|
|
2818
|
+
/**
|
|
2819
|
+
* The standard syntax of the formula kit. It gives the site and the playground a text form. The operators are
|
|
2820
|
+
* `or`, `and`, `not`, the comparisons, `+ - * / %`, a minus sign and `^`, from the loosest to the tightest. A call
|
|
2821
|
+
* `name(args)` applies the operation `ops.name`. `if(test, then, else)` and `list(items)` make the constructs. The
|
|
2822
|
+
* text `total = 2 + 3` gives the document the header name `total` (D62).
|
|
2823
|
+
*/
|
|
2824
|
+
export declare const STD_SYNTAX: SyntaxProfile;
|
|
2825
|
+
/**
|
|
2826
|
+
* This function reads a text into a document with the rules of a profile (SYNTAX.PARSE). It does not throw for a
|
|
2827
|
+
* bad text. The issue gives the offset, the length and a message (SYNTAX.SPAN).
|
|
2828
|
+
*
|
|
2829
|
+
* @param profile - The syntax profile.
|
|
2830
|
+
* @param text - The text.
|
|
2831
|
+
* @returns The document, or the issues of the text.
|
|
2832
|
+
* @throws {TypeError} The profile is not valid, for example an operator has two entries of the same place.
|
|
2833
|
+
*/
|
|
2834
|
+
export declare function parse(profile: SyntaxProfile, text: string): ParseResult;
|
|
2835
|
+
/**
|
|
2836
|
+
* This function writes a document as text with the rules of a profile (SYNTAX.PRINT). It writes the fewest
|
|
2837
|
+
* parentheses that keep the tree. `parse` reads the text back to the same document (SYNTAX.ROUNDTRIP).
|
|
2838
|
+
*
|
|
2839
|
+
* @param profile - The syntax profile.
|
|
2840
|
+
* @param doc - The document.
|
|
2841
|
+
* @returns The text, or `#VALUE!` at the place of a document that the profile cannot write.
|
|
2842
|
+
* @throws {TypeError} The profile is not valid.
|
|
2843
|
+
*/
|
|
2844
|
+
export declare function print(profile: SyntaxProfile, doc: unknown): Result<string>;
|
|
2845
|
+
/**
|
|
2846
|
+
* This function makes the part of a merge that adds the verb `format` to a machine (D23, D41). Its default writes
|
|
2847
|
+
* each document with the printer of the profile. A part gives its own text through the ladder, thus an own entry or
|
|
2848
|
+
* a kind entry of `format` still wins.
|
|
2849
|
+
*
|
|
2850
|
+
* @param profile - The syntax profile.
|
|
2851
|
+
* @returns The part for `mergeMachines`.
|
|
2852
|
+
*/
|
|
2853
|
+
export declare function syntaxFormat(profile: SyntaxProfile): MachinePart;
|
|
2854
|
+
//#endregion
|
|
2568
2855
|
//#region src/stdlib.d.ts
|
|
2569
2856
|
/**
|
|
2570
2857
|
* The world of the examples: small kinds for numbers, lists, conditions, names, sequences and effects.
|
|
2571
2858
|
* Each kind names an evaluator for `eval` and a view for `view`. The site draws each document with its view.
|
|
2572
2859
|
*/
|
|
2573
2860
|
export declare const STD_WORLD: World;
|
|
2861
|
+
/**
|
|
2862
|
+
* The text syntax of the standard world (K162, D64). The syntax kit (D41) reads it, thus a host of `STD_WORLD` does
|
|
2863
|
+
* not write its own profile. The operators `>`, `+` and `*` make `greater`, `add` and `multiply`. A call form makes
|
|
2864
|
+
* each other kind, and `ref` uses the reference syntax of the kit.
|
|
2865
|
+
*
|
|
2866
|
+
* A literal in a place that takes a document gets its data envelope (K159, D65). Such a place is a part of `if`,
|
|
2867
|
+
* `list`, `seq` or `pure`, the value of `write`, or the whole text. The document after a header name is such a place
|
|
2868
|
+
* too. Thus `list(1, "a")` evaluates to `[1, "a"]`. The forms `add`, `multiply` and `greater` write an operator document that its operator
|
|
2869
|
+
* does not write, for example `add(5)` (K163).
|
|
2870
|
+
*
|
|
2871
|
+
* A host with more kinds spreads this profile and adds its forms to `calls.forms`. `STD_SYNTAX` stays the profile of
|
|
2872
|
+
* the formula kit.
|
|
2873
|
+
*/
|
|
2874
|
+
export declare const WORLD_SYNTAX: SyntaxProfile;
|
|
2574
2875
|
/** The code of the evaluators of the standard world, by name. */
|
|
2575
2876
|
export declare const STD_EVALUATORS: Readonly<Record<string, Evaluator>>;
|
|
2576
2877
|
/** The rungs of the ladder of an attribute, in their order (TREE.LADDER, D42). */
|
|
@@ -2812,6 +3113,9 @@ type ExtFn = (data: Json, context: Context, domains?: Readonly<Record<string, Do
|
|
|
2812
3113
|
* `ext.domain`.
|
|
2813
3114
|
* - `truthy`: the truth of a value for `if`, `and` and `or`. `undefined` is an error `#VALUE!`. The default
|
|
2814
3115
|
* accepts only `true` and `false`.
|
|
3116
|
+
* - `truthType`: the value type of a truth for the own `truthy`, for a check of types (TYPE.TRUTH, D81). A test of
|
|
3117
|
+
* `if` and each term of `and` and `or` must fit it. Without it, the check accepts each type there. A profile without
|
|
3118
|
+
* `truthy` ignores it, because the default truth needs `bool`.
|
|
2815
3119
|
* - `otherwise`: the value of an `if` without `else`. The default is `null`. A profile with this key gives its value,
|
|
2816
3120
|
* also `undefined`.
|
|
2817
3121
|
* - `logic`: what `and` and `or` give: a truth value (the default), or the value that decided.
|
|
@@ -2829,13 +3133,15 @@ type ExtFn = (data: Json, context: Context, domains?: Readonly<Record<string, Do
|
|
|
2829
3133
|
* overloads. An operation without a signature takes and gives `unknown` (TYPE.GRADUAL).
|
|
2830
3134
|
*
|
|
2831
3135
|
* A check of types trusts the signatures. Each operation must give a member of the result of each signature that
|
|
2832
|
-
* its arguments match. The hook `check` must keep each result in that type.
|
|
3136
|
+
* its arguments match. The hook `check` must keep each result in that type. The function `truthy` must give a truth
|
|
3137
|
+
* for each member of `truthType`.
|
|
2833
3138
|
*/
|
|
2834
3139
|
interface FormulaProfile {
|
|
2835
3140
|
readonly ops?: Readonly<Record<string, OpFn>> | ((name: string) => OpFn | undefined);
|
|
2836
3141
|
readonly lazy?: Readonly<Record<string, LazyOp>>;
|
|
2837
3142
|
readonly ext?: Readonly<Record<string, ExtFn>>;
|
|
2838
3143
|
readonly truthy?: (value: unknown) => boolean | undefined;
|
|
3144
|
+
readonly truthType?: ValueType;
|
|
2839
3145
|
readonly otherwise?: unknown;
|
|
2840
3146
|
readonly logic?: "boolean" | "value";
|
|
2841
3147
|
readonly omit?: (error: EvalError) => boolean;
|
|
@@ -2994,151 +3300,6 @@ export declare function encodeValue(machine: Pick<Machine, "domains">, value: un
|
|
|
2994
3300
|
*/
|
|
2995
3301
|
export declare function decodeValue(machine: Machine, doc: unknown): Result;
|
|
2996
3302
|
//#endregion
|
|
2997
|
-
//#region src/syntax.d.ts
|
|
2998
|
-
/** The place of an operator: before its term, between two terms, or after its term. */
|
|
2999
|
-
type SyntaxFixity = "prefix" | "infix" | "postfix";
|
|
3000
|
-
/**
|
|
3001
|
-
* The grouping of a chain of one infix operator. `left` reads `a - b - c` as `(a - b) - c`, and `right` reads
|
|
3002
|
-
* `a ^ b ^ c` as `a ^ (b ^ c)`. `none` refuses a chain. `flat` reads a chain as one document with each term.
|
|
3003
|
-
*/
|
|
3004
|
-
type SyntaxAssoc = "left" | "right" | "none" | "flat";
|
|
3005
|
-
/** One operator of a syntax profile. */
|
|
3006
|
-
interface SyntaxOperator {
|
|
3007
|
-
/** The text of the operator, for example `+`, `<>` or `and`. A word operator is a plain name. */
|
|
3008
|
-
readonly symbol: string;
|
|
3009
|
-
/** The place of the operator. */
|
|
3010
|
-
readonly fixity: SyntaxFixity;
|
|
3011
|
-
/** The precedence. A larger number binds more tightly. */
|
|
3012
|
-
readonly prec: number;
|
|
3013
|
-
/** The grouping of a chain of an infix operator. The default is `left`. */
|
|
3014
|
-
readonly assoc?: SyntaxAssoc;
|
|
3015
|
-
/** The type of the document that the operator makes, with dots between the keys, for example `ops.add` or `and`. */
|
|
3016
|
-
readonly kind: string;
|
|
3017
|
-
}
|
|
3018
|
-
/** The literal rules of a syntax profile. */
|
|
3019
|
-
interface SyntaxLiterals {
|
|
3020
|
-
/** `false` removes the decimal numbers. The default is `true`. */
|
|
3021
|
-
readonly numbers?: boolean;
|
|
3022
|
-
/** `true` puts a minus sign right before a digit into the number, where a term starts. The default is `true`. */
|
|
3023
|
-
readonly signed?: boolean;
|
|
3024
|
-
/** The texts: the quote and the escape of a quote. `false` removes the texts. The default is `"` with backslashes. */
|
|
3025
|
-
readonly strings?: false | {
|
|
3026
|
-
readonly quote?: "\"" | "'";
|
|
3027
|
-
readonly escape?: "backslash" | "double";
|
|
3028
|
-
};
|
|
3029
|
-
/** The words that are literals, with their values. The default is `true`, `false` and `null`. */
|
|
3030
|
-
readonly words?: Readonly<Record<string, unknown>>;
|
|
3031
|
-
}
|
|
3032
|
-
/** A reference syntax that a pattern gives, for example the address `A1` of a cell. */
|
|
3033
|
-
interface SyntaxRefPattern {
|
|
3034
|
-
/** The pattern of the text of a reference. The parser tries it before a name. */
|
|
3035
|
-
readonly pattern: RegExp;
|
|
3036
|
-
/** This function gives the path of the reference from its text. */
|
|
3037
|
-
readonly read: (text: string) => readonly Key[];
|
|
3038
|
-
/** This function gives the text of a path, or `undefined` when the pattern does not write the path. */
|
|
3039
|
-
readonly write: (path: readonly unknown[]) => string | undefined;
|
|
3040
|
-
}
|
|
3041
|
-
/** The reference syntax of a syntax profile. */
|
|
3042
|
-
interface SyntaxRefs {
|
|
3043
|
-
/** The root of a bare name. The default is `names`. Thus `x` is the path `["names", "x"]`. */
|
|
3044
|
-
readonly bare?: string;
|
|
3045
|
-
/** The roots that the text names first, for example `self.price`. The default is `self`, `world`, `event` and `caps`. */
|
|
3046
|
-
readonly roots?: readonly string[];
|
|
3047
|
-
/** `false` removes the field steps `a.b`. The default is `true`. */
|
|
3048
|
-
readonly fields?: boolean;
|
|
3049
|
-
/** The patterns of other references. */
|
|
3050
|
-
readonly patterns?: readonly SyntaxRefPattern[];
|
|
3051
|
-
}
|
|
3052
|
-
/** A call form: a name with arguments in parentheses that makes a construct, for example `if(test, then, else)`. */
|
|
3053
|
-
interface SyntaxForm {
|
|
3054
|
-
/** The name in the text. */
|
|
3055
|
-
readonly name: string;
|
|
3056
|
-
/** The type of the document, with dots between the keys. */
|
|
3057
|
-
readonly kind: string;
|
|
3058
|
-
/** The fields of the value, in the order of the arguments. Without them, the value is the list of the arguments. */
|
|
3059
|
-
readonly fields?: readonly string[];
|
|
3060
|
-
/** The smallest number of arguments. The default is the number of the fields, or `0`. */
|
|
3061
|
-
readonly min?: number;
|
|
3062
|
-
}
|
|
3063
|
-
/** The call syntax of a syntax profile. */
|
|
3064
|
-
interface SyntaxCalls {
|
|
3065
|
-
/** The operations that a call `name(args)` can name. `true` permits each name. The default is `true`. */
|
|
3066
|
-
readonly ops?: boolean | readonly string[];
|
|
3067
|
-
/** The call forms of constructs. A form wins over an operation with the same name. */
|
|
3068
|
-
readonly forms?: readonly SyntaxForm[];
|
|
3069
|
-
/** The text between two arguments. The default is `,`. */
|
|
3070
|
-
readonly separator?: string;
|
|
3071
|
-
}
|
|
3072
|
-
/**
|
|
3073
|
-
* The text syntax of a language (D41): an operator table, literal rules, reference syntax and call syntax. `parse`
|
|
3074
|
-
* reads a text into a document, and `print` writes a document as text. The profile is data, thus a site, an editor
|
|
3075
|
-
* and a language read the same rules.
|
|
3076
|
-
*/
|
|
3077
|
-
interface SyntaxProfile {
|
|
3078
|
-
/** The operators. */
|
|
3079
|
-
readonly operators?: readonly SyntaxOperator[];
|
|
3080
|
-
/** The literal rules. */
|
|
3081
|
-
readonly literals?: SyntaxLiterals;
|
|
3082
|
-
/** The reference syntax. */
|
|
3083
|
-
readonly refs?: SyntaxRefs;
|
|
3084
|
-
/** The call syntax. */
|
|
3085
|
-
readonly calls?: SyntaxCalls;
|
|
3086
|
-
/** The deepest nesting that `parse` accepts. The default is `256`. */
|
|
3087
|
-
readonly maxDepth?: number;
|
|
3088
|
-
}
|
|
3089
|
-
/** A problem of a text: its character offset, its length and a message. */
|
|
3090
|
-
interface SyntaxIssue {
|
|
3091
|
-
/** The 0-based character offset of the problem. */
|
|
3092
|
-
readonly offset: number;
|
|
3093
|
-
/** The number of characters of the problem. `0` marks a place between two characters. */
|
|
3094
|
-
readonly length: number;
|
|
3095
|
-
/** The message. */
|
|
3096
|
-
readonly message: string;
|
|
3097
|
-
}
|
|
3098
|
-
/** The result of `parse`: a document, or the problems of the text. */
|
|
3099
|
-
type ParseResult = {
|
|
3100
|
-
readonly ok: true;
|
|
3101
|
-
readonly doc: Json;
|
|
3102
|
-
} | {
|
|
3103
|
-
readonly ok: false;
|
|
3104
|
-
readonly issues: readonly SyntaxIssue[];
|
|
3105
|
-
};
|
|
3106
|
-
/**
|
|
3107
|
-
* The standard syntax of the formula kit. It gives the site and the playground a text form. The operators are
|
|
3108
|
-
* `or`, `and`, `not`, the comparisons, `+ - * / %`, a minus sign and `^`, from the loosest to the tightest. A call
|
|
3109
|
-
* `name(args)` applies the operation `ops.name`. `if(test, then, else)` and `list(items)` make the constructs.
|
|
3110
|
-
*/
|
|
3111
|
-
export declare const STD_SYNTAX: SyntaxProfile;
|
|
3112
|
-
/**
|
|
3113
|
-
* This function reads a text into a document with the rules of a profile (SYNTAX.PARSE). It does not throw for a
|
|
3114
|
-
* bad text. The issue gives the offset, the length and a message (SYNTAX.SPAN).
|
|
3115
|
-
*
|
|
3116
|
-
* @param profile - The syntax profile.
|
|
3117
|
-
* @param text - The text.
|
|
3118
|
-
* @returns The document, or the issues of the text.
|
|
3119
|
-
* @throws {TypeError} The profile is not valid, for example an operator has two entries of the same place.
|
|
3120
|
-
*/
|
|
3121
|
-
export declare function parse(profile: SyntaxProfile, text: string): ParseResult;
|
|
3122
|
-
/**
|
|
3123
|
-
* This function writes a document as text with the rules of a profile (SYNTAX.PRINT). It writes the fewest
|
|
3124
|
-
* parentheses that keep the tree. `parse` reads the text back to the same document (SYNTAX.ROUNDTRIP).
|
|
3125
|
-
*
|
|
3126
|
-
* @param profile - The syntax profile.
|
|
3127
|
-
* @param doc - The document.
|
|
3128
|
-
* @returns The text, or `#VALUE!` at the place of a document that the profile cannot write.
|
|
3129
|
-
* @throws {TypeError} The profile is not valid.
|
|
3130
|
-
*/
|
|
3131
|
-
export declare function print(profile: SyntaxProfile, doc: unknown): Result<string>;
|
|
3132
|
-
/**
|
|
3133
|
-
* This function makes the part of a merge that adds the verb `format` to a machine (D23, D41). Its default writes
|
|
3134
|
-
* each document with the printer of the profile. A part gives its own text through the ladder, thus an own entry or
|
|
3135
|
-
* a kind entry of `format` still wins.
|
|
3136
|
-
*
|
|
3137
|
-
* @param profile - The syntax profile.
|
|
3138
|
-
* @returns The part for `mergeMachines`.
|
|
3139
|
-
*/
|
|
3140
|
-
export declare function syntaxFormat(profile: SyntaxProfile): MachinePart;
|
|
3141
|
-
//#endregion
|
|
3142
3303
|
//#region src/reference.d.ts
|
|
3143
3304
|
/**
|
|
3144
3305
|
* The definitional code of the reference, by evaluator name. The reference cannot read compiled code, thus each
|
|
@@ -3163,6 +3324,12 @@ interface ReferenceOptions {
|
|
|
3163
3324
|
* each verb by the same rules (VERB.AGREE).
|
|
3164
3325
|
*/
|
|
3165
3326
|
readonly verb?: string;
|
|
3327
|
+
/**
|
|
3328
|
+
* A list that gets each read of a resolution, in its order (REF.READS). A read has the shape of a read of a plan:
|
|
3329
|
+
* the path, what it reached and the mark `free`. The reads of a closure and of an equation of a tree go in the
|
|
3330
|
+
* same list. The reference adds no kept reads, because it has no static reads of a closure.
|
|
3331
|
+
*/
|
|
3332
|
+
readonly reads?: Read[];
|
|
3166
3333
|
}
|
|
3167
3334
|
/** The options of a run of the reference: the options of an evaluation, with the host and a signal (REF.RUN). */
|
|
3168
3335
|
interface ReferenceRunOptions extends ReferenceOptions {
|
|
@@ -3302,6 +3469,11 @@ type Agreement = {
|
|
|
3302
3469
|
readonly ok: true;
|
|
3303
3470
|
readonly result: Result;
|
|
3304
3471
|
readonly effects: readonly Effect[];
|
|
3472
|
+
/**
|
|
3473
|
+
* The free reads of the plan that `agreeRun` compared with the reference run (RUN.AGREES-READS). It is absent
|
|
3474
|
+
* when no read compared, for example in `agree`.
|
|
3475
|
+
*/
|
|
3476
|
+
readonly reads?: readonly Read[];
|
|
3305
3477
|
} | {
|
|
3306
3478
|
readonly ok: false;
|
|
3307
3479
|
readonly tier: Tier;
|
|
@@ -3360,6 +3532,13 @@ interface AgreeRunOptions extends Omit<AgreeOptions, "other" | "perform"> {
|
|
|
3360
3532
|
* The rules of `agree` compare the results and the effects, with their addresses and outcomes. A tier must also
|
|
3361
3533
|
* settle the waits of each `all` in the order of the plan, thus a replay keeps the order of the waits.
|
|
3362
3534
|
*
|
|
3535
|
+
* The reference run must also give the free reads of the plan, in their order (RUN.AGREES-READS). Another replay of
|
|
3536
|
+
* the plan records these reads. A kept read does not compare. When the plan keeps each root, its reads are not known,
|
|
3537
|
+
* and no read compares.
|
|
3538
|
+
*
|
|
3539
|
+
* One replayer of the log serves each tier and the replay for the reads (RUN.AGREES-ONE-REPLAYER). The replayer keeps
|
|
3540
|
+
* no state of a run (RUN.REPLAY-RUNS), thus each tier replays the same log as with a replayer of its own.
|
|
3541
|
+
*
|
|
3363
3542
|
* @param machine - The world, the evaluators and the runners.
|
|
3364
3543
|
* @param doc - The document.
|
|
3365
3544
|
* @param context - The names and the capabilities at the root.
|
|
@@ -3383,8 +3562,10 @@ export declare function agreeRun(machine: Machine, doc: unknown, context?: Conte
|
|
|
3383
3562
|
* - `C8`: compiled code gives the result of code that compiles again at the time of the evaluation.
|
|
3384
3563
|
* - `local`: the code keeps no state from one call to the next.
|
|
3385
3564
|
* - `agree`: compiled code gives the result of its definition for the reference interpreter.
|
|
3565
|
+
* - `truth`: the own `truthy` of a formula profile gives `true` or `false` for each member of its `truthType` (D86).
|
|
3566
|
+
* Only `formula.if`, `formula.and` and `formula.or` of the formula kit get this check.
|
|
3386
3567
|
*/
|
|
3387
|
-
type Obligation = "C1" | "C2" | "C3" | "C4" | "C5" | "C6" | "C7" | "C8" | "local" | "agree";
|
|
3568
|
+
type Obligation = "C1" | "C2" | "C3" | "C4" | "C5" | "C6" | "C7" | "C8" | "local" | "agree" | "truth";
|
|
3388
3569
|
/** The probe of a finding: the document, the result of each probe part, the capabilities and the handler. */
|
|
3389
3570
|
interface ConformProbe {
|
|
3390
3571
|
/** The text of the type of the document. */
|
|
@@ -3461,8 +3642,10 @@ interface ConformOptions {
|
|
|
3461
3642
|
*
|
|
3462
3643
|
* The checks follow the obligations C1 to C8 of `docs/SEMANTICS.md`. Two more checks follow the premises of the
|
|
3463
3644
|
* simulation of the plan. The check `local` finds state that stays from one call to the next. The check `agree` compares
|
|
3464
|
-
* compiled code with its definition. The
|
|
3465
|
-
*
|
|
3645
|
+
* compiled code with its definition. The finding of an obligation names the first probe that breaks it. An empty list
|
|
3646
|
+
* means that each probe conforms.
|
|
3647
|
+
*
|
|
3648
|
+
* The check `truth` tests the declared truth of a formula profile (D86).
|
|
3466
3649
|
*
|
|
3467
3650
|
* @param machine - The machine with the code and the world of the kinds.
|
|
3468
3651
|
* @param name - The name of the evaluator or of the runner. A runner wins over an evaluator of the same name.
|
|
@@ -4218,12 +4401,21 @@ interface ReplayOptions {
|
|
|
4218
4401
|
* value, because it does not wait. The default is `true`: an effect waits when it waited in the recorded run.
|
|
4219
4402
|
*/
|
|
4220
4403
|
readonly wait?: boolean;
|
|
4404
|
+
/**
|
|
4405
|
+
* The rule of the host for two payloads that are not the same by `Object.is`: one of the run and one of the log.
|
|
4406
|
+
* It works as the rule of `sameResult`. Its `undefined` gives the rules of `docEquals`. A log from `decodeLog` holds new copies
|
|
4407
|
+
* of the members of a domain, for example of a time. The rule tells that two such copies are the same.
|
|
4408
|
+
*/
|
|
4409
|
+
readonly equal?: (a: unknown, b: unknown) => boolean | undefined;
|
|
4221
4410
|
}
|
|
4222
4411
|
/**
|
|
4223
4412
|
* This function makes a recorder (RUN.RECORD). The recorder gives each effect to the function `perform` of the host.
|
|
4224
4413
|
* Its log keeps each effect with its address, its kind, its payload and the outcome that the kernel gives it. The log
|
|
4225
4414
|
* also keeps the order in which the waits of each `all` settle.
|
|
4226
4415
|
*
|
|
4416
|
+
* The recorder gives each call of its journal to the journal of the inner function, for example of a replayer. Thus a
|
|
4417
|
+
* recording of a replay settles the waits in the order of the replayer, and it gives the same log (RUN.REPLAY-ORDER).
|
|
4418
|
+
*
|
|
4227
4419
|
* @param perform - The function of the host. Without it, each effect gives its payload, as in a run without a host.
|
|
4228
4420
|
* @returns The function `perform` for the run, and the log.
|
|
4229
4421
|
*/
|
|
@@ -4233,13 +4425,172 @@ export declare function recorder(perform?: Perform): Recorder;
|
|
|
4233
4425
|
* recorded error comes again with its code, its reason, its place and its cause. The waits of each `all` settle in the
|
|
4234
4426
|
* recorded order. An effect that the log does not have at its address gives `#REPLAY!` (RUN.REPLAY-MISMATCH).
|
|
4235
4427
|
*
|
|
4236
|
-
*
|
|
4428
|
+
* One replayer serves more than one run, also two runs at the same time (RUN.REPLAY-RUNS). The kernel tells the journal
|
|
4429
|
+
* the number of the waits of each `all` that settled before, thus the replayer keeps no state of a run. When the
|
|
4430
|
+
* recorded item of a wait does not wait in the run, that wait follows the order of the host.
|
|
4237
4431
|
*
|
|
4238
|
-
* @param log - The log of a recorder
|
|
4239
|
-
* @param options - `wait: false` for an evaluation.
|
|
4432
|
+
* @param log - The log of a recorder, or of `decodeLog`.
|
|
4433
|
+
* @param options - `wait: false` for an evaluation, and the rule of the host for payloads.
|
|
4240
4434
|
* @returns The function `perform` for the replay.
|
|
4241
4435
|
*/
|
|
4242
4436
|
export declare function replayer(log: ReplayLog, options?: ReplayOptions): Perform;
|
|
4437
|
+
/** The JSON form of a log (RUN.REPLAY-JSON). `encodeLog` writes it, and `decodeLog` reads it. */
|
|
4438
|
+
interface ReplayLogJson {
|
|
4439
|
+
/** The version of the form. Only the version 1 exists. */
|
|
4440
|
+
readonly version: 1;
|
|
4441
|
+
readonly effects: readonly ReplayEntryJson[];
|
|
4442
|
+
readonly settles: readonly ReplaySettle[];
|
|
4443
|
+
}
|
|
4444
|
+
/** The JSON form of one effect of a log. A value is a term document of `encodeValue` (D40). */
|
|
4445
|
+
interface ReplayEntryJson {
|
|
4446
|
+
readonly address: string;
|
|
4447
|
+
readonly kind: string;
|
|
4448
|
+
/** The term document of the payload. The value `undefined` is `ext.undefined`. */
|
|
4449
|
+
readonly payload: Json;
|
|
4450
|
+
/** The JSON form of the outcome. It is absent when the recorded run stopped before the answer came. */
|
|
4451
|
+
readonly outcome?: ReplayResultJson;
|
|
4452
|
+
readonly waited: boolean;
|
|
4453
|
+
}
|
|
4454
|
+
/** The JSON form of an outcome: the term document of the value, or the JSON form of the error. */
|
|
4455
|
+
type ReplayResultJson = {
|
|
4456
|
+
readonly ok: true;
|
|
4457
|
+
readonly value: Json;
|
|
4458
|
+
} | {
|
|
4459
|
+
readonly ok: false;
|
|
4460
|
+
readonly error: ReplayErrorJson;
|
|
4461
|
+
};
|
|
4462
|
+
/** The JSON form of an error value. It has `cause`, `exception` or `causeParts` only when the error has a cause. */
|
|
4463
|
+
interface ReplayErrorJson {
|
|
4464
|
+
readonly code: ErrorCode;
|
|
4465
|
+
readonly reason: string;
|
|
4466
|
+
readonly place?: readonly Key[];
|
|
4467
|
+
/** The term document of the cause, when `encodeValue` writes the cause. */
|
|
4468
|
+
readonly cause?: Json;
|
|
4469
|
+
/** The JSON form of a cause that is an exception, when no domain with a codec holds it. */
|
|
4470
|
+
readonly exception?: ReplayExceptionJson;
|
|
4471
|
+
/**
|
|
4472
|
+
* The JSON form of a cause without a term document that is a list or a plain record with an exception at some depth
|
|
4473
|
+
* (RUN.REPLAY-CAUSE-PARTS, D87). It is a list of parts, the part `record` or the part `share`. The index 0 of `loop` is its
|
|
4474
|
+
* first exception, and the index 0 of `share` is its first list or record.
|
|
4475
|
+
*/
|
|
4476
|
+
readonly causeParts?: ReplayCausePartsJson;
|
|
4477
|
+
/** The names of the items of `causeParts` without a form, for example `cause.send`. This list is only a note. */
|
|
4478
|
+
readonly dropped?: readonly string[];
|
|
4479
|
+
}
|
|
4480
|
+
/**
|
|
4481
|
+
* The JSON form of a cause without a term document that is a list or a plain record with an exception at some depth
|
|
4482
|
+
* (D87). It is a list of parts, the part `record` or the part `share`, as a field in `parts` (D82, D88).
|
|
4483
|
+
*/
|
|
4484
|
+
type ReplayCausePartsJson = readonly ReplayPartsJson[] | {
|
|
4485
|
+
readonly record: Readonly<Record<string, ReplayPartsJson>>;
|
|
4486
|
+
} | {
|
|
4487
|
+
readonly share: number;
|
|
4488
|
+
};
|
|
4489
|
+
/**
|
|
4490
|
+
* The JSON form of an exception (RUN.REPLAY-CAUSES, D76). The exceptions of an error and of their causes are a chain.
|
|
4491
|
+
* The index 0 of the chain is the exception of the error. Each field after `message` is optional, thus a log of the
|
|
4492
|
+
* version 1 without them stays correct.
|
|
4493
|
+
*/
|
|
4494
|
+
interface ReplayExceptionJson {
|
|
4495
|
+
readonly name: string;
|
|
4496
|
+
readonly message: string;
|
|
4497
|
+
/** The term documents of the own fields of the exception that `encodeValue` writes, for example `code` or `errno`. */
|
|
4498
|
+
readonly fields?: Readonly<Record<string, Json>>;
|
|
4499
|
+
/**
|
|
4500
|
+
* The own enumerable fields without a term document that are an exception, a list or a plain record (RUN.REPLAY-FIELDS,
|
|
4501
|
+
* D78, D82). An example is a list `errors` on an `Error`. A list is a list of parts, and a record is the part `record`.
|
|
4502
|
+
* Each exception in them has the rule of a cause. A container without a form in it is a name in `dropped`. A container
|
|
4503
|
+
* that an earlier place holds is the part `share` (D88).
|
|
4504
|
+
*/
|
|
4505
|
+
readonly parts?: Readonly<Record<string, ReplayPartsJson>>;
|
|
4506
|
+
/**
|
|
4507
|
+
* The names of the own fields without a form, and `cause` for a cause without a form. An item of a container has the
|
|
4508
|
+
* name of the container, a dot and its key or index, for example `errors.1` or `cause.send`. This list is only a note:
|
|
4509
|
+
* `decodeLog` does not give these fields back.
|
|
4510
|
+
*/
|
|
4511
|
+
readonly dropped?: readonly string[];
|
|
4512
|
+
/**
|
|
4513
|
+
* The own fields of the standard classes that are not enumerable (RUN.REPLAY-HIDDEN, D77): `errors` of an
|
|
4514
|
+
* `AggregateError`, `error` and `suppressed` of a `SuppressedError`. A list is a list of parts.
|
|
4515
|
+
*/
|
|
4516
|
+
readonly hidden?: Readonly<Record<string, ReplayPartsJson>>;
|
|
4517
|
+
/** The term document of the cause, when `encodeValue` writes the cause. */
|
|
4518
|
+
readonly cause?: Json;
|
|
4519
|
+
/** The JSON form of a cause that is an exception, when no domain with a codec holds it. */
|
|
4520
|
+
readonly exception?: ReplayExceptionJson;
|
|
4521
|
+
/** The index in the chain of an earlier exception that is the cause. Thus a cycle of causes stays exact. */
|
|
4522
|
+
readonly loop?: number;
|
|
4523
|
+
/**
|
|
4524
|
+
* The JSON form of a cause without a term document that is a list or a plain record with an exception at some depth
|
|
4525
|
+
* (RUN.REPLAY-CAUSE-PARTS, D87). Each exception in it has the rule of a cause, also a `loop`.
|
|
4526
|
+
*/
|
|
4527
|
+
readonly causeParts?: ReplayCausePartsJson;
|
|
4528
|
+
}
|
|
4529
|
+
/**
|
|
4530
|
+
* The JSON form of one value of a field in `parts` or `hidden` (D77, D78, D82). It is a term document, an exception, a
|
|
4531
|
+
* loop, a record of parts, or a share (D88). The walk is depth
|
|
4532
|
+
* first: the fields in `parts` in their order, the hidden fields, then the cause. The mark `dropped` keeps the place of
|
|
4533
|
+
* an item of a list without a form, and `decodeLog` gives a hole there.
|
|
4534
|
+
*
|
|
4535
|
+
* The part `share` is a list or a record of parts that an earlier place of the walk holds (RUN.REPLAY-SHARED, D88). Its
|
|
4536
|
+
* index counts the lists and the records of parts in the order of the walk. Thus `decodeLog` gives one object for both places.
|
|
4537
|
+
*/
|
|
4538
|
+
type ReplayPartJson = {
|
|
4539
|
+
readonly value: Json;
|
|
4540
|
+
} | {
|
|
4541
|
+
readonly exception: ReplayExceptionJson;
|
|
4542
|
+
} | {
|
|
4543
|
+
readonly loop: number;
|
|
4544
|
+
} | {
|
|
4545
|
+
readonly record: Readonly<Record<string, ReplayPartsJson>>;
|
|
4546
|
+
} | {
|
|
4547
|
+
readonly share: number;
|
|
4548
|
+
} | {
|
|
4549
|
+
readonly dropped: true;
|
|
4550
|
+
};
|
|
4551
|
+
/**
|
|
4552
|
+
* The JSON form of a value in `parts`, in `hidden` or in a record of parts (D82). It is one part, or a list of them. A
|
|
4553
|
+
* list in a list is a JSON list in a JSON list, thus the rule is the same at each depth.
|
|
4554
|
+
*/
|
|
4555
|
+
type ReplayPartsJson = ReplayPartJson | readonly ReplayPartsJson[];
|
|
4556
|
+
/**
|
|
4557
|
+
* This function writes a log as JSON (RUN.REPLAY-JSON, D75). Then `JSON.stringify` gives the text of a golden file.
|
|
4558
|
+
*
|
|
4559
|
+
* - Each payload and each value of an outcome is a term document of `encodeValue`. Thus `NaN`, `-0` and `undefined`
|
|
4560
|
+
* stay exact, and a member of a domain with a codec is `ext.domain`.
|
|
4561
|
+
* - An error keeps its code, its reason, its place and its cause. A cause that `encodeValue` cannot write and that is
|
|
4562
|
+
* an exception keeps its name and its message in the field `exception`.
|
|
4563
|
+
* - An exception also keeps its own fields that `encodeValue` writes, and the chain of its causes (RUN.REPLAY-CAUSES).
|
|
4564
|
+
* The list `dropped` names each other own field. A cause that is an earlier exception of the chain is its index in `loop`.
|
|
4565
|
+
* - An exception keeps the hidden fields of the standard classes in `hidden`, for example `errors` of an
|
|
4566
|
+
* `AggregateError` (RUN.REPLAY-HIDDEN, D77). Each exception in them has the rule of a cause.
|
|
4567
|
+
* - An enumerable field without a term document that is an exception, a list or a plain record is in `parts`
|
|
4568
|
+
* (RUN.REPLAY-FIELDS, D78, D82). An item of a list without a form is the mark `dropped` at its place.
|
|
4569
|
+
* - A cause without a term document that is a list or a plain record with an exception is in `causeParts`
|
|
4570
|
+
* (RUN.REPLAY-CAUSE-PARTS, D87). The rule is the same for the cause of an exception and of an error value.
|
|
4571
|
+
* - A list or a record of parts that an earlier place of one error holds is the part `share` with its index
|
|
4572
|
+
* (RUN.REPLAY-SHARED, D88). This rule also covers a container that holds itself.
|
|
4573
|
+
* - An outcome that the log does not have stays absent.
|
|
4574
|
+
*
|
|
4575
|
+
* @param machine - The machine of the run, or only its domains.
|
|
4576
|
+
* @param log - The log of a recorder.
|
|
4577
|
+
* @returns The JSON form. `decodeLog` gives the log again.
|
|
4578
|
+
* @throws {TypeError} A value has no term document, for example a closure, a host thing, a symbol, or a value that no
|
|
4579
|
+
* domain with a codec holds. The message names the effect and its address. A part of an exception is not a refusal.
|
|
4580
|
+
*/
|
|
4581
|
+
export declare function encodeLog(machine: Pick<Machine, "domains">, log: ReplayLog): ReplayLogJson;
|
|
4582
|
+
/**
|
|
4583
|
+
* This function reads the JSON form of a log again (RUN.REPLAY-JSON). It reads each term document with the formula kit
|
|
4584
|
+
* and the domains of the machine. A cause in the field `exception` becomes an exception with that name and message.
|
|
4585
|
+
* The exception gets its fields and the chain of its causes again, also a cycle (RUN.REPLAY-CAUSES). A list gets a
|
|
4586
|
+
* hole at the place of the mark `dropped`, thus each later item keeps its index (D78). Each share of a list or a record
|
|
4587
|
+
* gives the same object (RUN.REPLAY-SHARED).
|
|
4588
|
+
*
|
|
4589
|
+
* @param machine - The machine of the run, or only its domains.
|
|
4590
|
+
* @param data - The JSON form, for example from `JSON.parse` of a golden file.
|
|
4591
|
+
* @returns The log for `replayer`, or `#VALUE!` with the place of the first field that it cannot read.
|
|
4592
|
+
*/
|
|
4593
|
+
export declare function decodeLog(machine: Pick<Machine, "domains">, data: unknown): Result<ReplayLog>;
|
|
4243
4594
|
//#endregion
|
|
4244
4595
|
//#region src/providers.d.ts
|
|
4245
4596
|
/** The type that a provider reads, and the problems of the reading. Each problem tells what the type does not test. */
|
|
@@ -4289,5 +4640,5 @@ interface SampleOptions {
|
|
|
4289
4640
|
*/
|
|
4290
4641
|
export declare function typeFromSamples(values: readonly unknown[], options?: SampleOptions): ValueType;
|
|
4291
4642
|
//#endregion
|
|
4292
|
-
export type { AgreeOptions, AgreeRunOptions, AgreeScheduleOptions, Agreement, Alias, AllOptions, Answer, AskOptions, AttributeDeclaration, AttributeRung, AttributeTrace, Cap, CapsRule, CheckOptions, Classification, Closure, Code, CompileInput, CompiledEvaluator, CompiledPart, CompiledRunner, ConformOptions, ConformProbe, Construct, Context, Part as ContextPart, Definitions, DerefCode, DocFacts, DocParts, DocVisit, Domain, DomainCodec, DomainExtension, Durable, DurableCounts, DurableOptions, Edge, Effect, EffectsOptions, Envelope, Epochs, ErrorCode, EvalError, EvalFn, EvalInput, EvalOptions, EvaluateOptions, Evaluator, ExtFn, FactsOptions, Failed, Finding, FormulaProfile, GenerateOptions, Give, GraphCycle, GraphEdge, GraphNode, GraphOptions, Header, Hop, HopBy, HostThing, Issue, Journal, Json, JsonRecord, KernelCode, Key, Kind, KindFacts, KindSource, LazyOp, LazyRule, Lookup, Machine, MachinePart, MergeConflict, MergePath, NamesSource, Namespace, Navigator, NearestOptions, NodeEdge, NodeGraph, NodeInfo, NodeRunOptions, Obligation, OpFn, OrderProblem, Outcome, ParseResult, Part$1 as Part, PartInfo, Shape as PartShape, PartSlot, PartType, PartsSpec, Perform, Plan, PlanRunOptions, PrepareOptions, Random, Read, ReadsCheck, Recorder, RefUse, ReferenceOptions, ReferenceRunOptions, ReplayEntry, ReplayLog, ReplayOptions, ReplaySettle, Resolution, ResolveCode, ResolveOptions, Result, Root, RootTypes, Run, RunCode, RunFn, RunInput, RunOptions, RunPart, Rung, Runner, Runtime, SampleOptions, Schedule, ScheduleAgreement, ScheduleAgreementCounts, ScheduleCounts, ScheduleEngine, ScheduleEngineFactory, ScheduleEngineStart, ScheduleOptions, ScopeRule, Shape$1 as Shape, Side, Signature, Split, StaticRead, Step, StepSpec, Steps, StopSignal, Stored, SyntaxAssoc, SyntaxCalls, SyntaxFixity, SyntaxForm, SyntaxIssue, SyntaxLiterals, SyntaxOperator, SyntaxProfile, SyntaxRefPattern, SyntaxRefs, Thing, Tier, TierInput, TierResult, TraceNode, TreeContract, TypeInput, TypeIssue, TypeProblem, TypeReading, TypeRef, TypeRule, Typed, Typing, Use, ValueType, VerbEffects, VerifyOptions, WalkInput, WalkOptions, WalkProblem, WalkResult, Walker, World, WorldEntry, WorldIssue, WorldPart };
|
|
4643
|
+
export type { AgreeOptions, AgreeRunOptions, AgreeScheduleOptions, Agreement, Alias, AllOptions, Answer, AskOptions, AttributeDeclaration, AttributeRung, AttributeTrace, Cap, CapsRule, CheckOptions, Classification, Closure, Code, CompileInput, CompiledEvaluator, CompiledPart, CompiledRunner, ConformOptions, ConformProbe, Construct, Context, Part as ContextPart, Definitions, DerefCode, DocFacts, DocParts, DocVisit, Domain, DomainCodec, DomainExtension, Durable, DurableCounts, DurableOptions, Edge, Effect, EffectsOptions, Envelope, Epochs, ErrorCode, EvalError, EvalFn, EvalInput, EvalOptions, EvaluateOptions, Evaluator, ExtFn, FactsOptions, Failed, Finding, FormulaProfile, GenerateOptions, Give, GraphCycle, GraphEdge, GraphNode, GraphOptions, Header, Hop, HopBy, HostThing, Issue, Journal, Json, JsonRecord, KernelCode, Key, Kind, KindFacts, KindSource, LazyOp, LazyRule, Lookup, Machine, MachinePart, MergeConflict, MergePath, NamesSource, Namespace, Navigator, NearestOptions, NodeEdge, NodeGraph, NodeInfo, NodeRunOptions, Obligation, OpFn, OrderProblem, Outcome, ParseResult, Part$1 as Part, PartInfo, Shape as PartShape, PartSlot, PartType, PartsSpec, Perform, Plan, PlanRunOptions, PrepareOptions, Random, Read, ReadsCheck, Recorder, RefUse, ReferenceOptions, ReferenceRunOptions, ReplayCausePartsJson, ReplayEntry, ReplayEntryJson, ReplayErrorJson, ReplayExceptionJson, ReplayLog, ReplayLogJson, ReplayOptions, ReplayPartJson, ReplayPartsJson, ReplayResultJson, ReplaySettle, Resolution, ResolveCode, ResolveOptions, Result, Root, RootTypes, Run, RunCode, RunFn, RunInput, RunOptions, RunPart, Rung, Runner, Runtime, SampleOptions, Schedule, ScheduleAgreement, ScheduleAgreementCounts, ScheduleCounts, ScheduleEngine, ScheduleEngineFactory, ScheduleEngineStart, ScheduleOptions, ScopeRule, Shape$1 as Shape, Side, Signature, Split, StaticRead, Step, StepSpec, Steps, StopSignal, Stored, SyntaxAssoc, SyntaxCalls, SyntaxEnvelopes, SyntaxFixity, SyntaxForm, SyntaxFormArgs, SyntaxHeader, SyntaxIssue, SyntaxLiterals, SyntaxOperator, SyntaxProfile, SyntaxRefPattern, SyntaxRefs, Thing, Tier, TierInput, TierResult, TraceNode, TreeContract, TypeInput, TypeIssue, TypeProblem, TypeReading, TypeRef, TypeRule, Typed, Typing, Use, ValueType, VerbEffects, VerifyOptions, WalkInput, WalkOptions, WalkProblem, WalkResult, Walker, World, WorldEntry, WorldIssue, WorldPart };
|
|
4293
4644
|
//# sourceMappingURL=index.d.ts.map
|