hclang 0.39.0 → 0.40.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.
@@ -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 `$!.invalid-demi`, a named error, as Figures refuses an",
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); _^^} : {$!.invalid-scale}};",
1459
+ " (k ~ (0.<>)) ? {@left (l * k); @right (r * k); _^^} : {$!!.invalid-scale}};",
1460
1460
  " .toText {“Demi(” (((_^ .phase) = 2) ? {“<>”} : {“()”}) “,” (_^ .left) “,” (_^ .right) “)”}",
1461
- " ]} : {$!.invalid-demi}} : {$!.invalid-demi}};",
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
- "# $!.invalid-demi",
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
- "# [$!.invalid-demi, $!.invalid-demi, $!.invalid-demi, $!.invalid-demi, $!.invalid-demi]",
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
- "# $!.invalid-scale",
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}} : {$!.unsupported-figure}};",
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 _; $!.unsupported-figure}}};",
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} : {$!.unsupported-figure}) = e, (e.### ? {e} : {$!.unsupported-figure}) === 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 `$!.invalid-router`, a named error, as `Demi` refuses with",
2544
- "`$!.invalid-demi`.",
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
- " ]} : {$!.invalid-router}} : {$!.invalid-router}};",
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
- "# $!.invalid-router",
2605
+ "# $!!.invalid-router",
2606
2606
  "; [RotorRouter [(5 - 3), [], []], RotorRouter [2, [], 5], RotorRouter [2, (1, 2), []], RotorRouter [2, []], RotorRouter 5]",
2607
- "# [$!.invalid-router, $!.invalid-router, $!.invalid-router, $!.invalid-router, $!.invalid-router]",
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",
@@ -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.reduce((sum, item, index) => {
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
- return sum;
114
- const value = item.in(resumedScope(item, scope));
115
- if (value.is.error === true)
116
- return value;
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
- return value;
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
- return value.called_by(sum);
158
+ sum = value.called_by(sum);
159
+ continue;
126
160
  }
127
161
  if (index > 0 && value.is.operator === true) {
128
- return value.called_by(sum, Frame.nil).atSite(scope);
162
+ sum = value.called_by(sum, Frame.nil).atSite(scope);
163
+ continue;
129
164
  }
130
- return sum.call(value);
131
- }, Frame.nil);
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
+ }
@@ -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 ["!", "<>", ">", "-"].includes(this.data);
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
- return this.string_prefix() + this.data + this.meta_string();
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
- const NOTE_PREFIXES = new Set(["!", "+", "-", "~", "=", ">"]);
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
- /** A named error is a source atom; its flag is not a lexical failure. */
17
- const namedError = (source) => /^[A-Za-z_][A-Za-z0-9_-]*$/.test(source.slice(2))
18
- ? complete(Frame.error(`$${source}`))
19
- : invalidDollar(source);
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 anchors and the retained diagnostic-note spellings behind one `$`
24
- * registration. Longest match keeps `$$` atomic, while unsupported `$word`
25
- * forms fail on their first character instead of consuming an expression.
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) || 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
- // `<>` is the only retained note label beginning with `<`; `$<` and `$<<`
48
- // were vestigial control spellings and are rejected cleanly.
49
- if (source === "<") {
50
- return char === ">"
51
- ? { disposition: ScanDisposition.Consume }
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 === "!" && char === ".") {
55
- return { disposition: ScanDisposition.Consume };
83
+ if (source === "!!") {
84
+ return char === "."
85
+ ? { disposition: ScanDisposition.Consume }
86
+ : invalidDollar(source, char);
56
87
  }
57
- if (source.startsWith("!.")) {
58
- const accepted = source.length === 2
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
- : namedError(source);
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 namedError(source);
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
+ }
@@ -802,6 +802,14 @@ export class Frame extends MetaFrame {
802
802
  isEqualTo(other) {
803
803
  return this.equals(other) === Frame.all;
804
804
  }
805
+ /**
806
+ * Whether this frame is an observed error of the kind `candidate` names
807
+ * (spec a13/14 §7). Only a catch handler's observation answers yes; a
808
+ * schema candidate written as `$!.reason` or `$!!.reason` names the kind.
809
+ */
810
+ matchesKind(_candidate) {
811
+ return false;
812
+ }
805
813
  /**
806
814
  * className returns the name of the class as a string.
807
815
  * @returns a string
@@ -1167,3 +1175,16 @@ Object.defineProperty(Frame, "globals", {
1167
1175
  writable: true,
1168
1176
  value: Frame.missing
1169
1177
  });
1178
+ /**
1179
+ * Handles `failure` with the catch handler that `handler` evaluates to
1180
+ * (spec a13/14 §5). The observation is current while the handler is both
1181
+ * evaluated and called. `frame-observation.ts` installs the real one when it
1182
+ * loads; it is late bound so that expression reduction need not import it
1183
+ * (load order).
1184
+ */
1185
+ Object.defineProperty(Frame, "catchWith", {
1186
+ enumerable: true,
1187
+ configurable: true,
1188
+ writable: true,
1189
+ value: (failure) => failure
1190
+ });
@@ -14,7 +14,7 @@ export class EnumerationSchemaMatcher {
14
14
  return matchSuccess(value);
15
15
  }
16
16
  }
17
- else if (candidate.isEqualTo(value)) {
17
+ else if (candidate.isEqualTo(value) || value.matchesKind(candidate)) {
18
18
  return matchSuccess(value);
19
19
  }
20
20
  }
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";
@@ -1 +1 @@
1
- export const VERSION = "0.39.0";
1
+ export const VERSION = "0.40.0";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "hclang",
3
- "version": "0.39.0",
3
+ "version": "0.40.0",
4
4
  "description": "Homoiconic C command-line interpreter and REPL",
5
5
  "keywords": [
6
6
  "language",