functionalscript 0.46.1 → 0.47.0

package/fjs/djs/parser/module.f.d.mts

@@ -8,61 +8,94 @@
  * @import { Fold } from '../../types/function/operator/types.ts'
  * @import { DjsToken, DjsTokenWithMetadata } from '../tokenizer/types.ts'
  * @import { OrderedMap } from '../../types/ordered_map/types.ts'
- * @import { AstArray, AstConst, AstModule, AstModuleRef } from '../ast/types.ts'
+ * @import { AstArray, AstConst, AstModule, AstModuleRef, AstObject } from '../ast/types.ts'
  * @import { TokenMetadata } from '../../js/tokenizer/types.ts'
- * @import { ParseError, _ValueToken } from './types.ts'
+ * @import { ParseError, _FramingKeyword, _OrdinaryTokenName, _ValueToken } from './types.ts'
+ * @import { Assert } from '../../asserts/types.ts'
+ * @import { Equal } from '../../types/ts/types.ts'
+ * @import { CodePointMeta } from '../../bnf/descent/types.ts'
+ * @import { Ast, AstSequence } from '../../bnf/matcher/types.ts'
+ * @import { Rule, TerminalRange } from '../../bnf/types.ts'
+ * @import { DescentMatch } from '../../bnf/descent/types.ts'
  */
 import type { Result } from '../../types/result/types.ts';
 import type { List } from '../../types/list/types.ts';
-import type { DjsTokenWithMetadata } from '../tokenizer/types.ts';
+import type { DjsToken, DjsTokenWithMetadata } from '../tokenizer/types.ts';
 import type { OrderedMap } from '../../types/ordered_map/types.ts';
 import type { AstConst, AstModule, AstModuleRef } from '../ast/types.ts';
-import type { ParseError } from './types.ts';
-export type _DjsStackArray = ['array', List<AstConst>];
-export type _DjsStackObject = ['object', OrderedMap<AstConst>, string];
-export type _DjsStackElement = _DjsStackArray | _DjsStackObject;
-export type _DjsStack = List<_DjsStackElement>;
-export type _ParserState = _InitialState | _NewLineRequiredState | _ImportState | _ConstState | _ExportState | _ParseValueState | _ResultState | _ErrorState;
-export type _ModuleState = {
-    readonly refs: OrderedMap<AstModuleRef>;
-    readonly modules: List<string>;
-    readonly consts: List<AstConst>;
-};
-export type _InitialState = {
-    readonly state: '';
-    readonly module: _ModuleState;
-};
-export type _NewLineRequiredState = {
-    readonly state: 'nl';
-    readonly module: _ModuleState;
-};
-export type _ImportState = {
-    readonly state: 'import' | 'import+name' | 'import+from';
-    readonly module: _ModuleState;
-};
-export type _ConstState = {
-    readonly state: 'const' | 'const+name';
-    readonly module: _ModuleState;
-};
-export type _ExportState = {
-    readonly state: 'export';
-    readonly module: _ModuleState;
+import type { TokenMetadata } from '../../js/tokenizer/types.ts';
+import type { ParseError, _FramingKeyword, _OrdinaryTokenName } from './types.ts';
+import type { Assert } from '../../asserts/types.ts';
+import type { Equal } from '../../types/ts/types.ts';
+import type { CodePointMeta } from '../../bnf/descent/types.ts';
+import type { Ast } from '../../bnf/matcher/types.ts';
+export type _TokenStream = {
+    readonly tokens: readonly DjsTokenWithMetadata[];
+    readonly eofMetadata: TokenMetadata;
 };
-export type _ValueState = '' | '[' | '[v' | '[,' | '{' | '{[' | '{[k' | '{k' | '{:' | '{v' | '{,';
-export type _ParseValueState = {
-    readonly state: 'constValue' | 'exportValue';
-    readonly module: _ModuleState;
-    readonly valueState: _ValueState;
-    readonly top: _DjsStackElement | null;
-    readonly stack: _DjsStack;
-};
-export type _ResultState = {
-    readonly state: 'result';
-    readonly module: _ModuleState;
+/**
+ * The parser layer's complete finite alphabet: every token name its grammar may
+ * name as a terminal, and the exact set a token-name-to-symbol mapping has to be
+ * validated over before parsing.
+ *
+ * `eof` is not a member — {@link splitEof} removes the tokenizer's physical
+ * end-of-input token before any name is mapped, and the backend synthesizes its
+ * own logical one.
+ *
+ * The names are the *token* vocabulary, not the tokenizer grammar's tag
+ * vocabulary: only eight punctuators survive into `DjsToken`, so the JS operator
+ * set the tokenizer recognizes is far larger than what reaches this layer.
+ *
+ * A name is not always a kind. The framing keywords arrive as `id` tokens and
+ * need terminals of their own, or the grammar could not tell `export default`
+ * from two arbitrary identifiers — see {@link framingKeywords}.
+ *
+ * The `_…AreComplete` assertions below check both halves against `DjsToken` and
+ * `_FramingKeyword` at compile time, so a kind or keyword added there breaks the
+ * build rather than going unrepresented.
+ */
+declare const tokenKindNames: readonly ['true', 'false', 'null', 'undefined', '{', '}', ':', ',', '[', ']', '.', '=', 'string', 'number', 'error', 'id', 'bigint', 'ws', 'nl', '//', '/*'];
+/**
+ * The framing keywords, which the tokenizer emits as `id` tokens carrying the
+ * word in `value`. Kept as its own list because the mapping has to recognize
+ * exactly these values, not merely encode them.
+ *
+ * **A grammar over this alphabet owes them an identifier rule.** None of the
+ * five is reserved: outside the framing positions the parser accepts them as
+ * ordinary identifiers, so `const export = 1`, `export default export`, and
+ * `{ from: 2, default: 3 }` all parse today. Once each carries its own symbol, a
+ * rule whose identifier terminal is the bare `id` symbol rejects every one of
+ * them. Wherever an identifier is accepted — binding names, references, object
+ * keys, import names — the terminal has to be the union of `id` and these five.
+ *
+ * Giving a word its own symbol narrows where it is *required*, never where it is
+ * *allowed*.
+ */
+declare const framingKeywords: readonly ['import', 'const', 'export', 'default', 'from'];
+/**
+ * The complete alphabet: one name per `DjsToken` kind except `eof`, plus one per
+ * framing keyword. No keyword collides with a kind, so the two lists concatenate
+ * without a name being registered twice — which `encoding` would reject anyway.
+ */
+declare const ordinaryTokenNames: ("," | "." | "/*" | "//" | ":" | "=" | "[" | "]" | "bigint" | "const" | "default" | "error" | "export" | "false" | "from" | "id" | "import" | "nl" | "null" | "number" | "string" | "true" | "undefined" | "ws" | "{" | "}")[];
+export type _KindsAreComplete = Assert<Equal<(typeof tokenKindNames)[number], Exclude<DjsToken['kind'], 'eof'>>>;
+export type _KeywordsAreComplete = Assert<Equal<(typeof framingKeywords)[number], _FramingKeyword>>;
+export type _AlphabetIsComplete = Assert<Equal<(typeof ordinaryTokenNames)[number], _OrdinaryTokenName>>;
+export type _EofIsNotAName = Assert<Equal<Extract<_OrdinaryTokenName, 'eof'>, never>>;
+export type _Node = Ast<CodePointMeta<DjsTokenWithMetadata>>;
+export type _FoldState = {
+    readonly refs: OrderedMap<AstModuleRef>;
+    readonly modules: readonly string[];
+    readonly consts: readonly AstConst[];
+    readonly error: ParseError | null;
 };
-export type _ErrorState = {
-    readonly state: 'error';
-    readonly error: ParseError;
+export type _FoldFrame = {
+    readonly items: readonly _Node[];
+    readonly index: number;
+    readonly array: List<AstConst>;
+    readonly object: OrderedMap<AstConst>;
+    readonly keys: readonly (readonly [string, boolean])[];
+    readonly isArray: boolean;
 };
 /**
  * Reads the token list as a FunctionalScript module: `import` statements, then
@@ -72,17 +105,32 @@ export type _ErrorState = {
  * module, and `fjs/media/json` is its reader
  * ([spec: JSON input](../../../spec/README.md#json-input)).
  *
+ * The grammar it accepts is written down, in the rules above, rather than
+ * implied by the control flow of a state machine — which is what this replaced.
+ *
  * @type {(tokenList: List<DjsTokenWithMetadata>) => Result<AstModule, ParseError>}
  */
 export declare const parseFromTokens: (tokenList: List<DjsTokenWithMetadata>) => Result<AstModule, ParseError>;
 export declare const proof: {
-    pushKey: {
-        nonObjectTop: () => void;
+    ordinaryTokenNames: {
+        noDuplicates: () => void;
     };
-    endArray: {
-        nonArrayTop: () => void;
+    tokenToSymbol: {
+        distinctAndAboveUnicode: () => void;
+        framingKeywordsAreNotIdentifiers: () => void;
+        carriesTheToken: () => void;
+        throw: {
+            eofRejected: () => CodePointMeta<DjsTokenWithMetadata>;
+        };
     };
-    endObject: {
-        nonObjectTop: () => void;
+    splitEof: {
+        final: () => void;
+        onlyEof: () => void;
+        missing: () => void;
+        empty: () => void;
+        lexicalError: () => void;
+        notFinal: () => void;
+        duplicate: () => void;
     };
 };
+export {};