hclang 0.39.0 → 0.41.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/esm/lib/bundle/hc-sources.js +51 -15
- package/esm/lib/frames/effect-registry.js +92 -0
- package/esm/lib/frames/error-kind.js +34 -0
- package/esm/lib/frames/frame-expr.js +90 -11
- package/esm/lib/frames/frame-lazy.js +45 -1
- package/esm/lib/frames/frame-note.js +16 -6
- package/esm/lib/frames/frame-observation.js +97 -0
- package/esm/lib/frames/frame-scope-anchor.js +92 -23
- package/esm/lib/frames/frame-symbol.js +10 -1
- package/esm/lib/frames/frame.js +39 -0
- package/esm/lib/frames/partition-check.js +46 -0
- package/esm/lib/frames/schema-matcher.js +1 -1
- package/esm/lib/frames.js +4 -1
- package/esm/lib/ops/type-operations.js +56 -0
- package/esm/lib/ops.js +3 -1
- package/esm/lib/version.js +1 -1
- package/package.json +1 -1
|
@@ -1412,7 +1412,7 @@ export const HC_SOURCES = new Map([
|
|
|
1412
1412
|
"when odd, right next. It is a Count rather than all or nil because a field",
|
|
1413
1413
|
"cannot hold nil, and a Count keeps the odd phase present: a Demi in phase 1 is",
|
|
1414
1414
|
"a value, unlike the nil `.####` answers for a Frame with no Demi. Anything else",
|
|
1415
|
-
"is refused with
|
|
1415
|
+
"is refused with `$!!.invalid-demi`, a named error, as Figures refuses an",
|
|
1416
1416
|
"unsupported host. The fields are the whole state, so two Demis are `=` exactly",
|
|
1417
1417
|
"when their fields are.",
|
|
1418
1418
|
"",
|
|
@@ -1456,9 +1456,9 @@ export const HC_SOURCES = new Map([
|
|
|
1456
1456
|
" .apply_ {.s (_ .##); .l (_^ .left); .r (_^ .right);",
|
|
1457
1457
|
" (s ~ (0.<>)) ? {((_^^ .phase) = 2) ? {@left (l + s); @phase 1;} : {@right (r + s); @phase 2;}; _^^} : {s}};",
|
|
1458
1458
|
" .scale_ {.k _; .l (_^ .left); .r (_^ .right);",
|
|
1459
|
-
" (k ~ (0.<>)) ? {@left (l * k); @right (r * k); _^^} : {
|
|
1459
|
+
" (k ~ (0.<>)) ? {@left (l * k); @right (r * k); _^^} : {$!!.invalid-scale}};",
|
|
1460
1460
|
" .toText {“Demi(” (((_^ .phase) = 2) ? {“<>”} : {“()”}) “,” (_^ .left) “,” (_^ .right) “)”}",
|
|
1461
|
-
" ]} : {
|
|
1461
|
+
" ]} : {$!!.invalid-demi}} : {$!!.invalid-demi}};",
|
|
1462
1462
|
"```",
|
|
1463
1463
|
"## Construction",
|
|
1464
1464
|
"",
|
|
@@ -1475,9 +1475,9 @@ export const HC_SOURCES = new Map([
|
|
|
1475
1475
|
"Anything but three Counts with phase 1 or 2 is refused",
|
|
1476
1476
|
"```",
|
|
1477
1477
|
"; Demi [3, 0, 0]",
|
|
1478
|
-
"#
|
|
1478
|
+
"# $!!.invalid-demi",
|
|
1479
1479
|
"; [Demi [2, (0 - 1), 0], Demi [2, (5 - 3), 0], Demi [2, 0], Demi 5, Demi [(5 - 3), 0, 0]]",
|
|
1480
|
-
"# [
|
|
1480
|
+
"# [$!!.invalid-demi, $!!.invalid-demi, $!!.invalid-demi, $!!.invalid-demi, $!!.invalid-demi]",
|
|
1481
1481
|
"```",
|
|
1482
1482
|
"## Application",
|
|
1483
1483
|
"",
|
|
@@ -1608,7 +1608,7 @@ export const HC_SOURCES = new Map([
|
|
|
1608
1608
|
"; [“” (e.scale_ 2), “” (e.scale_ 0), (e.scale_ 1) = e, ((e.scale_ 2).scale_ 3) = (e.scale_ 6)]",
|
|
1609
1609
|
"# [“Demi((),24,6)”, “Demi((),0,0)”, <>, <>]",
|
|
1610
1610
|
"; e.scale_ (0 - 2)",
|
|
1611
|
-
"#
|
|
1611
|
+
"# $!!.invalid-scale",
|
|
1612
1612
|
"```",
|
|
1613
1613
|
"It is the shadow of Star on a nonempty host",
|
|
1614
1614
|
"```",
|
|
@@ -1701,7 +1701,7 @@ export const HC_SOURCES = new Map([
|
|
|
1701
1701
|
"```",
|
|
1702
1702
|
".gap {.x _; (x.###) ? {",
|
|
1703
1703
|
" .signed (x.###);",
|
|
1704
|
-
" (signed .< 0) ? {0 - signed} : {signed}} : {
|
|
1704
|
+
" (signed .< 0) ? {0 - signed} : {signed}} : {$!!.unsupported-figure}};",
|
|
1705
1705
|
"```",
|
|
1706
1706
|
"Spin retains a typed positive Count divisor. Bare `x.### / N` would accept",
|
|
1707
1707
|
"negative or fractional divisors and silently answer nil for an unsupported",
|
|
@@ -1713,7 +1713,7 @@ export const HC_SOURCES = new Map([
|
|
|
1713
1713
|
" (host.###) ? {",
|
|
1714
1714
|
" {.n <(1).<>> _; .signed (host.###);",
|
|
1715
1715
|
" (n .< 1) ? {signed / 0} : {signed / n}}} : {",
|
|
1716
|
-
" {.n _;
|
|
1716
|
+
" {.n _; $!!.unsupported-figure}}};",
|
|
1717
1717
|
"```",
|
|
1718
1718
|
"Native construction, counting and comparisons need no module helpers.",
|
|
1719
1719
|
"```",
|
|
@@ -1729,7 +1729,7 @@ export const HC_SOURCES = new Map([
|
|
|
1729
1729
|
"```",
|
|
1730
1730
|
"; [([].### ? {<>} : {()}), ([[], [[]]].### ? {<>} : {()}), ([[], 5].### ? {<>} : {()}), ([.k 1; []].### ? {<>} : {()})]",
|
|
1731
1731
|
"# [<>, <>, <>, <>]",
|
|
1732
|
-
"; [(e.### ? {e} : {
|
|
1732
|
+
"; [(e.### ? {e} : {$!!.unsupported-figure}) = e, (e.### ? {e} : {$!!.unsupported-figure}) === e]",
|
|
1733
1733
|
"# [<>, <>]",
|
|
1734
1734
|
"; [[], “a”] * [[]]",
|
|
1735
1735
|
"# $!.star-domain *",
|
|
@@ -2540,8 +2540,8 @@ export const HC_SOURCES = new Map([
|
|
|
2540
2540
|
"array's properties are configuration, not routed Frames, so the constructor",
|
|
2541
2541
|
"keeps the elements in a fresh array of its own, and a channel argument that",
|
|
2542
2542
|
"declares `apply` cannot change what appending means. Anything else is refused",
|
|
2543
|
-
"with
|
|
2544
|
-
"
|
|
2543
|
+
"with `$!!.invalid-router`, a named error, as `Demi` refuses with",
|
|
2544
|
+
"`$!!.invalid-demi`.",
|
|
2545
2545
|
"Any phase and any two channels are a state; nothing requires the channels to",
|
|
2546
2546
|
"be a history the router could have produced.",
|
|
2547
2547
|
"",
|
|
@@ -2588,7 +2588,7 @@ export const HC_SOURCES = new Map([
|
|
|
2588
2588
|
" .## {(channel-load (_^ .left)) + (channel-load (_^ .right))};",
|
|
2589
2589
|
" .### {(channel-load (_^ .left)) - (channel-load (_^ .right))};",
|
|
2590
2590
|
" .toText {“RotorRouter(” (((_^ .phase) = 2) ? {“<>”} : {“()”}) “,” (_^ .left) “,” (_^ .right) “)”}",
|
|
2591
|
-
" ]} : {
|
|
2591
|
+
" ]} : {$!!.invalid-router}} : {$!!.invalid-router}};",
|
|
2592
2592
|
"```",
|
|
2593
2593
|
"## Construction",
|
|
2594
2594
|
"",
|
|
@@ -2602,9 +2602,9 @@ export const HC_SOURCES = new Map([
|
|
|
2602
2602
|
"Anything but a phase of 1 or 2 and two arrays is refused",
|
|
2603
2603
|
"```",
|
|
2604
2604
|
"; RotorRouter [3, [], []]",
|
|
2605
|
-
"#
|
|
2605
|
+
"# $!!.invalid-router",
|
|
2606
2606
|
"; [RotorRouter [(5 - 3), [], []], RotorRouter [2, [], 5], RotorRouter [2, (1, 2), []], RotorRouter [2, []], RotorRouter 5]",
|
|
2607
|
-
"# [
|
|
2607
|
+
"# [$!!.invalid-router, $!!.invalid-router, $!!.invalid-router, $!!.invalid-router, $!!.invalid-router]",
|
|
2608
2608
|
"```",
|
|
2609
2609
|
"A channel is its elements. The router keeps them in an array of its own, so a",
|
|
2610
2610
|
"channel's properties and a declared `apply` do not come with it",
|
|
@@ -4134,7 +4134,43 @@ export const HC_SOURCES = new Map([
|
|
|
4134
4134
|
"; join-name (.middle “Q”)",
|
|
4135
4135
|
"# $!invalid-argument-list (.middle “Q”, $!missing-required-argument .last;)",
|
|
4136
4136
|
"```",
|
|
4137
|
-
"The return type is usually inferred, but can be specified explicitly using a
|
|
4137
|
+
"The return type is usually inferred, but can be specified explicitly using a",
|
|
4138
|
+
"trailing `^^`. The result a successful call exposes must conform to that schema,",
|
|
4139
|
+
"and a result that does not is refused rather than returned:",
|
|
4140
|
+
"```",
|
|
4141
|
+
"; .small (.x) ^ {x} ^^ <1, 2, 3>;",
|
|
4142
|
+
"; small (.x 2)",
|
|
4143
|
+
"# 2",
|
|
4144
|
+
"; small (.x 9)",
|
|
4145
|
+
"# $!.type-error <1, 2, 3> 9",
|
|
4146
|
+
"```",
|
|
4147
|
+
"A return contract checks only the exposed result; it neither freezes, copies,",
|
|
4148
|
+
"nor converts the underlying object, and a closure whose body already failed",
|
|
4149
|
+
"surfaces that failure rather than a contract complaint.",
|
|
4150
|
+
"",
|
|
4151
|
+
"",
|
|
4152
|
+
"#### Effect Boundaries",
|
|
4153
|
+
"",
|
|
4154
|
+
"Where `^` and `^^` describe one call, the arrow `->` describes a continuing",
|
|
4155
|
+
"relationship. In `A -> B` the callback `B` is registered on the value `A`",
|
|
4156
|
+
"manages, and a later committed mutation of that value, by any actor through any",
|
|
4157
|
+
"alias, is a new invocation of `B`. The arrow is an effect boundary, not a write",
|
|
4158
|
+
"permission: it answers `A` unchanged and never grants the right to write it.",
|
|
4159
|
+
"Here each committed write of the cell bumps a shared counter the callback holds,",
|
|
4160
|
+
"while the cell itself keeps the value that was written to it:",
|
|
4161
|
+
"```",
|
|
4162
|
+
"; .log_ [.count 0; .tick_ {@count (count + 1);}];",
|
|
4163
|
+
"; .cell_ [.v 1; .put_ {@v _;}];",
|
|
4164
|
+
"; cell_ -> {log_.tick_ ()};",
|
|
4165
|
+
"; cell_.put_ 7;",
|
|
4166
|
+
"; cell_.v",
|
|
4167
|
+
"# 7",
|
|
4168
|
+
"; log_.count",
|
|
4169
|
+
"# 1",
|
|
4170
|
+
"```",
|
|
4171
|
+
"A refused or uncommitted write triggers nothing, and a functional update on an",
|
|
4172
|
+
"immutable handle writes a copy the arrow never observed, so only a real",
|
|
4173
|
+
"committed mutation of the managed value is a new consequence.",
|
|
4138
4174
|
"",
|
|
4139
4175
|
"",
|
|
4140
4176
|
"#### Type Values",
|
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
/** Subscribers registered on one managed value, in registration order. */
|
|
2
|
+
const subscribers = new WeakMap();
|
|
3
|
+
/** Managed values whose callbacks are currently running, to bound reentrancy. */
|
|
4
|
+
const firing = new WeakSet();
|
|
5
|
+
/** Committed nested mutations of a firing value, each owed one more round. */
|
|
6
|
+
const pending = new Map();
|
|
7
|
+
/** The most delivery rounds one outermost commit may cause (nested included). */
|
|
8
|
+
export const EFFECT_DELIVERY_LIMIT = 65_536;
|
|
9
|
+
/**
|
|
10
|
+
* The invoker is installed once by the runtime so this module need not import
|
|
11
|
+
* closure machinery (which would close an import cycle through `frame.ts`).
|
|
12
|
+
* Until it is installed, a registered callback is simply not called.
|
|
13
|
+
*/
|
|
14
|
+
let invoke;
|
|
15
|
+
/** Installs the one callback-invocation strategy (called at startup). */
|
|
16
|
+
export function installEffectInvoker(invoker) {
|
|
17
|
+
invoke = invoker;
|
|
18
|
+
}
|
|
19
|
+
/**
|
|
20
|
+
* Registers `callback` as an effect-boundary observer of `managed`.
|
|
21
|
+
*
|
|
22
|
+
* Idempotent per (managed, callback) pair so re-declaring the same arrow does
|
|
23
|
+
* not multiply invocations. Returns the managed value so the arrow operator can
|
|
24
|
+
* answer it unchanged.
|
|
25
|
+
*/
|
|
26
|
+
export function registerEffect(managed, callback) {
|
|
27
|
+
const existing = subscribers.get(managed);
|
|
28
|
+
if (!existing) {
|
|
29
|
+
subscribers.set(managed, [callback]);
|
|
30
|
+
return managed;
|
|
31
|
+
}
|
|
32
|
+
if (!existing.includes(callback))
|
|
33
|
+
existing.push(callback);
|
|
34
|
+
return managed;
|
|
35
|
+
}
|
|
36
|
+
/** Whether a value carries any effect-boundary subscribers. */
|
|
37
|
+
export function hasEffectSubscribers(managed) {
|
|
38
|
+
return subscribers.has(managed);
|
|
39
|
+
}
|
|
40
|
+
/**
|
|
41
|
+
* Whether `observer` itself is registered on `managed` by an `A -> B` arrow,
|
|
42
|
+
* so a committed mutation of `managed` invokes it. Another callback on the
|
|
43
|
+
* same value does not count (PR #475 review).
|
|
44
|
+
*/
|
|
45
|
+
export function isEffectObserver(managed, observer) {
|
|
46
|
+
return subscribers.get(managed)?.includes(observer) ?? false;
|
|
47
|
+
}
|
|
48
|
+
/**
|
|
49
|
+
* Notifies a managed value's subscribers that it committed a mutation.
|
|
50
|
+
*
|
|
51
|
+
* The single seam called from the mutation commit points. It is a no-op for the
|
|
52
|
+
* overwhelming majority of frames, which carry no subscribers, so ordinary
|
|
53
|
+
* construction and mutation pay only a `WeakMap.has` check. A commit to a value
|
|
54
|
+
* already firing is deferred to a later round rather than dropped.
|
|
55
|
+
*/
|
|
56
|
+
export function notifyEffect(managed) {
|
|
57
|
+
if (!subscribers.has(managed) || !invoke)
|
|
58
|
+
return;
|
|
59
|
+
if (firing.has(managed)) {
|
|
60
|
+
pending.set(managed, (pending.get(managed) ?? 0) + 1);
|
|
61
|
+
return;
|
|
62
|
+
}
|
|
63
|
+
firing.add(managed);
|
|
64
|
+
let thrown;
|
|
65
|
+
try {
|
|
66
|
+
let due = 1;
|
|
67
|
+
for (let rounds = 1; due > 0; rounds++) {
|
|
68
|
+
if (rounds > EFFECT_DELIVERY_LIMIT) {
|
|
69
|
+
throw new RangeError(`$!.effect-delivery-limit ${EFFECT_DELIVERY_LIMIT}`);
|
|
70
|
+
}
|
|
71
|
+
due--;
|
|
72
|
+
// Snapshot each round, so an arrow registered by a callback joins the
|
|
73
|
+
// next round rather than the one being delivered.
|
|
74
|
+
for (const callback of [...subscribers.get(managed)]) {
|
|
75
|
+
try {
|
|
76
|
+
invoke(callback, managed);
|
|
77
|
+
}
|
|
78
|
+
catch (error) {
|
|
79
|
+
thrown ??= { error };
|
|
80
|
+
}
|
|
81
|
+
}
|
|
82
|
+
due += pending.get(managed) ?? 0;
|
|
83
|
+
pending.delete(managed);
|
|
84
|
+
}
|
|
85
|
+
}
|
|
86
|
+
finally {
|
|
87
|
+
firing.delete(managed);
|
|
88
|
+
pending.delete(managed);
|
|
89
|
+
}
|
|
90
|
+
if (thrown)
|
|
91
|
+
throw thrown.error;
|
|
92
|
+
}
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Error kinds (spec a13/14 §3, §4).
|
|
3
|
+
*
|
|
4
|
+
* A kind is the namespace and reason an error renders with: `$!.reason` for a
|
|
5
|
+
* system error, made by the interpreter, and `$!!.reason` for a user error,
|
|
6
|
+
* raised by HC code. Every error's rendering begins with its kind, followed by
|
|
7
|
+
* whatever subject it carries, so the kind is read from that prefix with the
|
|
8
|
+
* reason grammar of spec 10 §6.1.
|
|
9
|
+
*
|
|
10
|
+
* A `$!.reason` literal written in HC source is a user error that still
|
|
11
|
+
* describes the system kind it was written as. A schema that holds it matches
|
|
12
|
+
* that system kind (§4), while raising it propagates the user error.
|
|
13
|
+
*/
|
|
14
|
+
const KIND = /^\$(!!?)\.([A-Za-z_][A-Za-z0-9_-]*)/;
|
|
15
|
+
/**
|
|
16
|
+
* The kind a literal was written as, stored on the frame itself. It is an own
|
|
17
|
+
* enumerable property, so `Frame.copy` (`Object.assign`) carries it to every
|
|
18
|
+
* copy, and the kind survives wherever the literal's frame is copied.
|
|
19
|
+
*/
|
|
20
|
+
const WRITTEN = Symbol("written error kind");
|
|
21
|
+
/** The kind an error renders with, `$!.reason` or `$!!.reason`, if any. */
|
|
22
|
+
export const kindOf = (error) => {
|
|
23
|
+
const match = KIND.exec(error.toString());
|
|
24
|
+
return match ? `$${match[1]}.${match[2]}` : undefined;
|
|
25
|
+
};
|
|
26
|
+
/** The reason within a kind, without its namespace. */
|
|
27
|
+
export const reasonOf = (error) => KIND.exec(error.toString())?.[2];
|
|
28
|
+
/** Records that a user error was written as the system kind `kind`. */
|
|
29
|
+
export const describeAs = (error, kind) => {
|
|
30
|
+
error[WRITTEN] = kind;
|
|
31
|
+
return error;
|
|
32
|
+
};
|
|
33
|
+
/** The kind a schema candidate names: as written, or as it renders. */
|
|
34
|
+
export const describedKind = (candidate) => candidate[WRITTEN] ?? kindOf(candidate);
|
|
@@ -102,33 +102,103 @@ export class FrameExpr extends FrameList {
|
|
|
102
102
|
// Don't add separator here - let parent FrameList handle it
|
|
103
103
|
return [body];
|
|
104
104
|
}
|
|
105
|
+
/**
|
|
106
|
+
* Reduces an expression's terms left to right, with the catch operator `$!`
|
|
107
|
+
* as its one boundary (spec a13/14 §5).
|
|
108
|
+
*
|
|
109
|
+
* Spaced, `E $! H₁ $! H₂` guards everything to its left: the expression
|
|
110
|
+
* splits at each bare `$!`, and each handler part is evaluated only while
|
|
111
|
+
* the result so far is an error. A tight catcher, `x $!{H}`, is one term
|
|
112
|
+
* (a16) that handles the failure just before it: the preceding term's, or
|
|
113
|
+
* else the expression so far.
|
|
114
|
+
*/
|
|
105
115
|
static evaluateTerms(terms, scope) {
|
|
106
|
-
return terms.
|
|
116
|
+
return terms.some(isCatch)
|
|
117
|
+
? FrameExpr.catchSpaced(terms, scope)
|
|
118
|
+
: FrameExpr.reduceTerms(terms, scope);
|
|
119
|
+
}
|
|
120
|
+
static reduceTerms(terms, scope) {
|
|
121
|
+
let sum = Frame.nil;
|
|
122
|
+
for (let index = 0; index < terms.length; index++) {
|
|
123
|
+
const item = terms[index];
|
|
124
|
+
if (isCatcher(item)) {
|
|
125
|
+
if (index === 0)
|
|
126
|
+
return Frame.error("$!.catch-operand-missing");
|
|
127
|
+
// A catcher after a success has nothing to handle and is not run.
|
|
128
|
+
if (sum.isError())
|
|
129
|
+
sum = FrameExpr.handle(sum, item, scope);
|
|
130
|
+
continue;
|
|
131
|
+
}
|
|
107
132
|
// A failed term is the result of the expression. In particular, a
|
|
108
133
|
// missing dot-parameter read must not be replaced by the operator or
|
|
109
134
|
// operand that follows it. Only the value itself counts: an aggregate
|
|
110
135
|
// that collected a failure is still an ordinary value its later terms
|
|
111
136
|
// can read (`[E, 7] .1` is 7), as it was before #467 flagged notes.
|
|
137
|
+
// Later terms are skipped; only a catcher can still handle it.
|
|
112
138
|
if (sum.isError())
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
139
|
+
continue;
|
|
140
|
+
let value = item.in(resumedScope(item, scope));
|
|
141
|
+
while (value.is.error === true && isCatcher(terms[index + 1])) {
|
|
142
|
+
value = FrameExpr.handle(value, terms[++index], scope);
|
|
143
|
+
}
|
|
144
|
+
if (value.is.error === true) {
|
|
145
|
+
sum = value;
|
|
146
|
+
continue;
|
|
147
|
+
}
|
|
117
148
|
if (index === 0 && value.isSymbol() && value.is.address &&
|
|
118
|
-
Frame.SIZE_OPERATORS.includes(value.spelling()))
|
|
119
|
-
|
|
149
|
+
Frame.SIZE_OPERATORS.includes(value.spelling())) {
|
|
150
|
+
sum = value;
|
|
151
|
+
continue;
|
|
152
|
+
}
|
|
120
153
|
// An explicit nil receiver still has a Size. The initial nil accumulator
|
|
121
154
|
// is not a receiver, so a leading .## remains an address (#411).
|
|
122
155
|
if (index > 0 && sum.is.void && value.isSymbol() &&
|
|
123
156
|
value.is.address &&
|
|
124
157
|
Frame.SIZE_OPERATORS.includes(value.spelling())) {
|
|
125
|
-
|
|
158
|
+
sum = value.called_by(sum);
|
|
159
|
+
continue;
|
|
126
160
|
}
|
|
127
161
|
if (index > 0 && value.is.operator === true) {
|
|
128
|
-
|
|
162
|
+
sum = value.called_by(sum, Frame.nil).atSite(scope);
|
|
163
|
+
continue;
|
|
129
164
|
}
|
|
130
|
-
|
|
131
|
-
}
|
|
165
|
+
sum = sum.call(value);
|
|
166
|
+
}
|
|
167
|
+
return sum;
|
|
168
|
+
}
|
|
169
|
+
/** `E $! H₁ $! H₂ …`: guard everything to the left of each handler. */
|
|
170
|
+
static catchSpaced(terms, scope) {
|
|
171
|
+
const parts = [[]];
|
|
172
|
+
for (const term of terms) {
|
|
173
|
+
if (isCatch(term))
|
|
174
|
+
parts.push([]);
|
|
175
|
+
else
|
|
176
|
+
parts.at(-1).push(term);
|
|
177
|
+
}
|
|
178
|
+
const [guarded, ...handlers] = parts;
|
|
179
|
+
if (guarded.length === 0)
|
|
180
|
+
return Frame.error("$!.catch-operand-missing");
|
|
181
|
+
if (handlers.some((part) => part.length === 0)) {
|
|
182
|
+
return Frame.error("$!.catch-handler-missing");
|
|
183
|
+
}
|
|
184
|
+
let result = FrameExpr.reduceTerms(guarded, scope);
|
|
185
|
+
for (const part of handlers) {
|
|
186
|
+
if (!result.isError())
|
|
187
|
+
break;
|
|
188
|
+
result = Frame.catchWith(result, () => FrameExpr.reduceTerms(part, scope));
|
|
189
|
+
}
|
|
190
|
+
return result;
|
|
191
|
+
}
|
|
192
|
+
/**
|
|
193
|
+
* A tight catcher `$!H` handles `failure` with the handler `H`. The handler
|
|
194
|
+
* is evaluated only on failure, with the observation already current, so
|
|
195
|
+
* `$#` reads it whether `H` is a closure or not.
|
|
196
|
+
*/
|
|
197
|
+
static handle(failure, catcher, scope) {
|
|
198
|
+
const body = catcher.data.slice(1);
|
|
199
|
+
if (body.length === 0)
|
|
200
|
+
return Frame.error("$!.catch-handler-missing");
|
|
201
|
+
return Frame.catchWith(failure, () => FrameExpr.evaluateTerms(body, scope));
|
|
132
202
|
}
|
|
133
203
|
schemaRetrieval(scope) {
|
|
134
204
|
if (this.data.length !== 2 || !this.data[0].isSymbol() ||
|
|
@@ -504,3 +574,12 @@ function unwrapSingleton(frame) {
|
|
|
504
574
|
}
|
|
505
575
|
return result;
|
|
506
576
|
}
|
|
577
|
+
/** The catch operator `$!`, as the lexer completes it (`FrameCatch`). */
|
|
578
|
+
function isCatch(term) {
|
|
579
|
+
return term?.className() === "FrameCatch";
|
|
580
|
+
}
|
|
581
|
+
/** A tight expression that begins with `$!`: `$!{H}` written after a term. */
|
|
582
|
+
function isCatcher(term) {
|
|
583
|
+
return term instanceof FrameExpr && term.constructor === FrameExpr &&
|
|
584
|
+
isCatch(term.asArray()[0]);
|
|
585
|
+
}
|
|
@@ -6,6 +6,7 @@ import { FrameSymbol } from "./frame-symbol.js";
|
|
|
6
6
|
import { NilContext } from "./context.js";
|
|
7
7
|
import { EvaluationScope } from "./evaluation-scope.js";
|
|
8
8
|
import { renderSourceTerm } from "./frame-list.js";
|
|
9
|
+
import { isFrameMatcher } from "./frame-match.js";
|
|
9
10
|
// Both maps describe per-evaluation bound copies. The parsed/shared closure is
|
|
10
11
|
// never a key, so evaluating one template in two scopes cannot rebind either
|
|
11
12
|
// result or mutate the template's lexical ancestry.
|
|
@@ -23,6 +24,16 @@ export class FrameLazy extends FrameExpr {
|
|
|
23
24
|
writable: true,
|
|
24
25
|
value: void 0
|
|
25
26
|
});
|
|
27
|
+
// The optional `^^` output contract, complementary to the `^` input
|
|
28
|
+
// signature above. A declared return schema gates the body's result the way
|
|
29
|
+
// `signature` gates the argument, and nothing else: it is a type assertion
|
|
30
|
+
// on the exposed value, not a freeze, copy, conversion, or callback.
|
|
31
|
+
Object.defineProperty(this, "returnContract", {
|
|
32
|
+
enumerable: true,
|
|
33
|
+
configurable: true,
|
|
34
|
+
writable: true,
|
|
35
|
+
value: void 0
|
|
36
|
+
});
|
|
26
37
|
}
|
|
27
38
|
bindSignature(signature) {
|
|
28
39
|
if (signature instanceof FrameGroup) {
|
|
@@ -30,6 +41,38 @@ export class FrameLazy extends FrameExpr {
|
|
|
30
41
|
}
|
|
31
42
|
return this;
|
|
32
43
|
}
|
|
44
|
+
/**
|
|
45
|
+
* Records the `^^` return contract. The schema is kept as written and only
|
|
46
|
+
* consulted after the body runs, so copying the closure template, which the
|
|
47
|
+
* per-evaluation `bind` above does, carries the contract to the bound copy.
|
|
48
|
+
*/
|
|
49
|
+
bindReturn(returnContract) {
|
|
50
|
+
this.returnContract = returnContract;
|
|
51
|
+
return this;
|
|
52
|
+
}
|
|
53
|
+
/** The declared `^^` output schema, or undefined when none was bound. */
|
|
54
|
+
returnSchema() {
|
|
55
|
+
return this.returnContract;
|
|
56
|
+
}
|
|
57
|
+
/**
|
|
58
|
+
* Checks a completed body result against the declared `^^` contract. An
|
|
59
|
+
* undeclared closure keeps HC's implicit constructive behavior and returns
|
|
60
|
+
* the result unchanged. A result that is already a failure is propagated
|
|
61
|
+
* without a second complaint, since the body never produced a value to
|
|
62
|
+
* expose. Otherwise a non-conforming result is refused as a `$!.type-error`,
|
|
63
|
+
* naming the declared schema and the offending value.
|
|
64
|
+
*/
|
|
65
|
+
checkReturn(result) {
|
|
66
|
+
const contract = this.returnContract;
|
|
67
|
+
if (!contract)
|
|
68
|
+
return result;
|
|
69
|
+
if (result.is.error)
|
|
70
|
+
return result;
|
|
71
|
+
if (isFrameMatcher(contract) && !contract.match(result).matched) {
|
|
72
|
+
return Frame.error(`$!.type-error ${contract.toString()} ${result.toString()}`);
|
|
73
|
+
}
|
|
74
|
+
return result;
|
|
75
|
+
}
|
|
33
76
|
string_open() {
|
|
34
77
|
return FrameLazy.LAZY_BEGIN;
|
|
35
78
|
}
|
|
@@ -144,7 +187,8 @@ export class FrameLazy extends FrameExpr {
|
|
|
144
187
|
return prepared;
|
|
145
188
|
const enclosing = capturedScopes.get(this) ?? this.legacyCapture();
|
|
146
189
|
const scope = EvaluationScope.call(prepared, parameter, this, enclosing, receiverState);
|
|
147
|
-
|
|
190
|
+
const result = FrameExpr.evaluateBody(this.data, scope, this.is.sequence === true);
|
|
191
|
+
return this.checkReturn(result);
|
|
148
192
|
}
|
|
149
193
|
legacyCapture() {
|
|
150
194
|
return this.up && !this.up.is.missing
|
|
@@ -14,9 +14,6 @@ export class FrameNote extends FrameAtom {
|
|
|
14
14
|
static key(source, where) {
|
|
15
15
|
return new FrameNote("!", source, where);
|
|
16
16
|
}
|
|
17
|
-
static type(source) {
|
|
18
|
-
return new FrameNote("<>", source);
|
|
19
|
-
}
|
|
20
17
|
static index(source) {
|
|
21
18
|
return new FrameNote(">", source);
|
|
22
19
|
}
|
|
@@ -54,7 +51,7 @@ export class FrameNote extends FrameAtom {
|
|
|
54
51
|
}
|
|
55
52
|
/** Diagnostic notes that represent failures, rather than test progress. */
|
|
56
53
|
isDiagnosticFailure() {
|
|
57
|
-
return ["!", "
|
|
54
|
+
return ["!", ">", "-"].includes(this.data);
|
|
58
55
|
}
|
|
59
56
|
in(_contexts = [Frame.nil]) {
|
|
60
57
|
return this;
|
|
@@ -76,7 +73,10 @@ export class FrameNote extends FrameAtom {
|
|
|
76
73
|
return FrameNote.NOTE_END;
|
|
77
74
|
}
|
|
78
75
|
toString() {
|
|
79
|
-
|
|
76
|
+
const label = FrameNote.SYSTEM_ERROR_LABELS.has(this.data)
|
|
77
|
+
? "!"
|
|
78
|
+
: this.data;
|
|
79
|
+
return this.string_prefix() + label + this.meta_string();
|
|
80
80
|
}
|
|
81
81
|
setLabel(data, source) {
|
|
82
82
|
const label = FrameNote.LABELS.en[data];
|
|
@@ -130,8 +130,18 @@ Object.defineProperty(FrameNote, "LABELS", {
|
|
|
130
130
|
"-": "test-fail",
|
|
131
131
|
"~": "test-unimplemented",
|
|
132
132
|
"=": "test-summary",
|
|
133
|
-
"<>": "type-mismatch",
|
|
134
133
|
">": "bounds-exceeded",
|
|
135
134
|
},
|
|
136
135
|
}
|
|
137
136
|
});
|
|
137
|
+
/**
|
|
138
|
+
* Note labels that render as a system error, `$!.<label name>` (spec a13/14
|
|
139
|
+
* §3). Every failure the interpreter reports starts with `$!`; only the
|
|
140
|
+
* testdoc report labels keep their own sigils.
|
|
141
|
+
*/
|
|
142
|
+
Object.defineProperty(FrameNote, "SYSTEM_ERROR_LABELS", {
|
|
143
|
+
enumerable: true,
|
|
144
|
+
configurable: true,
|
|
145
|
+
writable: true,
|
|
146
|
+
value: new Set(["!", ">"])
|
|
147
|
+
});
|
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
import { Frame } from "./frame.js";
|
|
2
|
+
import { FrameAtom } from "./frame-atom.js";
|
|
3
|
+
import { FrameString } from "./frame-string.js";
|
|
4
|
+
import { describedKind, kindOf, reasonOf } from "./error-kind.js";
|
|
5
|
+
/** A symbol's spelling, without importing `FrameSymbol` (load order). */
|
|
6
|
+
const spelling = (frame) => frame.className() === "FrameSymbol"
|
|
7
|
+
? frame.spelling()
|
|
8
|
+
: undefined;
|
|
9
|
+
/**
|
|
10
|
+
* The observations of the handlers now running, innermost last.
|
|
11
|
+
*
|
|
12
|
+
* This relies on evaluation being synchronous: a handler runs to completion
|
|
13
|
+
* inside `during`, so pushes and pops nest exactly, and `finally` pops even
|
|
14
|
+
* when evaluation throws. Nothing in `lib/` suspends evaluation (`HCLang.call`
|
|
15
|
+
* returns a promise but evaluates synchronously before resolving it). If
|
|
16
|
+
* evaluation ever suspends while a handler runs, this stack must move into the
|
|
17
|
+
* evaluation context, or `$#` would leak into an interleaved evaluation.
|
|
18
|
+
*/
|
|
19
|
+
const running = [];
|
|
20
|
+
/**
|
|
21
|
+
* What a catch handler receives (spec a13/14 §6, §7): a non-propagating view
|
|
22
|
+
* of one error.
|
|
23
|
+
*
|
|
24
|
+
* It holds the original error, never a copy, and is not itself an error.
|
|
25
|
+
* `.!` reads the original, so answering it declines or re-raises with the
|
|
26
|
+
* same frame; `.#` reads the reason as text. Any other member is missing. It
|
|
27
|
+
* prints as `$#.reason`. A schema candidate written as an error kind matches
|
|
28
|
+
* it when the kinds agree (`$# ~ <$!.division-by-zero>`).
|
|
29
|
+
*/
|
|
30
|
+
export class FrameObservation extends FrameAtom {
|
|
31
|
+
constructor(original) {
|
|
32
|
+
super();
|
|
33
|
+
Object.defineProperty(this, "original", {
|
|
34
|
+
enumerable: true,
|
|
35
|
+
configurable: true,
|
|
36
|
+
writable: true,
|
|
37
|
+
value: original
|
|
38
|
+
});
|
|
39
|
+
}
|
|
40
|
+
/** The observation of the innermost running handler, if any. */
|
|
41
|
+
static current() {
|
|
42
|
+
return running.at(-1);
|
|
43
|
+
}
|
|
44
|
+
/** Runs `body` with this as the current observation. */
|
|
45
|
+
during(body) {
|
|
46
|
+
running.push(this);
|
|
47
|
+
try {
|
|
48
|
+
return body();
|
|
49
|
+
}
|
|
50
|
+
finally {
|
|
51
|
+
running.pop();
|
|
52
|
+
}
|
|
53
|
+
}
|
|
54
|
+
/** The original's kind, `$!.reason` or `$!!.reason`. */
|
|
55
|
+
kind() {
|
|
56
|
+
return kindOf(this.original);
|
|
57
|
+
}
|
|
58
|
+
matchesKind(candidate) {
|
|
59
|
+
const kind = this.kind();
|
|
60
|
+
return kind !== undefined && describedKind(candidate) === kind;
|
|
61
|
+
}
|
|
62
|
+
/** `.!` is the original error, `.#` its reason; nothing else is a member. */
|
|
63
|
+
call(argument, _parameter = Frame.nil) {
|
|
64
|
+
switch (spelling(argument)) {
|
|
65
|
+
case "!":
|
|
66
|
+
return this.original;
|
|
67
|
+
case "#":
|
|
68
|
+
return new FrameString(reasonOf(this.original) ?? "");
|
|
69
|
+
default:
|
|
70
|
+
return Frame.error(`$!.name-missing ${this.toString()}${argument.toString()}`);
|
|
71
|
+
}
|
|
72
|
+
}
|
|
73
|
+
in(_input = []) {
|
|
74
|
+
return this;
|
|
75
|
+
}
|
|
76
|
+
toString() {
|
|
77
|
+
return `$#.${reasonOf(this.original) ?? ""}`;
|
|
78
|
+
}
|
|
79
|
+
dataString() {
|
|
80
|
+
return this.toString();
|
|
81
|
+
}
|
|
82
|
+
}
|
|
83
|
+
/**
|
|
84
|
+
* Evaluates a handler and handles `failure` with it, both with the
|
|
85
|
+
* observation as the current `$#`. A closure is called with the observation;
|
|
86
|
+
* any other value is the replacement itself. A handler that is itself an error
|
|
87
|
+
* is the result (spec a13/12 §2.3).
|
|
88
|
+
*/
|
|
89
|
+
Frame.catchWith = (failure, evaluate) => {
|
|
90
|
+
const observation = new FrameObservation(failure);
|
|
91
|
+
return observation.during(() => {
|
|
92
|
+
const handler = evaluate();
|
|
93
|
+
if (handler.isError())
|
|
94
|
+
return handler;
|
|
95
|
+
return handler.isClosure() ? handler.call(observation) : handler;
|
|
96
|
+
});
|
|
97
|
+
};
|
|
@@ -1,10 +1,13 @@
|
|
|
1
1
|
import { Frame } from "./frame.js";
|
|
2
2
|
import { FrameAtom } from "./frame-atom.js";
|
|
3
3
|
import { FrameNote } from "./frame-note.js";
|
|
4
|
+
import { FrameObservation } from "./frame-observation.js";
|
|
4
5
|
import { FrameSymbol } from "./frame-symbol.js";
|
|
6
|
+
import { describeAs } from "./error-kind.js";
|
|
5
7
|
import { EvaluationScope } from "./evaluation-scope.js";
|
|
6
8
|
import { ScanDisposition, } from "../scan.js";
|
|
7
|
-
|
|
9
|
+
/** The testdoc report labels, the only semicolon-delimited notes left. */
|
|
10
|
+
const NOTE_PREFIXES = new Set(["+", "-", "~", "="]);
|
|
8
11
|
const complete = (frame) => ({
|
|
9
12
|
disposition: ScanDisposition.CompleteRedispatch,
|
|
10
13
|
frame,
|
|
@@ -13,26 +16,44 @@ const invalidDollar = (source, char = "") => ({
|
|
|
13
16
|
disposition: ScanDisposition.Error,
|
|
14
17
|
message: `invalid dollar form: $${source}${char === "\n" ? "\\n" : char}`,
|
|
15
18
|
});
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
19
|
+
const REASON = /^[A-Za-z_][A-Za-z0-9_-]*$/;
|
|
20
|
+
/**
|
|
21
|
+
* An error literal is a source atom; its flag is not a lexical failure.
|
|
22
|
+
*
|
|
23
|
+
* Source code raises only user errors (spec a13/14 §1). `$!!.reason` is one.
|
|
24
|
+
* `$!.reason` names the system kind: it raises the user error with the same
|
|
25
|
+
* reason, and a schema holding it matches that system kind (§4).
|
|
26
|
+
*/
|
|
27
|
+
const errorLiteral = (source) => {
|
|
28
|
+
const user = source.startsWith("!!.");
|
|
29
|
+
const reason = source.slice(user ? 3 : 2);
|
|
30
|
+
if (!REASON.test(reason))
|
|
31
|
+
return invalidDollar(source);
|
|
32
|
+
const error = Frame.error(`$!!.${reason}`);
|
|
33
|
+
return complete(user ? error : describeAs(error, `$!.${reason}`));
|
|
34
|
+
};
|
|
20
35
|
/** A boundary starts another token rather than extending a dollar form. */
|
|
21
36
|
const isBoundary = (char) => !/[$\w-]/.test(char);
|
|
22
37
|
/**
|
|
23
|
-
* Recognizes
|
|
24
|
-
*
|
|
25
|
-
*
|
|
38
|
+
* Recognizes the dollar family behind one `$` registration: the anchors `$`,
|
|
39
|
+
* `$$` and `$#`, the catch operator `$!`, the error literals `$!.reason` and
|
|
40
|
+
* `$!!.reason`, and the testdoc report notes. Longest match keeps `$$` atomic,
|
|
41
|
+
* while unsupported `$word` forms fail on their first character instead of
|
|
42
|
+
* consuming an expression.
|
|
26
43
|
*/
|
|
27
44
|
const recognizeDollar = (symbol, source = "") => {
|
|
28
45
|
const char = symbol.toString();
|
|
29
46
|
if (source === "") {
|
|
30
|
-
if (char === "$") {
|
|
47
|
+
if (char === "$" || char === "!" || char === "#") {
|
|
31
48
|
return { disposition: ScanDisposition.Consume };
|
|
32
49
|
}
|
|
33
|
-
if (NOTE_PREFIXES.has(char)
|
|
50
|
+
if (NOTE_PREFIXES.has(char)) {
|
|
34
51
|
return { disposition: ScanDisposition.Consume };
|
|
35
52
|
}
|
|
53
|
+
// The removed `$>…;` and `$<>…;` note forms stay lexical errors rather
|
|
54
|
+
// than reading as an anchor followed by an operator.
|
|
55
|
+
if (char === "<" || char === ">")
|
|
56
|
+
return invalidDollar(source, char);
|
|
36
57
|
return isBoundary(char)
|
|
37
58
|
? complete(FrameScopeAnchor.file())
|
|
38
59
|
: invalidDollar(source, char);
|
|
@@ -44,23 +65,34 @@ const recognizeDollar = (symbol, source = "") => {
|
|
|
44
65
|
? complete(FrameScopeAnchor.host())
|
|
45
66
|
: invalidDollar(source, char);
|
|
46
67
|
}
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
68
|
+
if (source === "#") {
|
|
69
|
+
return isBoundary(char)
|
|
70
|
+
? complete(new FrameObservationAnchor())
|
|
71
|
+
: invalidDollar(source, char);
|
|
72
|
+
}
|
|
73
|
+
// `$!` is the catch operator unless a dot or a second `!` follows. A word
|
|
74
|
+
// character is the removed `$!word;` note form, so it is rejected.
|
|
75
|
+
if (source === "!") {
|
|
76
|
+
if (char === "." || char === "!") {
|
|
77
|
+
return { disposition: ScanDisposition.Consume };
|
|
78
|
+
}
|
|
79
|
+
return isBoundary(char)
|
|
80
|
+
? complete(new FrameCatch())
|
|
52
81
|
: invalidDollar(source, char);
|
|
53
82
|
}
|
|
54
|
-
if (source === "
|
|
55
|
-
return
|
|
83
|
+
if (source === "!!") {
|
|
84
|
+
return char === "."
|
|
85
|
+
? { disposition: ScanDisposition.Consume }
|
|
86
|
+
: invalidDollar(source, char);
|
|
56
87
|
}
|
|
57
|
-
if (source.startsWith("!.")) {
|
|
58
|
-
const
|
|
88
|
+
if (source.startsWith("!.") || source.startsWith("!!.")) {
|
|
89
|
+
const start = source.startsWith("!!.") ? 3 : 2;
|
|
90
|
+
const accepted = source.length === start
|
|
59
91
|
? /^[A-Za-z_]$/.test(char)
|
|
60
92
|
: /^[A-Za-z0-9_-]$/.test(char);
|
|
61
93
|
return accepted
|
|
62
94
|
? { disposition: ScanDisposition.Consume }
|
|
63
|
-
:
|
|
95
|
+
: errorLiteral(source);
|
|
64
96
|
}
|
|
65
97
|
if (char === FrameNote.NOTE_END) {
|
|
66
98
|
return { disposition: ScanDisposition.CompleteRedispatch };
|
|
@@ -72,10 +104,15 @@ const finishDollar = (source = "") => {
|
|
|
72
104
|
return complete(FrameScopeAnchor.file());
|
|
73
105
|
if (source === "$")
|
|
74
106
|
return complete(FrameScopeAnchor.host());
|
|
75
|
-
if (source === "
|
|
107
|
+
if (source === "#")
|
|
108
|
+
return complete(new FrameObservationAnchor());
|
|
109
|
+
if (source === "!")
|
|
110
|
+
return complete(new FrameCatch());
|
|
111
|
+
if (source === "!!")
|
|
76
112
|
return invalidDollar(source);
|
|
77
|
-
if (source.startsWith("!."))
|
|
78
|
-
return
|
|
113
|
+
if (source.startsWith("!.") || source.startsWith("!!.")) {
|
|
114
|
+
return errorLiteral(source);
|
|
115
|
+
}
|
|
79
116
|
return {
|
|
80
117
|
disposition: ScanDisposition.Error,
|
|
81
118
|
message: `unterminated FrameNote: $${source}`,
|
|
@@ -184,3 +221,35 @@ Object.defineProperty(FrameScopeAnchor, "SYNTAX", {
|
|
|
184
221
|
fromSource: (source) => new FrameNote(source),
|
|
185
222
|
}
|
|
186
223
|
});
|
|
224
|
+
/**
|
|
225
|
+
* The catch operator `$!` (spec a13/14 §5). It is syntax: expression
|
|
226
|
+
* reduction (`FrameExpr`) recognizes it among an expression's terms, so it
|
|
227
|
+
* never evaluates as a value of its own.
|
|
228
|
+
*/
|
|
229
|
+
export class FrameCatch extends FrameAtom {
|
|
230
|
+
in(_input = []) {
|
|
231
|
+
return this;
|
|
232
|
+
}
|
|
233
|
+
string_prefix() {
|
|
234
|
+
return "$!";
|
|
235
|
+
}
|
|
236
|
+
toData() {
|
|
237
|
+
return "";
|
|
238
|
+
}
|
|
239
|
+
}
|
|
240
|
+
/**
|
|
241
|
+
* `$#`, the anchor for the observation of the innermost catch handler now
|
|
242
|
+
* running (spec a13/14 §6). Outside every handler it is an error.
|
|
243
|
+
*/
|
|
244
|
+
export class FrameObservationAnchor extends FrameAtom {
|
|
245
|
+
in(_input = []) {
|
|
246
|
+
return FrameObservation.current() ??
|
|
247
|
+
Frame.error("$!.observation-missing");
|
|
248
|
+
}
|
|
249
|
+
string_prefix() {
|
|
250
|
+
return "$#";
|
|
251
|
+
}
|
|
252
|
+
toData() {
|
|
253
|
+
return "";
|
|
254
|
+
}
|
|
255
|
+
}
|
|
@@ -14,7 +14,7 @@ import { FrameCurry } from "../ops/frame-curry.js";
|
|
|
14
14
|
import { isFrameMatcher } from "./frame-match.js";
|
|
15
15
|
import { NilContext } from "./context.js";
|
|
16
16
|
import { EvaluationScope } from "./evaluation-scope.js";
|
|
17
|
-
import { completeAtEnd, includeOrReserve, TIME_DELIMITER, } from "./atom-syntax.js";
|
|
17
|
+
import { completeAtEnd, includeOrEnd, includeOrReserve, TIME_DELIMITER, } from "./atom-syntax.js";
|
|
18
18
|
import { ScanDisposition, } from "../scan.js";
|
|
19
19
|
/**
|
|
20
20
|
* The echo a declaration answers, which is a declaration and not an element.
|
|
@@ -488,6 +488,15 @@ Object.defineProperty(FrameOperator, "SYNTAX", {
|
|
|
488
488
|
SIGIL_STARTS: FrameOperator.SIGIL_STARTS,
|
|
489
489
|
recognize: (symbol, source = "") => {
|
|
490
490
|
const char = symbol.toString();
|
|
491
|
+
// `->` is one operator, the effect-boundary arrow (006.17 §3-4). The
|
|
492
|
+
// hyphen that opens it is an ordinary operator start; the `>` that would
|
|
493
|
+
// otherwise redispatch to schema syntax is swallowed here so `a -> b`
|
|
494
|
+
// lexes as subject, arrow, callback rather than `a -` then an
|
|
495
|
+
// unterminated `<...>`. Only a lone trailing `-` claims the `>`; a longer
|
|
496
|
+
// operator run ending in `-` keeps the old boundary.
|
|
497
|
+
if (char === ">" && source === "-") {
|
|
498
|
+
return includeOrEnd(true);
|
|
499
|
+
}
|
|
491
500
|
// Comparison brackets belong to the schema syntax, not to an operator.
|
|
492
501
|
if (char === "<" || char === ">") {
|
|
493
502
|
return { disposition: ScanDisposition.CompleteRedispatch };
|
package/esm/lib/frames/frame.js
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import { NilContext } from "./context.js";
|
|
2
2
|
import { renderNested } from "./stringify.js";
|
|
3
|
+
import { hasEffectSubscribers, notifyEffect } from "./effect-registry.js";
|
|
3
4
|
/** Visibility levels for logical frame bindings. */
|
|
4
5
|
export var Visibility;
|
|
5
6
|
(function (Visibility) {
|
|
@@ -253,12 +254,24 @@ export class MetaFrame {
|
|
|
253
254
|
}
|
|
254
255
|
/**
|
|
255
256
|
* set adds a new key-value pair to the current context.
|
|
257
|
+
*
|
|
258
|
+
* This is the single commit point for a named-property mutation, so it is
|
|
259
|
+
* where an `A -> B` effect boundary observes a *committed* change (006.17
|
|
260
|
+
* §3-4): after the write lands, any callback registered on this value is a
|
|
261
|
+
* new invocation. Firing is a no-op for the common case of a value with no
|
|
262
|
+
* subscribers (a `WeakMap.has` check), and is skipped for a write that does
|
|
263
|
+
* not change the stored value, so a re-assignment of the same frame is not a
|
|
264
|
+
* mutation.
|
|
256
265
|
*/
|
|
257
266
|
set(key, value) {
|
|
258
267
|
if (this.meta === NilContext) {
|
|
259
268
|
this.meta = {};
|
|
260
269
|
}
|
|
270
|
+
const previous = this.meta[key];
|
|
261
271
|
this.meta[key] = value;
|
|
272
|
+
if (previous !== value && hasEffectSubscribers(this)) {
|
|
273
|
+
notifyEffect(this);
|
|
274
|
+
}
|
|
262
275
|
return this;
|
|
263
276
|
}
|
|
264
277
|
/** Whether this frame carries an explicitly declared parent. */
|
|
@@ -802,6 +815,14 @@ export class Frame extends MetaFrame {
|
|
|
802
815
|
isEqualTo(other) {
|
|
803
816
|
return this.equals(other) === Frame.all;
|
|
804
817
|
}
|
|
818
|
+
/**
|
|
819
|
+
* Whether this frame is an observed error of the kind `candidate` names
|
|
820
|
+
* (spec a13/14 §7). Only a catch handler's observation answers yes; a
|
|
821
|
+
* schema candidate written as `$!.reason` or `$!!.reason` names the kind.
|
|
822
|
+
*/
|
|
823
|
+
matchesKind(_candidate) {
|
|
824
|
+
return false;
|
|
825
|
+
}
|
|
805
826
|
/**
|
|
806
827
|
* className returns the name of the class as a string.
|
|
807
828
|
* @returns a string
|
|
@@ -998,6 +1019,11 @@ export class Frame extends MetaFrame {
|
|
|
998
1019
|
replaced = true;
|
|
999
1020
|
}
|
|
1000
1021
|
}
|
|
1022
|
+
// An element-plane commit is a mutation too; a copy-on-write install lands
|
|
1023
|
+
// on a fresh copy that carries no subscribers, so it never fires here.
|
|
1024
|
+
if (replaced && hasEffectSubscribers(this)) {
|
|
1025
|
+
notifyEffect(this);
|
|
1026
|
+
}
|
|
1001
1027
|
return replaced;
|
|
1002
1028
|
}
|
|
1003
1029
|
static quantityOperator(argument) {
|
|
@@ -1167,3 +1193,16 @@ Object.defineProperty(Frame, "globals", {
|
|
|
1167
1193
|
writable: true,
|
|
1168
1194
|
value: Frame.missing
|
|
1169
1195
|
});
|
|
1196
|
+
/**
|
|
1197
|
+
* Handles `failure` with the catch handler that `handler` evaluates to
|
|
1198
|
+
* (spec a13/14 §5). The observation is current while the handler is both
|
|
1199
|
+
* evaluated and called. `frame-observation.ts` installs the real one when it
|
|
1200
|
+
* loads; it is late bound so that expression reduction need not import it
|
|
1201
|
+
* (load order).
|
|
1202
|
+
*/
|
|
1203
|
+
Object.defineProperty(Frame, "catchWith", {
|
|
1204
|
+
enumerable: true,
|
|
1205
|
+
configurable: true,
|
|
1206
|
+
writable: true,
|
|
1207
|
+
value: (failure) => failure
|
|
1208
|
+
});
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
import { isEffectObserver } from "./effect-registry.js";
|
|
2
|
+
/** Builds a plan from an explicit value→partition-id map. */
|
|
3
|
+
export function partitionPlan(placement) {
|
|
4
|
+
const ids = new Map(placement);
|
|
5
|
+
return { partitionOf: (value) => ids.get(value) };
|
|
6
|
+
}
|
|
7
|
+
/** Whether two placements name different partitions (a proposed boundary). */
|
|
8
|
+
function crosses(a, b) {
|
|
9
|
+
// Unplaced values are local; a boundary exists only between two named,
|
|
10
|
+
// distinct partitions.
|
|
11
|
+
return a !== undefined && b !== undefined && a !== b;
|
|
12
|
+
}
|
|
13
|
+
/**
|
|
14
|
+
* Checks a partition plan: accepts local mutable dependencies and transactional
|
|
15
|
+
* dependencies anywhere, and rejects a cross-partition *mutable* dependency
|
|
16
|
+
* that lacks an explicit effect boundary on its managed value.
|
|
17
|
+
*
|
|
18
|
+
* `arrows` lets a static (pre-evaluation) caller declare the explicit
|
|
19
|
+
* `[managed, observer]` effect boundaries of a plan; when omitted, coverage is
|
|
20
|
+
* read from the live effect registry, so an `A -> C` that actually ran makes
|
|
21
|
+
* C's dependency on A legal, and nothing else.
|
|
22
|
+
*/
|
|
23
|
+
export function checkPartitions(edges, plan, arrows) {
|
|
24
|
+
const isCovered = (managed, observer) => arrows
|
|
25
|
+
? arrows.some(([a, c]) => a === managed && c === observer)
|
|
26
|
+
: isEffectObserver(managed, observer);
|
|
27
|
+
const errors = [];
|
|
28
|
+
for (const edge of edges) {
|
|
29
|
+
if (edge.kind !== "mutable")
|
|
30
|
+
continue; // transactional never needs a boundary
|
|
31
|
+
const from = plan.partitionOf(edge.observer);
|
|
32
|
+
const to = plan.partitionOf(edge.managed);
|
|
33
|
+
if (!crosses(from, to))
|
|
34
|
+
continue; // local mutable dependency is fine
|
|
35
|
+
if (isCovered(edge.managed, edge.observer))
|
|
36
|
+
continue; // its own arrow
|
|
37
|
+
errors.push({
|
|
38
|
+
managed: edge.managed,
|
|
39
|
+
observer: edge.observer,
|
|
40
|
+
fromPartition: from,
|
|
41
|
+
toPartition: to,
|
|
42
|
+
reason: "$!.partition-error cross-partition mutable dependency without an effect boundary",
|
|
43
|
+
});
|
|
44
|
+
}
|
|
45
|
+
return { ok: errors.length === 0, errors };
|
|
46
|
+
}
|
package/esm/lib/frames.js
CHANGED
|
@@ -22,7 +22,8 @@ export { FrameList } from "./frames/frame-list.js";
|
|
|
22
22
|
export { FrameName } from "./frames/frame-name.js";
|
|
23
23
|
export { FrameWord } from "./frames/frame-word.js";
|
|
24
24
|
export { FrameNote } from "./frames/frame-note.js";
|
|
25
|
-
export { FrameScopeAnchor, } from "./frames/frame-scope-anchor.js";
|
|
25
|
+
export { FrameCatch, FrameObservationAnchor, FrameScopeAnchor, } from "./frames/frame-scope-anchor.js";
|
|
26
|
+
export { FrameObservation } from "./frames/frame-observation.js";
|
|
26
27
|
export { FrameNumeric, NUMERIC_RANK, } from "./frames/frame-numeric.js";
|
|
27
28
|
export { FrameInt } from "./frames/frame-int.js";
|
|
28
29
|
export { FrameCount } from "./frames/frame-count.js";
|
|
@@ -49,4 +50,6 @@ export { Frame, } from "./frames/frame.js";
|
|
|
49
50
|
export { MetaFrame, Visibility } from "./frames/meta-frame.js";
|
|
50
51
|
export { ScanDisposition, } from "./scan.js";
|
|
51
52
|
export { contextEqual, contextString, NilContext, } from "./frames/context.js";
|
|
53
|
+
export { hasEffectSubscribers, installEffectInvoker, isEffectObserver, notifyEffect, registerEffect, } from "./frames/effect-registry.js";
|
|
54
|
+
export { checkPartitions, partitionPlan, } from "./frames/partition-check.js";
|
|
52
55
|
Frame.globals = Ops;
|
|
@@ -3,6 +3,20 @@ import { Frame } from "../frames/frame.js";
|
|
|
3
3
|
import { FrameLazy } from "../frames/frame-lazy.js";
|
|
4
4
|
import { FrameLiteral } from "../frames/frame-symbol.js";
|
|
5
5
|
import { isFrameMatcher } from "../frames/frame-match.js";
|
|
6
|
+
import { installEffectInvoker, registerEffect, } from "../frames/effect-registry.js";
|
|
7
|
+
// Install the one strategy the effect registry uses to invoke a registered
|
|
8
|
+
// callback. A callback is an ordinary closure, so a committed mutation calls it
|
|
9
|
+
// with the managed value as its argument — a *new invocation*, never an
|
|
10
|
+
// alteration of a value it returned earlier. Installed here, where FrameLazy is
|
|
11
|
+
// already imported, so `frame.ts` need not depend on closure machinery.
|
|
12
|
+
installEffectInvoker((callback, managed) => callback.call(managed, Frame.nil));
|
|
13
|
+
/** The closure a declaration echo now names, if it names one. */
|
|
14
|
+
const boundClosure = (source) => {
|
|
15
|
+
if (!(source instanceof FrameLiteral) || !source.binding)
|
|
16
|
+
return undefined;
|
|
17
|
+
const bound = source.binding.target.get(source.binding.key);
|
|
18
|
+
return bound instanceof FrameLazy ? bound : undefined;
|
|
19
|
+
};
|
|
6
20
|
/** Test whether a value belongs to a first-class type or schema. */
|
|
7
21
|
export const HasType = (source, type) => {
|
|
8
22
|
if (type === Frame.all)
|
|
@@ -23,3 +37,45 @@ export const BindType = (source, body) => {
|
|
|
23
37
|
}
|
|
24
38
|
return source;
|
|
25
39
|
};
|
|
40
|
+
/**
|
|
41
|
+
* Attach an output-type contract to a declared closure, the `^^` complement of
|
|
42
|
+
* the `^` input signature. The left operand is the declaration echo produced
|
|
43
|
+
* by `^` (or by the declaration itself), whose name now holds the closure; the
|
|
44
|
+
* right operand is the schema the closure's result must conform to. Binding a
|
|
45
|
+
* return contract neither freezes nor rewrites the closure beyond recording the
|
|
46
|
+
* schema it will check at call time, and the echo is returned unchanged so a
|
|
47
|
+
* `^^` can follow a `^` in one left-associative expression. A `^^` with no
|
|
48
|
+
* closure to bind, or a left operand that is not a live declaration, is left
|
|
49
|
+
* alone rather than erroring, matching how `^` ignores a shape it cannot bind.
|
|
50
|
+
*/
|
|
51
|
+
export const BindReturn = (source, returnType) => {
|
|
52
|
+
const closure = boundClosure(source);
|
|
53
|
+
if (closure) {
|
|
54
|
+
closure.bindReturn(returnType);
|
|
55
|
+
}
|
|
56
|
+
return source;
|
|
57
|
+
};
|
|
58
|
+
/**
|
|
59
|
+
* Register an effect boundary: `A -> B` (occurrence/history 006.17 §3-4).
|
|
60
|
+
*
|
|
61
|
+
* `A` is the managed value on the left; `B` is the callback on the right. This
|
|
62
|
+
* records `B` as an observer of `A`'s managed referent so that a *subsequent
|
|
63
|
+
* committed mutation of that value, by any actor through any alias*, is a new
|
|
64
|
+
* invocation of `B`. The arrow is an effect boundary, not a write-authority
|
|
65
|
+
* boundary: registration neither grants nor withholds write permission, does
|
|
66
|
+
* not freeze/copy/convert `A`, and is independent of whether any handle to `A`
|
|
67
|
+
* is mutable.
|
|
68
|
+
*
|
|
69
|
+
* The managed identity is `A`'s referent — the same frame a mutating write
|
|
70
|
+
* lands its `set`/`replaceMember` on — so a handle (`a_`) and the value it
|
|
71
|
+
* wraps register one and the same subscription. The arrow answers `A`
|
|
72
|
+
* unchanged, so it composes left-associatively like `^`/`^^` and leaves the
|
|
73
|
+
* one-shot/return spellings untouched. A left operand with no mutable identity
|
|
74
|
+
* (a bare scalar) registers against its own frame; nothing fires until that
|
|
75
|
+
* frame is actually mutated, which a scalar never is.
|
|
76
|
+
*/
|
|
77
|
+
export const Arrow = (source, callback) => {
|
|
78
|
+
const managed = source.referent();
|
|
79
|
+
registerEffect(managed, callback);
|
|
80
|
+
return source;
|
|
81
|
+
};
|
package/esm/lib/ops.js
CHANGED
|
@@ -3,7 +3,7 @@ import { FrameOps } from "./ops/frame-ops.js";
|
|
|
3
3
|
import { MapElements, MapMembers, ReduceElements, ReduceMembers, SpliceElements, } from "./ops/iterators.js";
|
|
4
4
|
import { Add, Divide, Equals, GreaterThan, GreaterThanOrEqual, Identical, LessThan, LessThanOrEqual, Modulo, Multiply, Power, Subtract, TypeEquals, } from "./ops/math.js";
|
|
5
5
|
import { IdenticalMember, Member, TypedMember } from "./ops/membership.js";
|
|
6
|
-
import { BindType } from "./ops/type-operations.js";
|
|
6
|
+
import { Arrow, BindReturn, BindType } from "./ops/type-operations.js";
|
|
7
7
|
export { FrameCurry } from "./ops/frame-curry.js";
|
|
8
8
|
export const Ops = new FrameOps({
|
|
9
9
|
"&": MapElements,
|
|
@@ -32,4 +32,6 @@ export const Ops = new FrameOps({
|
|
|
32
32
|
"~~": TypedMember,
|
|
33
33
|
"~~~": IdenticalMember,
|
|
34
34
|
"^": BindType,
|
|
35
|
+
"^^": BindReturn,
|
|
36
|
+
"->": Arrow,
|
|
35
37
|
});
|
package/esm/lib/version.js
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
export const VERSION = "0.
|
|
1
|
+
export const VERSION = "0.41.0";
|