hclang 0.33.0 → 0.34.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.
@@ -1164,45 +1164,46 @@ export const HC_SOURCES = new Map([
1164
1164
  "```",
1165
1165
  "Figures are native frames (#454; issue occurrence/figure 010.02)",
1166
1166
  "",
1167
- "A Figure is a finite, property-free nested array built from `[]`. Construction",
1168
- "is brackets, form is the value itself, immediate size is `.#`, terminal count",
1167
+ "A Figure is a finite nested array built from `[]`, read through its elements",
1168
+ "only: properties and declared parents are ignored by observations. Inlay keeps",
1169
+ "nonterminal metadata when rebuilding frames. Construction is brackets, form is the value itself, immediate size is `.#`, terminal count",
1169
1170
  "is `.##`, form equality is `=`, and identity is `===`. The empty frame is one",
1170
- "terminal: `[].#` is 0 and `[].##` is 1.",
1171
+ "terminal: `[].#` is 0 and `[].##` is 1. The signed residual `.###` is",
1172
+ "`x₁.## − x₂.## + x₃.## − …` over the immediate elements, a FrameInt that is 0",
1173
+ "for `[]` (issue occurrence/figure 010.04).",
1171
1174
  "",
1172
1175
  "There are no Figure constructors, marks, tally observers, count aliases or",
1173
1176
  "comparison wrappers. Use native operations directly. Multiplication that places",
1174
1177
  "y once per terminal of x is `x.## [y]`. A tally, when wanted, is an explicit",
1175
1178
  "construction, such as `x & {[[]]}` for one fresh mark per immediate element.",
1176
- "Native `.##` also counts atoms in mixed trees; this module's traversals stay",
1177
- "within the Figure domain so reconstruction cannot silently discard properties.",
1179
+ "Native `.##` also counts atoms in mixed trees; native `.###` answers nil on",
1180
+ "anything that is not a Figure, so this module's traversals stay in the domain.",
1178
1181
  "",
1179
1182
  "Only operations that add a traversal or calculation remain: `inlay`, `withness`, `gap` and `spin`, with `pure` and `need` for domain validation.",
1180
1183
  "The traversals validate at their public boundary; their recursive steps use",
1181
1184
  "native operations directly. Withness returns a native boolean, `<>` or `()`.",
1182
1185
  "```",
1183
1186
  "```",
1184
- "Supported domain: `pure x` accepts property-free nested arrays and rejects",
1185
- "atoms, strings and property-bearing frames.",
1187
+ "Supported domain: `pure x` accepts nested arrays, ignoring their properties",
1188
+ "and declared parents at every level, and rejects atoms, strings, groups, schemas and closures anywhere in them. It is",
1189
+ "the native `.###` check: a FrameInt, even 0, is true, and nil is false.",
1186
1190
  "```",
1187
- ".pure {.x _;",
1188
- " .go {.n _;",
1189
- " (n = []) ? {<>} : {",
1190
- " .rebuilt (n & {.e _; e});",
1191
- " (rebuilt = n) ? {(n &| {(go _) ? {[]} : {[0]}}) = []} : {()}}};",
1192
- " go x};",
1191
+ ".pure {.x _; (x.###) ? {<>} : {()}};",
1193
1192
  "```",
1194
1193
  "`need x` returns a supported frame itself, or a native refusal.",
1195
1194
  "```",
1196
1195
  ".need {.x _; (pure x) ? {x} : {unsupported-figure}};",
1197
1196
  "```",
1198
1197
  "`inlay x y` replaces every terminal of x with y, retaining nonterminal nesting.",
1199
- "The replacement is reused by identity; ancestors are freshly constructed.",
1198
+ "The replacement is reused by identity; ancestors are freshly constructed,",
1199
+ "preserving their properties and declared parents. A terminal is recognized by",
1200
+ "its element count; its replacement is y itself, including y’s metadata.",
1200
1201
  "The host is validated once, and the replacement can be any native value.",
1201
1202
  "```",
1202
1203
  ".inlay {.x _; .host x;",
1203
1204
  " (pure host) ? {",
1204
1205
  " {.y _;",
1205
- " .go {.n _; (n = []) ? {y} : {n & {go _}}};",
1206
+ " .go {.n _; (n.# = 0) ? {y} : {(n & {go _}) | (0 n)}};",
1206
1207
  " go host}} : {",
1207
1208
  " {.y _; need host}}};",
1208
1209
  "```",
@@ -1214,25 +1215,22 @@ export const HC_SOURCES = new Map([
1214
1215
  " .absent (fs &| {.f _; ((host &| {(_ === f) ? {[f]}}) = []) ? {[f]}});",
1215
1216
  " absent = []}};",
1216
1217
  "```",
1217
- "`gap x` is the absolute alternating sum of its immediate elements' `.##`",
1218
- "counts. The empty frame has Gap 0. The validated host needs no per-child guard.",
1218
+ "`gap x` is the absolute value of native `x.###`, the alternating sum of its",
1219
+ "immediate elements' `.##` counts, always a nonnegative FrameInt (Owner decision",
1220
+ "for #455). The empty frame has Gap 0 as a FrameInt too.",
1219
1221
  "```",
1220
1222
  ".gap {.x _; (pure x) ? {",
1221
- " .tail {(_ && {(((_ .0) = .0) ? {[()]} : {[[__ .1]]}) .0}) &| {_}};",
1222
- " .alt {.cs _; (cs = []) ? {0} : {(cs .0).## - (alt (tail cs))}};",
1223
- " .signed (alt x);",
1223
+ " .signed (x.###);",
1224
1224
  " (signed .< 0) ? {0 - signed} : {signed}} : {need x}};",
1225
1225
  "```",
1226
- "`spin x N` keeps the sign of the alternating sum and divides by a positive",
1227
- "count N. Non-count N is a type error; zero is division-by-zero. The host is",
1228
- "validated before the resolution is checked.",
1226
+ "`spin x N` keeps the sign of `x.###` and divides by a positive count N.",
1227
+ "Non-count N is a type error; zero is division-by-zero. The host is validated",
1228
+ "before the resolution is checked.",
1229
1229
  "```",
1230
1230
  ".spin {.x _; .host x;",
1231
1231
  " (pure host) ? {",
1232
1232
  " {.n <~~1> _;",
1233
- " .tail {(_ && {(((_ .0) = .0) ? {[()]} : {[[__ .1]]}) .0}) &| {_}};",
1234
- " .alt {.cs _; (cs = []) ? {0} : {(cs .0).## - (alt (tail cs))}};",
1235
- " .signed (alt host);",
1233
+ " .signed (host.###);",
1236
1234
  " (n .< 1) ? {signed / 0} : {signed / n}}} : {",
1237
1235
  " {.n _; need host}}};",
1238
1236
  "```",
@@ -1249,16 +1247,28 @@ export const HC_SOURCES = new Map([
1249
1247
  "Native terminal counting needs no enumeration or tally construction.",
1250
1248
  "```",
1251
1249
  "; [(pure []), (pure [[], [[]]]), (pure [[], 5]), (pure [.k 1; []])]",
1252
- "# [<>, <>, (), ()]",
1250
+ "# [<>, <>, (), <>]",
1253
1251
  "; [(need e) = e, (need e) === e]",
1254
1252
  "# [<>, <>]",
1255
- "; inlay [.k 1; []] [[]]",
1253
+ "; inlay [[], 5] [[]]",
1256
1254
  "# $!.name-missing “$:Frame.0.unsupported-figure”;",
1257
1255
  "; inlay 5 [[]]",
1258
1256
  "# $!.name-missing “$:Frame.0.unsupported-figure”;",
1259
- "; gap [.k 1; [[], []]]",
1257
+ "; gap ([], [[], []])",
1260
1258
  "# $!.name-missing “$:Frame.0.unsupported-figure”;",
1261
1259
  "```",
1260
+ "Properties and declared parents never decide the domain or an observation.",
1261
+ "Inlay preserves metadata on rebuilt nonterminal ancestors and leaves its host",
1262
+ "unchanged.",
1263
+ "```",
1264
+ "; [(gap [.k 1; [[], []]]) = 2, [.k 1; [], [[], []]].### = -1]",
1265
+ "# [<>, <>]",
1266
+ "; (inlay [.k 1; [], [.j 2; []]] [[]]) = [.k 1; [[]], [.j 2; [[]]]]",
1267
+ "# <>",
1268
+ "; .p [.k 1; []]; .q (inlay p [[]]);",
1269
+ "; [q = [.k 1; [[]]], p.k, p = [.k 1; []]]",
1270
+ "# [<>, 1, <>]",
1271
+ "```",
1262
1272
  "Inlay preserves nesting and empty replacements; native repetition constructs a",
1263
1273
  "flat product. Both have the same terminal count on Figures.",
1264
1274
  "```",
@@ -1284,7 +1294,22 @@ export const HC_SOURCES = new Map([
1284
1294
  "; [(withness [] [[[]]]), (withness [shared] [])]",
1285
1295
  "# [(), <>]",
1286
1296
  "```",
1287
- "Gap and Spin read native terminal counts, including shared branches at every",
1297
+ "Native `.###` folds the immediate elements' terminal counts with alternating",
1298
+ "signs, one sign per element, and answers a FrameInt even when it is 0 or",
1299
+ "positive. Anything that is not a Figure answers nil.",
1300
+ "```",
1301
+ "; [[].###, [[]].###, [[], []].###, [[], [[], []]].###, [[[], []], []].###]",
1302
+ "# [0, 1, 0, -1, 1]",
1303
+ "; [[], [[], []], [[], [], []]].###",
1304
+ "# 2",
1305
+ "; [([].###) == (0 - 0), ([[]].###) == (1 - 0), ([[]].###) == 1]",
1306
+ "# [<>, <>, ()]",
1307
+ "; [[[], [[]]], [[[], []], []], [[[[], [], []]]]].###",
1308
+ "# 2",
1309
+ "; [[1, []].###, [[], “ab”].###, [[], ([], [])].###, 5.###]",
1310
+ "# [(), (), (), ()]",
1311
+ "```",
1312
+ "Gap is `|x.###|` and Spin is `x.### / N`, including shared branches at every",
1288
1313
  "occurrence. Reversing two unequal branches reverses Spin's sign.",
1289
1314
  "```",
1290
1315
  "; [(gap []) = 0, (gap [[[], []]]) = 2, (gap [[[], []], [[], [], []]]) = 1]",
@@ -1295,6 +1320,9 @@ export const HC_SOURCES = new Map([
1295
1320
  "# [<>, <>]",
1296
1321
  "; [(spin [[[], []]] 1) = 2, (spin [] 4) = 0]",
1297
1322
  "# [<>, <>]",
1323
+ "; .z [[[], []], [[], [], [], [], []]];",
1324
+ "; [z.###, (gap z) = (0 - z.###), (spin z 4) = (z.### / 4)]",
1325
+ "# [-3, <>, <>]",
1298
1326
  "; spin [[[], []]] 2.5",
1299
1327
  "# $!.type-error .n <~~1> 2.5",
1300
1328
  "; spin [[[], []]] 0",
@@ -62,6 +62,13 @@ export class FrameArray extends FrameList {
62
62
  ownsIdentity() {
63
63
  return true;
64
64
  }
65
+ /**
66
+ * Every array is a Figure node, read through its elements; its properties
67
+ * and declared parent are ignored (010.04).
68
+ */
69
+ isFigureNode() {
70
+ return true;
71
+ }
65
72
  /**
66
73
  * An immutable handle on this aggregate, as a name reads it: applying it
67
74
  * collects onto a copy and its mutating methods answer functional updates.
@@ -30,9 +30,14 @@ export class FrameCount extends FrameInt {
30
30
  throw new RangeError(`count must not be negative: ${this.spelling}`);
31
31
  }
32
32
  }
33
- /** A count is its own size, so `.#` and `.##` both answer it (#411). */
34
- sizeFor(_key) {
35
- return this;
33
+ /**
34
+ * A count is its own size, so `.#` and `.##` both answer it (#411). A count
35
+ * is not a Figure, so `.###` answers nil, as for any atom (010.04). The
36
+ * spelling is the literal `Frame.kRESIDUAL`, since this module imports
37
+ * `Frame` as a type only.
38
+ */
39
+ sizeFor(key) {
40
+ return key === "###" ? super.sizeFor(key) : this;
36
41
  }
37
42
  promoteOne() {
38
43
  return new FrameInt(this.data);
@@ -387,11 +387,10 @@ export class FrameScoped extends Frame {
387
387
  sizeFor(key) {
388
388
  return this.term.sizeFor(key);
389
389
  }
390
- /** Counts as its term walks, `.#` and `.##`; anything else is applied. */
390
+ /** Sizes as its term does, `.#`, `.##` and `.###`; anything else is applied. */
391
391
  call(argument, parameter = Frame.nil) {
392
392
  if (argument instanceof FrameSymbol && argument.is.address === true &&
393
- (argument.spelling() === Frame.kCOUNT ||
394
- argument.spelling() === Frame.kLEAVES)) {
393
+ Frame.SIZE_OPERATORS.includes(argument.spelling())) {
395
394
  return this.sizeFor(argument.spelling());
396
395
  }
397
396
  return this.live().call(argument, parameter);
@@ -94,14 +94,14 @@ export class FrameLazy extends FrameExpr {
94
94
  /**
95
95
  * A closure walks as the atoms of its body (#429), so `.#` counts them and
96
96
  * `.##` the terminals below them, as for any aggregate (#411); an empty
97
- * body is one terminal. The operator
97
+ * body is one terminal. A closure is not a Figure, so `.###` is nil
98
+ * (010.04). The operator
98
99
  * reaches a closure as its argument, where a body would otherwise run, so
99
100
  * it is answered here before the body is.
100
101
  */
101
102
  sizeOperator(argument) {
102
103
  if (argument instanceof FrameSymbol && argument.is.address === true &&
103
- (argument.spelling() === Frame.kCOUNT ||
104
- argument.spelling() === Frame.kLEAVES)) {
104
+ Frame.SIZE_OPERATORS.includes(argument.spelling())) {
105
105
  return this.sizeFor(argument.spelling());
106
106
  }
107
107
  return undefined;
@@ -2,6 +2,7 @@ import { Frame } from "./frame.js";
2
2
  import { NilContext } from "./context.js";
3
3
  import { EvaluationScope } from "./evaluation-scope.js";
4
4
  import { FrameCount } from "./frame-count.js";
5
+ import { FrameInt } from "./frame-int.js";
5
6
  import { REPETITION_ELEMENT_LIMIT } from "./frame-numeric.js";
6
7
  import { renderNested } from "./stringify.js";
7
8
  /**
@@ -138,13 +139,15 @@ export class FrameList extends Frame {
138
139
  /**
139
140
  * `.#` counts this aggregate's elements (#411) and `.##` the terminals of
140
141
  * its structure (issue occurrence/figure 010.02), so neither counts a
141
- * property. Every aggregate is a list, so each one answers here rather than
142
- * in its own class.
142
+ * property. `.###` is a Figure's signed residual (010.04). Every aggregate
143
+ * is a list, so each one answers here rather than in its own class.
143
144
  */
144
145
  sizeFor(key) {
145
146
  if (key === Frame.kCOUNT) {
146
147
  return new FrameCount(BigInt(this.countedElements().length));
147
148
  }
149
+ if (key === Frame.kRESIDUAL)
150
+ return this.residual();
148
151
  const terminals = this.terminalCount(new Set());
149
152
  return terminals === undefined
150
153
  ? Frame.error(`$!.cyclic-aggregate .${key}`)
@@ -185,6 +188,68 @@ export class FrameList extends Frame {
185
188
  path.delete(this);
186
189
  return terminals;
187
190
  }
191
+ /**
192
+ * Whether this aggregate can be a node of a Figure, a finite nested array
193
+ * (010.04). Only an array can, so groups, schemas and closures answer false
194
+ * here. Properties are not elements, so they never decide it.
195
+ */
196
+ isFigureNode() {
197
+ return false;
198
+ }
199
+ /**
200
+ * `.###`, the signed alternating sum of the terminal counts of a Figure's
201
+ * immediate elements, `T(x₁) − T(x₂) + T(x₃) − …`, always a FrameInt and 0
202
+ * for `[]` (issue occurrence/figure 010.04). A terminal is an empty frame,
203
+ * so on a Figure `T` is `.##`. Each element is folded with one sign; the
204
+ * signs do not alternate over the terminals below it.
205
+ *
206
+ * A Figure is read through its elements only, so properties and a declared
207
+ * parent are ignored at every level, as `.#` and `.##` ignore them. Anything
208
+ * else is not a Figure and answers nil, as `.#` does for a non-aggregate:
209
+ * an atom, a string, a group, a schema or a closure anywhere in the
210
+ * structure, or an aggregate that contains itself.
211
+ */
212
+ residual() {
213
+ if (!this.isFigureNode())
214
+ return Frame.nil;
215
+ const path = new Set([this]);
216
+ let signed = 0n;
217
+ let positive = true;
218
+ for (const element of this.countedElements()) {
219
+ const terminals = FrameList.figureTerminals(element.referent(), path);
220
+ if (terminals === undefined)
221
+ return Frame.nil;
222
+ signed += positive ? terminals : -terminals;
223
+ positive = !positive;
224
+ }
225
+ return new FrameInt(signed);
226
+ }
227
+ /**
228
+ * The terminal count of `value` as a Figure: 1 for an empty frame, else the
229
+ * sum over its elements. Answers undefined when any node is not a Figure
230
+ * node or contains itself. `path` holds the nodes from the root down, as
231
+ * for `terminalCount`, so a shared branch counts at every occurrence.
232
+ */
233
+ static figureTerminals(value, path) {
234
+ if (!(value instanceof FrameList) || !value.isFigureNode()) {
235
+ return undefined;
236
+ }
237
+ if (path.has(value))
238
+ return undefined;
239
+ const elements = value.countedElements();
240
+ if (elements.length === 0)
241
+ return 1n;
242
+ path.add(value);
243
+ let terminals = 0n;
244
+ for (const element of elements) {
245
+ const below = FrameList.figureTerminals(element.referent(), path);
246
+ if (below === undefined)
247
+ return undefined;
248
+ terminals += below;
249
+ }
250
+ path.delete(value);
251
+ return terminals;
252
+ }
188
253
  /**
189
254
  * `n x` for an aggregate concatenates (v0.22.0). The answer is a fresh
190
255
  * aggregate of x's kind holding the terms x keeps once, its properties and
@@ -23,10 +23,10 @@ const recognizeName = (symbol, source = "") => {
23
23
  if (source.endsWith("^")) {
24
24
  return { disposition: ScanDisposition.CompleteRedispatch };
25
25
  }
26
- // `#` begins a comment except where it spells a size operator, `.#` or `.##`
27
- // (#411), which nothing extends: `.foo#bar` still ends at its `#`, and `.###`
28
- // is `.##` before a comment.
29
- if ([Frame.kCOUNT, Frame.kLEAVES].includes(source + char)) {
26
+ // `#` begins a comment except where it spells a size operator, `.#`, `.##`
27
+ // or `.###` (#411, 010.04), which nothing extends: `.foo#bar` still ends at
28
+ // its `#`, and `.####` is `.###` before a comment.
29
+ if (Frame.SIZE_OPERATORS.includes(source + char)) {
30
30
  return { disposition: ScanDisposition.Consume };
31
31
  }
32
32
  if (source.startsWith(Frame.kCOUNT)) {
@@ -283,8 +283,7 @@ export class FrameSymbol extends FrameAtom {
283
283
  // A size operator answers for the receiver itself rather than looking a
284
284
  // name up, so the scope a value was read from never answers for it (#411).
285
285
  // Only an address is one, since the lexer looks `#` up as the comment.
286
- if (this.is.address === true &&
287
- (this.data === Frame.kCOUNT || this.data === Frame.kLEAVES)) {
286
+ if (this.is.address === true && Frame.SIZE_OPERATORS.includes(this.data)) {
288
287
  return context.referent().sizeFor(this.data);
289
288
  }
290
289
  // An address applied by a receiver reads that member, `o .x`. Two
@@ -244,8 +244,10 @@ export class Frame extends MetaFrame {
244
244
  return this;
245
245
  }
246
246
  /**
247
- * What this frame answers for a size operator, `.#` or `.##` (#411). Only an
248
- * aggregate counts and a count is its own size, so anything else is nil.
247
+ * What this frame answers for a size operator, `.#`, `.##` or `.###`
248
+ * (#411). Only an aggregate counts and a count is its own size, so anything
249
+ * else is nil. `.###` answers only on Figures, nested arrays (issue
250
+ * occurrence/figure 010.04).
249
251
  */
250
252
  sizeFor(_key) {
251
253
  return Frame.nil;
@@ -581,6 +583,31 @@ Object.defineProperty(Frame, "kLEAVES", {
581
583
  writable: true,
582
584
  value: "##"
583
585
  });
586
+ /**
587
+ * kRESIDUAL is the size operator `.###`, a Figure's signed alternating sum
588
+ * of its immediate elements' terminal counts, as a FrameInt (issue
589
+ * occurrence/figure 010.04).
590
+ */
591
+ Object.defineProperty(Frame, "kRESIDUAL", {
592
+ enumerable: true,
593
+ configurable: true,
594
+ writable: true,
595
+ value: "###"
596
+ });
597
+ /**
598
+ * The size operators, the only names spelled with `#` (#411). Each answers
599
+ * for its receiver through `sizeFor`, never through name lookup.
600
+ */
601
+ Object.defineProperty(Frame, "SIZE_OPERATORS", {
602
+ enumerable: true,
603
+ configurable: true,
604
+ writable: true,
605
+ value: [
606
+ Frame.kCOUNT,
607
+ Frame.kLEAVES,
608
+ Frame.kRESIDUAL,
609
+ ]
610
+ });
584
611
  /**
585
612
  * BEGIN_EXPR is the symbol for the beginning of an expression.
586
613
  */
@@ -1 +1 @@
1
- export const VERSION = "0.33.0";
1
+ export const VERSION = "0.34.0";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "hclang",
3
- "version": "0.33.0",
3
+ "version": "0.34.0",
4
4
  "description": "Homoiconic C command-line interpreter and REPL",
5
5
  "keywords": [
6
6
  "language",