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