hclang 0.37.0 → 0.37.3

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.
@@ -65,6 +65,9 @@ export class FrameLiteral extends FrameAtom {
65
65
  }
66
66
  }
67
67
  export class FrameSymbol extends FrameAtom {
68
+ isSymbol() {
69
+ return true;
70
+ }
68
71
  static for(symbol) {
69
72
  const exists = FrameSymbol.symbols[symbol];
70
73
  return exists || (FrameSymbol.symbols[symbol] = new FrameSymbol(symbol));
@@ -1,5 +1,389 @@
1
- import { MetaFrame } from "./meta-frame.js";
2
1
  import { NilContext } from "./context.js";
2
+ import { renderNested } from "./stringify.js";
3
+ /** Visibility levels for logical frame bindings. */
4
+ export var Visibility;
5
+ (function (Visibility) {
6
+ Visibility["Public"] = "public";
7
+ Visibility["Protected"] = "protected";
8
+ Visibility["Private"] = "private";
9
+ })(Visibility || (Visibility = {}));
10
+ /**
11
+ * MetaFrame is the parent class of Frame, providing methods for managing metadata.
12
+ */
13
+ export class MetaFrame {
14
+ /**
15
+ * Checks if the given string is numeric
16
+ * (to distinguish array indices from metadata keys)
17
+ *
18
+ * @param {string} value - The string to check.
19
+ * @returns {boolean} `true` if the string is all numeric, `false` otherwise.
20
+ */
21
+ static isInteger(value) {
22
+ return /^\p{N}+$/u.test(value);
23
+ }
24
+ /**
25
+ * Checks if the given character is alphabetic.
26
+ *
27
+ * @param {string} char - The character to check.
28
+ * @returns {boolean} `true` if the character is alphabetic, `false` otherwise.
29
+ */
30
+ static isAlphabetic(char) {
31
+ return /\p{L}/u.test(char);
32
+ }
33
+ /**
34
+ * meta is a map of key-value pairs for the Frame.
35
+ * _isNil is a flag indicating if the Frame is nil.
36
+ */
37
+ constructor(meta = NilContext, _isNil = false) {
38
+ Object.defineProperty(this, "meta", {
39
+ enumerable: true,
40
+ configurable: true,
41
+ writable: true,
42
+ value: meta
43
+ });
44
+ /**
45
+ * up is the lexical parent carried by structurally nested frames and
46
+ * per-read plumbing copies. Symbol lookup never rewrites it on a shared
47
+ * value; identity-bearing values carry reader context in a FrameHandle.
48
+ */
49
+ Object.defineProperty(this, "up", {
50
+ enumerable: true,
51
+ configurable: true,
52
+ writable: true,
53
+ value: {}
54
+ }); // forward-declare Frame
55
+ /**
56
+ * parent is the declared parent: the explicit `.^` inheritance link.
57
+ * It is written only by setParent, so the declared chain is acyclic by
58
+ * construction, and it is the only chain visibility authorizes against.
59
+ */
60
+ Object.defineProperty(this, "parent", {
61
+ enumerable: true,
62
+ configurable: true,
63
+ writable: true,
64
+ value: {}
65
+ }); // forward-declare Frame
66
+ /** Typed receiver capability installed only on an invocation frame. */
67
+ Object.defineProperty(this, "receiverState", {
68
+ enumerable: true,
69
+ configurable: true,
70
+ writable: true,
71
+ value: void 0
72
+ });
73
+ /**
74
+ * declares marks a frame that accepts declarations, so a name binds to the
75
+ * innermost marked target instead of inferring one from context classes.
76
+ */
77
+ Object.defineProperty(this, "declares", {
78
+ enumerable: true,
79
+ configurable: true,
80
+ writable: true,
81
+ value: false
82
+ });
83
+ /**
84
+ * id is a unique identifier for each Frame.
85
+ */
86
+ Object.defineProperty(this, "id", {
87
+ enumerable: true,
88
+ configurable: true,
89
+ writable: true,
90
+ value: void 0
91
+ });
92
+ const name = this.constructor.name;
93
+ const id = name + "." + MetaFrame.id_count++;
94
+ this.id = "$:" + id;
95
+ }
96
+ /**
97
+ * get_here retrieves a Frame by key from the current context.
98
+ */
99
+ get_here(key, _origin = this) {
100
+ const exact = this.resolve_here(key, _origin);
101
+ if (exact != null) {
102
+ return exact.value;
103
+ }
104
+ return this.match_here(key);
105
+ }
106
+ /** Lets a projection perform another frame's local lookup without its links. */
107
+ lookup_here_on(frame, key, origin) {
108
+ return frame.lookup_here(key, origin);
109
+ }
110
+ /**
111
+ * Lets a forwarding link search another frame's non-global lookup graph.
112
+ *
113
+ * `Frame.globals` stays the one final tier of the outer `get`, which
114
+ * curries an operator with that lookup's own origin; a forwarded `get`
115
+ * would reach the globals early, from the wrong frame.
116
+ */
117
+ lookup_graph_on(frame, key, origin) {
118
+ return MetaFrame.lookup(frame, key, origin, new Set());
119
+ }
120
+ /**
121
+ * Lets a forwarding link resolve a binding through another frame's
122
+ * non-global graph.
123
+ *
124
+ * The binding counterpart of `lookup_graph_on`, with the same tiers, so a
125
+ * forwarded value and its binding metadata come from the same declaration
126
+ * owner. `Frame.globals` stays the one final tier of the outer `resolve`.
127
+ */
128
+ resolve_graph_on(frame, key, origin) {
129
+ return MetaFrame.resolveBinding(frame, key, origin, new Set());
130
+ }
131
+ /** Resolves a logical name to the declaration key visible from origin. */
132
+ resolve_here(key, origin = this) {
133
+ if (key.startsWith("__")) {
134
+ return this.authorize(key, Visibility.Private, key.slice(2), origin);
135
+ }
136
+ if (key.startsWith("_")) {
137
+ return this.authorize(key, Visibility.Protected, key.slice(1), origin);
138
+ }
139
+ const publicValue = this.meta[key];
140
+ if (publicValue != null) {
141
+ return { owner: this, key, value: publicValue };
142
+ }
143
+ return this.authorize(`_${key}`, Visibility.Protected, key, origin) ??
144
+ this.authorize(`__${key}`, Visibility.Private, key, origin);
145
+ }
146
+ /** Resolves a binding through the same guarded graph as ordinary lookup. */
147
+ resolve(key, origin = this) {
148
+ const local = this.resolve_here(key, origin);
149
+ if (local)
150
+ return local;
151
+ const seen = new Set([this]);
152
+ for (const link of this.lookup_links()) {
153
+ const result = MetaFrame.resolveBinding(link, key, origin, seen);
154
+ if (result)
155
+ return result;
156
+ }
157
+ const globals = Frame.globals;
158
+ if (globals && !globals.is.missing && !seen.has(globals)) {
159
+ return MetaFrame.resolveBinding(globals, key, origin, seen);
160
+ }
161
+ return undefined;
162
+ }
163
+ /**
164
+ * Get a frame by key through one guarded lookup traversal.
165
+ *
166
+ * Subclasses customize only local lookup, links, and successful-result
167
+ * transformation. The traversal itself stays here so a virtual override
168
+ * cannot accidentally discard cycle state. Declared parents precede lexical
169
+ * scope, and globals are consulted once after the complete scope graph.
170
+ */
171
+ get(key, origin = this) {
172
+ const local = this.lookup_here(key, origin);
173
+ if (!local.is.missing) {
174
+ return this.lookup_result(local, key);
175
+ }
176
+ // Allocate traversal state only after an immediate local miss.
177
+ const seen = new Set([this]);
178
+ for (const link of this.lookup_links()) {
179
+ const result = MetaFrame.lookup(link, key, origin, seen);
180
+ if (!result.is.missing) {
181
+ return this.lookup_result(result, key);
182
+ }
183
+ }
184
+ // Globals are the final lookup tier, even when the lexical graph cycles.
185
+ const globals = Frame.globals;
186
+ if (globals && !globals.is.missing && !seen.has(globals)) {
187
+ const result = MetaFrame.lookup(globals, key, origin, seen);
188
+ if (!result.is.missing) {
189
+ return this.lookup_result(result, key);
190
+ }
191
+ }
192
+ return Frame.missing;
193
+ }
194
+ /** Local behavior used by the guarded lookup driver. */
195
+ lookup_here(key, origin) {
196
+ return this.get_here(key, origin);
197
+ }
198
+ /** Non-global links in lookup precedence order. */
199
+ lookup_links() {
200
+ const links = [];
201
+ if (this.parent && !this.parent.is.missing) {
202
+ links.push(this.parent);
203
+ }
204
+ if (this.up && !this.up.is.missing && this.up !== Frame.globals) {
205
+ links.push(this.up);
206
+ }
207
+ return links;
208
+ }
209
+ /** Allows wrappers to transform a value found anywhere below them. */
210
+ lookup_result(result, _key) {
211
+ return result;
212
+ }
213
+ /** Depth-first declared-before-lexical traversal without global fallback. */
214
+ static lookup(frame, key, origin, seen) {
215
+ if (seen.has(frame)) {
216
+ return Frame.missing;
217
+ }
218
+ seen.add(frame);
219
+ const local = frame.lookup_here(key, origin);
220
+ if (!local.is.missing) {
221
+ return frame.lookup_result(local, key);
222
+ }
223
+ for (const link of frame.lookup_links()) {
224
+ const result = MetaFrame.lookup(link, key, origin, seen);
225
+ if (!result.is.missing) {
226
+ return frame.lookup_result(result, key);
227
+ }
228
+ }
229
+ return Frame.missing;
230
+ }
231
+ /** Depth-first binding traversal without global fallback. */
232
+ static resolveBinding(frame, key, origin, seen) {
233
+ if (seen.has(frame))
234
+ return undefined;
235
+ seen.add(frame);
236
+ const local = frame.resolve_here(key, origin);
237
+ if (local)
238
+ return local;
239
+ for (const link of frame.lookup_links()) {
240
+ const result = MetaFrame.resolveBinding(link, key, origin, seen);
241
+ if (result)
242
+ return result;
243
+ }
244
+ return undefined;
245
+ }
246
+ /**
247
+ * set adds a new key-value pair to the current context.
248
+ */
249
+ set(key, value) {
250
+ if (this.meta === NilContext) {
251
+ this.meta = {};
252
+ }
253
+ this.meta[key] = value;
254
+ return this;
255
+ }
256
+ /** Whether this frame carries an explicitly declared parent. */
257
+ hasDeclaredParent() {
258
+ return this.parent != null && !this.parent.is.missing;
259
+ }
260
+ /**
261
+ * setParent is the only path that may attach a declared parent, so a cyclic
262
+ * declared chain cannot be built by a caller that forgot to check. It returns
263
+ * an error frame when the link is refused and undefined when it is accepted.
264
+ */
265
+ setParent(parent) {
266
+ if (this.wouldCreateParentCycle(parent)) {
267
+ return Frame.error("$!.cyclic-parent .^");
268
+ }
269
+ this.parent = parent;
270
+ return undefined;
271
+ }
272
+ /** Whether assigning parent would attach this frame to a cyclic chain. */
273
+ wouldCreateParentCycle(parent) {
274
+ const seen = new Set([this]);
275
+ let current = parent;
276
+ while (current && !current.is.missing) {
277
+ if (seen.has(current))
278
+ return true;
279
+ seen.add(current);
280
+ current = current.parent;
281
+ }
282
+ return false;
283
+ }
284
+ /**
285
+ * meta_copy creates a shallow copy of the current context.
286
+ */
287
+ meta_copy() {
288
+ return { ...this.meta };
289
+ }
290
+ /**
291
+ * meta_keys returns an array of keys in the current context.
292
+ */
293
+ meta_keys() {
294
+ return Object.keys(this.meta);
295
+ }
296
+ /**
297
+ * meta_length returns the number of keys in the current context.
298
+ */
299
+ meta_length() {
300
+ return this.meta_keys().length;
301
+ }
302
+ /**
303
+ * meta_pairs returns an array of key-value pairs in the current context.
304
+ */
305
+ meta_pairs() {
306
+ return Object.entries(this.meta);
307
+ }
308
+ /**
309
+ * meta_string returns a string representation of the current context.
310
+ *
311
+ * Nested values render through the cycle guard, so metadata that reaches this
312
+ * frame again yields an id rather than overflowing the host stack.
313
+ */
314
+ meta_string() {
315
+ return this.meta_pairs().map(([key, value]) => {
316
+ if (key === Frame.kOUT) {
317
+ return `.${key} ${value.id};`;
318
+ }
319
+ return `.${key} ${renderNested(value, () => value.toString())};`;
320
+ }).join(" ");
321
+ }
322
+ /**
323
+ * match_here checks if a target string matches any key in the current context.
324
+ */
325
+ match_here(target) {
326
+ let result = Frame.missing;
327
+ this.meta_pairs().forEach(([key, value]) => {
328
+ const isPattern = key.match(/\/(.*)\//);
329
+ if (isPattern) {
330
+ const pattern = new RegExp(isPattern[1]);
331
+ if (pattern.test(target)) {
332
+ result = value;
333
+ if ("source" in result) {
334
+ const sourced = result;
335
+ sourced.source = target;
336
+ }
337
+ }
338
+ }
339
+ });
340
+ return result;
341
+ }
342
+ authorize(physicalKey, visibility, key, origin) {
343
+ const value = this.meta[physicalKey];
344
+ if (value == null)
345
+ return undefined;
346
+ const authorized = visibility === Visibility.Public ||
347
+ (visibility === Visibility.Private
348
+ ? origin === this
349
+ : this.isAncestorOf(origin));
350
+ if (authorized) {
351
+ return { owner: this, key: physicalKey, value };
352
+ }
353
+ return {
354
+ owner: this,
355
+ key: physicalKey,
356
+ value: Frame.error(`$!.is-${visibility} .${key}`),
357
+ };
358
+ }
359
+ /**
360
+ * isAncestorOf walks the declared parent chain only. Lexical nesting and
361
+ * syntactic containment confer no protected access: an inner aggregate or an
362
+ * unrelated peer's method is not a descendant.
363
+ */
364
+ isAncestorOf(origin) {
365
+ const seen = new Set();
366
+ let current = origin;
367
+ while (current && !seen.has(current)) {
368
+ if (current === this)
369
+ return true;
370
+ seen.add(current);
371
+ if (!current.hasDeclaredParent())
372
+ return false;
373
+ current = current.parent;
374
+ }
375
+ return false;
376
+ }
377
+ }
378
+ /**
379
+ * id_count is a static counter, incremented to generate unique IDs.
380
+ */
381
+ Object.defineProperty(MetaFrame, "id_count", {
382
+ enumerable: true,
383
+ configurable: true,
384
+ writable: true,
385
+ value: 0
386
+ });
3
387
  /**
4
388
  * inspectFlags returns a string representation of the Flags.
5
389
  *
@@ -243,11 +627,20 @@ export class Frame extends MetaFrame {
243
627
  atSite(_site) {
244
628
  return this;
245
629
  }
246
- /**
247
- * Whether evaluating this atom resolves a binding where it is evaluated, as
248
- * an alias does, rather than being a value or a name a walk already holds
249
- * as a word. A walk holds such an atom with its closure's scope (spec a17).
250
- */
630
+ /** Concrete syntax/value families, without eager imports of subclasses. */
631
+ isName() {
632
+ return false;
633
+ }
634
+ isSymbol() {
635
+ return false;
636
+ }
637
+ isSchema() {
638
+ return false;
639
+ }
640
+ isClosure() {
641
+ return false;
642
+ }
643
+ /** Whether evaluating this atom resolves a binding in its evaluation scope. */
251
644
  resolvesInScope() {
252
645
  return false;
253
646
  }