@traqula/core 0.0.1-alpha.145 → 0.0.1-alpha.176

package/README.md

@@ -1,9 +1,11 @@
-# TRAQULA core package
+# Traqula core package
 
-TRAQULA core contains core components of traqula.
-Most importantly, its `lexer-builder` and `grammar-builder`.
-This library heavily relies on the amazing [chevrotain package](https://chevrotain.io/docs/).
-Knowing the basics of that package will allow you to quickly generate your own grammars
+**WARNING:** V2 will come shortly and will have lots of breaking changes.
+
+Traqula core contains core components of Traqula.
+Most importantly, its [lexer builder](./lib/lexer-builder/LexerBuilder.ts), [parser builder](./lib/parser-builder/parserBuilder.ts), and [generator builder](./lib/generator-builder/generatorBuilder.ts).
+This library heavily relies on the amazing [Chevrotain package](https://chevrotain.io/docs/).
+Knowing the basics of that package will allow you to quickly generate your own grammars.
 
 ## Installation
 
@@ -19,12 +21,12 @@ yarn add @traqula/core
 
 ## Usage
 
-Each parser contains two steps: 
+Each parser contains two steps:
 1. a lexer
 2. a grammar + abstract syntax tree generation step.
 
-Sometimes grammar definitions and abstract syntax tree generation is split into separate steps. 
-In this library, we choose to keep the two together.
+Sometimes grammar definitions and abstract syntax tree generation is split into separate steps.
+In this library, we choose to keep the two together when building a parser.
 
 ### Lexer Builder
 
@@ -38,10 +40,10 @@ To create a token definition, you use the provided function `createToken` like:
 const select = createToken({ name: 'Select', pattern: /select/i, label: 'SELECT' });
 ```
 
-Lexer definitions are then put in a list and when a lexer is build, the lexer will match a string to the first token in the list that matches.
+Lexer definitions are then put in a list and when a lexer is build, the lexer will match a string to the [**first token in the list**](https://chevrotain.io/docs/tutorial/step1_lexing.html#creating-the-lexer) that matches.
 Note that the order of definitions in the list is thus essential.
 
-We therefore use a `lexer-builder` which allows you to easily:
+We therefore use a [lexer builder](./lib/lexer-builder/LexerBuilder.ts) which allows you to easily:
 1. change the order of lexer rules,
 2. and create a new lexer staring from an existing one.
 
@@ -56,11 +58,11 @@ A new lexer can be created from an existing one by calling:
 const sparql11AdjustTokens = sparql11Tokens.addBefore(select, BuiltInAdjust);
 ```
 
-### Grammar Builder
+### Parser Builder
 
 The grammar builder is used to link together grammar rules such that they can be converted into a parser.
-Grammar rule definitions come in the form of `RuleDef` objects.
-Each `RuleDef` object contains its name and its returnType.
+Grammar rule definitions come in the form of [ParserRule](./lib/parser-builder/ruleDefTypes.ts) objects.
+Each `ParserRule` object contains its name and its returnType.
 Optionally, it can also contain arguments that should be provided to the SUBRULE calls.
 A simple example of a grammar rule is the rule bellow that allows you to parse booleanLiterals.
 
@@ -69,7 +71,7 @@ A simple example of a grammar rule is the rule bellow that allows you to parse b
  * Parses a boolean literal.
  * [[134]](https://www.w3.org/TR/sparql11-query/#rBooleanLiteral)
  */
-export const booleanLiteral: RuleDef<'booleanLiteral', LiteralTerm> = <const> {
+export const booleanLiteral: ParserRule<'booleanLiteral', LiteralTerm> = <const> {
     name: 'booleanLiteral',
     impl: ({ CONSUME, OR, context }) => () => OR([
       { ALT: () => context.dataFactory.literal(
@@ -84,20 +86,19 @@ export const booleanLiteral: RuleDef<'booleanLiteral', LiteralTerm> = <const> {
   };
 ```
 
-The `impl` member of `RuleDef` is a function that receives:
+The `impl` member of `ParserRule` is a function that receives:
 1. essential functions to create a grammar rule (capitalized members),
 2. a context object that can be used by the rules,
-3. a cache object ([WeakMap](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakMap)) that can be used to cache the creation of long lists in the parser. 
+3. a cache object ([WeakMap](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakMap)) that can be used to cache the creation of long lists in the parser, [increasing parser performance](https://chevrotain.io/docs/guide/performance.html#caching-arrays-of-alternatives).
 
-As a warning, we advise against unpacking the context entry in the function definition itself.
-Doing so will cause the unpacked entries to be captured in the closure which will cause unwanted behaviour since the context entry can be reset between runs.
+You cannot unpack the context entry in the function definition itself because the parser uses a [recording phase](https://chevrotain.io/docs/guide/internals.html#grammar-recording) to optimize itself. During this phase, the context entry will be undefined, as such, it can only be accessed within the `ACTION` function.
 
 The result of an `impl` call is a function called a `rule`.
 Rules can be [parameterized](https://chevrotain.io/docs/features/parameterized_rules.html), although I have not found a scenario where that is usefully.
-Personally I create a function that can be used to create multiple `RuleDef` objects.  
-The result of a rule should match the type provided in the `RuleDef` definition, and is the result of a call of `SUBRULE` with that rule.
+Personally I create a function that can be used to create multiple `ParserRule` objects.
+The result of a rule should match the type provided in the `ParserRule` definition, and is the result of a call of `SUBRULE` with that rule.
 
-### Patching rules
+#### Patching rules
 
 When a rule definition calls to a subrule using `SUBRULE(mySub)`, the implementation itself is not necessarily called.
 That is because the SUBRULE function will call the function with the same name as `mySub` that is present in the current grammarBuilder.
@@ -112,4 +113,25 @@ const myBuilder = Builder
 ```
 
 When `selectOrDescribe` calls what it thinks to be `selectRule`,
-it will instead call `selectRuleAlternative` since it overwrote the function `selectRule` with the same name. 
+it will instead call `selectRuleAlternative` since it overwrote the function `selectRule` with the same name.
+
+### Generator Builder
+
+The generator builder function in much the same as the [parser builder](#parser-builder).
+Your builder expects objects of type [GeneratorRule](lib/generator-builder/generatorTypes.ts),
+containing the implementation of the generator in the `gImpl` member.
+The `gImpl` function gets essential functions to create a generator rule (capitalized members),
+returning a function that will get the AST and context, returning a string.
+For generator rules, you can unpack the context since no recording phase is present in this case.
+The idea is that GeneratorRules and ParserRules can be tied together in the same object, as such, similar behaviour is grouped together.
+
+```typescript
+/**
+ * Parses a named node, either as an IRI or as a prefixed name.
+ * [[136]](https://www.w3.org/TR/sparql11-query/#riri)
+ */
+export const iri: GeneratorRule<'iri', IriTerm> = <const> {
+    name: 'iri',
+    gImpl: () => ast => ast.value,
+  };
+```

package/lib/generator-builder/builderTypes.d.ts

@@ -0,0 +1,20 @@
+import type { GeneratorRule } from './generatorTypes';
+/**
+ * Get union-type of names used in list of ruledefs.
+ */
+export type GenNamesFromList<T extends readonly GeneratorRule[]> = T[number]['name'];
+/**
+ * Convert a list of ruledefs to a record that maps each rule name to its definition.
+ */
+export type GenRuleMap<RuleNames extends string> = {
+    [Key in RuleNames]: GeneratorRule<any, Key>;
+};
+/**
+ * Convert a list of RuleDefs to a Record with the name of the RuleDef as the key, matching the RuleDefMap type.
+ */
+export type GenRulesToObject<T extends readonly GeneratorRule[], Names extends string = GenNamesFromList<T>, Agg extends Record<string, GeneratorRule> = Record<never, never>> = T extends readonly [infer First, ...infer Rest] ? (First extends GeneratorRule ? (Rest extends readonly GeneratorRule[] ? (GenRulesToObject<Rest, Names, {
+    [K in keyof Agg | First['name']]: K extends First['name'] ? First : Agg[K];
+}>) : never) : never) : GenRuleMap<Names> & Agg;
+export type GeneratorFromRules<Context, Names extends string, RuleDefs extends GenRuleMap<Names>> = {
+    [K in Names]: RuleDefs[K] extends GeneratorRule<Context, K, infer RET, infer ARGS> ? (input: RET, context: Context, args: ARGS) => string : never;
+};

package/lib/generator-builder/builderTypes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"builderTypes.js","sourceRoot":"","sources":["builderTypes.ts"],"names":[],"mappings":"","sourcesContent":["import type { GeneratorRule } from './generatorTypes';\n\n/**\n * Get union-type of names used in list of ruledefs.\n */\nexport type GenNamesFromList<T extends readonly GeneratorRule[]> = T[number]['name'];\n\n/**\n * Convert a list of ruledefs to a record that maps each rule name to its definition.\n */\nexport type GenRuleMap<RuleNames extends string> = {[Key in RuleNames]: GeneratorRule<any, Key> };\n\n/**\n * Convert a list of RuleDefs to a Record with the name of the RuleDef as the key, matching the RuleDefMap type.\n */\nexport type GenRulesToObject<\n  T extends readonly GeneratorRule[],\n  Names extends string = GenNamesFromList<T>,\n  Agg extends Record<string, GeneratorRule> = Record<never, never>,\n> = T extends readonly [infer First, ...infer Rest] ? (\n  First extends GeneratorRule ? (\n    Rest extends readonly GeneratorRule[] ? (\n      GenRulesToObject<Rest, Names, {[K in keyof Agg | First['name']]: K extends First['name'] ? First : Agg[K] }>\n    ) : never\n  ) : never\n) : GenRuleMap<Names> & Agg;\n\nexport type GeneratorFromRules<Context, Names extends string, RuleDefs extends GenRuleMap<Names>> = {\n  [K in Names]: RuleDefs[K] extends GeneratorRule<Context, K, infer RET, infer ARGS> ?\n      (input: RET, context: Context, args: ARGS) => string : never\n};\n"]}

package/lib/generator-builder/dynamicGenerator.d.ts

@@ -0,0 +1,7 @@
+import type { GenRuleMap } from './builderTypes';
+export declare class DynamicGenerator<Context, Names extends string, RuleDefs extends GenRuleMap<Names>> {
+    private __context;
+    setContext(context: Context): void;
+    private getSafeContext;
+    constructor(rules: RuleDefs);
+}

package/lib/generator-builder/dynamicGenerator.js

@@ -0,0 +1,28 @@
+export class DynamicGenerator {
+    setContext(context) {
+        this.__context = context;
+    }
+    getSafeContext() {
+        return this.__context;
+    }
+    constructor(rules) {
+        this.__context = undefined;
+        const selfRef = {
+            SUBRULE: (cstDef, input, arg) => {
+                const def = rules[cstDef.name];
+                if (!def) {
+                    throw new Error(`Rule ${cstDef.name} not found`);
+                }
+                return def.gImpl(selfRef)(input, this.getSafeContext(), arg);
+            },
+        };
+        // eslint-disable-next-line ts/no-unnecessary-type-assertion
+        for (const rule of Object.values(rules)) {
+            this[rule.name] = ((input, context, args) => {
+                this.setContext(context);
+                return rule.gImpl(selfRef)(input, this.getSafeContext(), args);
+            });
+        }
+    }
+}
+//# sourceMappingURL=dynamicGenerator.js.map

package/lib/generator-builder/dynamicGenerator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dynamicGenerator.js","sourceRoot":"","sources":["dynamicGenerator.ts"],"names":[],"mappings":"AAGA,MAAM,OAAO,gBAAgB;IAGpB,UAAU,CAAC,OAAgB;QAChC,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC;IAC3B,CAAC;IAEO,cAAc;QACpB,OAAiB,IAAI,CAAC,SAAS,CAAC;IAClC,CAAC;IAED,YAAmB,KAAe;QAV1B,cAAS,GAAwB,SAAS,CAAC;QAWjD,MAAM,OAAO,GAAe;YAC1B,OAAO,EAAE,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;gBAC9B,MAAM,GAAG,GAAG,KAAK,CAAQ,MAAM,CAAC,IAAI,CAAC,CAAC;gBACtC,IAAI,CAAC,GAAG,EAAE,CAAC;oBACT,MAAM,IAAI,KAAK,CAAC,QAAQ,MAAM,CAAC,IAAI,YAAY,CAAC,CAAC;gBACnD,CAAC;gBACD,OAAO,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,IAAI,CAAC,cAAc,EAAE,EAAE,GAAG,CAAC,CAAC;YAC/D,CAAC;SACF,CAAC;QAEF,4DAA4D;QAC5D,KAAK,MAAM,IAAI,IAAqB,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;YACzD,IAAI,CAAsB,IAAI,CAAC,IAAI,CAAC,GAAQ,CAAC,CAAC,KAAU,EAAE,OAAgB,EAAE,IAAS,EAAE,EAAE;gBACvF,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;gBACzB,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,IAAI,CAAC,cAAc,EAAE,EAAE,IAAI,CAAC,CAAC;YACjE,CAAC,CAAC,CAAC;QACL,CAAC;IACH,CAAC;CACF","sourcesContent":["import type { GenRuleMap } from './builderTypes';\nimport type { GeneratorRule, RuleDefArg } from './generatorTypes';\n\nexport class DynamicGenerator<Context, Names extends string, RuleDefs extends GenRuleMap<Names>> {\n  private __context: Context | undefined = undefined;\n\n  public setContext(context: Context): void {\n    this.__context = context;\n  }\n\n  private getSafeContext(): Context {\n    return <Context> this.__context;\n  }\n\n  public constructor(rules: RuleDefs) {\n    const selfRef: RuleDefArg = {\n      SUBRULE: (cstDef, input, arg) => {\n        const def = rules[<Names>cstDef.name];\n        if (!def) {\n          throw new Error(`Rule ${cstDef.name} not found`);\n        }\n        return def.gImpl(selfRef)(input, this.getSafeContext(), arg);\n      },\n    };\n\n    // eslint-disable-next-line ts/no-unnecessary-type-assertion\n    for (const rule of <GeneratorRule[]>Object.values(rules)) {\n      this[<keyof (typeof this)>rule.name] = <any>((input: any, context: Context, args: any) => {\n        this.setContext(context);\n        return rule.gImpl(selfRef)(input, this.getSafeContext(), args);\n      });\n    }\n  }\n}\n"]}

package/lib/generator-builder/generatorBuilder.d.ts

@@ -0,0 +1,58 @@
+import type { CheckOverlap } from '../utils';
+import type { GeneratorFromRules, GenNamesFromList, GenRuleMap, GenRulesToObject } from './builderTypes';
+import type { GeneratorRule } from './generatorTypes';
+export declare class GeneratorBuilder<Context, Names extends string, RuleDefs extends GenRuleMap<Names>> {
+    /**
+     * Create a GeneratorBuilder from some initial grammar rules or an existing GeneratorBuilder.
+     * If a GeneratorBuilder is provided, a new copy will be created.
+     */
+    static createBuilder<Context, Names extends string, RuleDefs extends GenRuleMap<Names>>(args: GeneratorBuilder<Context, Names, RuleDefs>): GeneratorBuilder<Context, Names, RuleDefs>;
+    static createBuilder<Rules extends readonly GeneratorRule[] = readonly GeneratorRule[], Context = Rules[0] extends GeneratorRule<infer context> ? context : never, Names extends string = GenNamesFromList<Rules>, RuleDefs extends GenRuleMap<Names> = GenRulesToObject<Rules>>(rules: Rules): GeneratorBuilder<Context, Names, RuleDefs>;
+    private rules;
+    private constructor();
+    typePatch<Patch extends {
+        [Key in Names]?: any;
+    }>(): GeneratorBuilder<Context, Names, {
+        [Key in Names]: Key extends keyof Patch ? (RuleDefs[Key] extends GeneratorRule<Context, Key, any, infer Args> ? GeneratorRule<Context, Key, Patch[Key], Args> : never) : (RuleDefs[Key] extends GeneratorRule<Context, Key> ? RuleDefs[Key] : never);
+    }>;
+    /**
+     * Change the implementation of an existing generator rule.
+     */
+    patchRule<U extends Names, RET, ARGS>(patch: GeneratorRule<Context, U, RET, ARGS>): GeneratorBuilder<Context, Names, {
+        [Key in Names]: Key extends U ? GeneratorRule<Context, Key, RET, ARGS> : (RuleDefs[Key] extends GeneratorRule<Context, Key> ? RuleDefs[Key] : never);
+    }>;
+    /**
+     * Add a rule to the grammar. If the rule already exists, but the implementation differs, an error will be thrown.
+     */
+    addRuleRedundant<U extends string, RET, ARGS>(rule: GeneratorRule<Context, U, RET, ARGS>): GeneratorBuilder<Context, Names | U, {
+        [K in Names | U]: K extends Names ? (RuleDefs[K] extends GeneratorRule<Context, K> ? RuleDefs[K] : never) : (K extends U ? GeneratorRule<Context, K, RET, ARGS> : never);
+    }>;
+    /**
+     * Add a rule to the grammar. Will raise a typescript error if the rule already exists in the grammar.
+     */
+    addRule<U extends string, RET, ARGS>(rule: CheckOverlap<U, Names, GeneratorRule<Context, U, RET, ARGS>>): GeneratorBuilder<Context, Names | U, {
+        [K in Names | U]: K extends Names ? (RuleDefs[K] extends GeneratorRule<Context, K> ? RuleDefs[K] : never) : (K extends U ? GeneratorRule<Context, K, RET, ARGS> : never);
+    }>;
+    addMany<U extends readonly GeneratorRule<Context>[]>(...rules: CheckOverlap<GenNamesFromList<U>, Names, U>): GeneratorBuilder<Context, Names | GenNamesFromList<U>, {
+        [K in Names | GenNamesFromList<U>]: K extends keyof GenRulesToObject<typeof rules> ? (GenRulesToObject<typeof rules>[K] extends GeneratorRule<Context, K> ? GenRulesToObject<typeof rules>[K] : never) : (K extends Names ? (RuleDefs[K] extends GeneratorRule<Context, K> ? RuleDefs[K] : never) : never);
+    }>;
+    /**
+     * Delete a grammar rule by its name.
+     */
+    deleteRule<U extends Names>(ruleName: U): GeneratorBuilder<Context, Exclude<Names, U>, {
+        [K in Exclude<Names, U>]: RuleDefs[K] extends GeneratorRule<Context, K> ? RuleDefs[K] : never;
+    }>;
+    /**
+     * Merge this grammar GeneratorBuilder with another.
+     * It is best to merge the bigger grammar with the smaller one.
+     * If the two builders both have a grammar rule with the same name,
+     * no error will be thrown case they map to the same ruledef object.
+     * If they map to a different object, an error will be thrown.
+     * To fix this problem, the overridingRules array should contain a rule with the same conflicting name,
+     * this rule implementation will be used.
+     */
+    merge<OtherNames extends string, OtherRules extends GenRuleMap<OtherNames>, OW extends readonly GeneratorRule<Context>[]>(GeneratorBuilder: GeneratorBuilder<Context, OtherNames, OtherRules>, overridingRules: OW): GeneratorBuilder<Context, Names | OtherNames | GenNamesFromList<OW>, {
+        [K in Names | OtherNames | GenNamesFromList<OW>]: K extends keyof GenRulesToObject<OW> ? (GenRulesToObject<OW>[K] extends GeneratorRule<Context, K> ? GenRulesToObject<OW>[K] : never) : (K extends Names ? (RuleDefs[K] extends GeneratorRule<Context, K> ? RuleDefs[K] : never) : K extends OtherNames ? (OtherRules[K] extends GeneratorRule<Context, K> ? OtherRules[K] : never) : never);
+    }>;
+    build(): GeneratorFromRules<Context, Names, RuleDefs>;
+}

package/lib/generator-builder/generatorBuilder.js

@@ -0,0 +1,101 @@
+import { DynamicGenerator } from './dynamicGenerator';
+/**
+ * Converts a list of ruledefs to a record mapping a name to the corresponding ruledef.
+ */
+function listToRuleDefMap(rules) {
+    const newRules = {};
+    for (const rule of rules) {
+        newRules[rule.name] = rule;
+    }
+    return newRules;
+}
+export class GeneratorBuilder {
+    static createBuilder(start) {
+        if (start instanceof GeneratorBuilder) {
+            return new GeneratorBuilder({ ...start.rules });
+        }
+        return new GeneratorBuilder(listToRuleDefMap(start));
+    }
+    constructor(startRules) {
+        this.rules = startRules;
+    }
+    typePatch() {
+        return this;
+    }
+    /**
+     * Change the implementation of an existing generator rule.
+     */
+    patchRule(patch) {
+        const self = this;
+        self.rules[patch.name] = patch;
+        return self;
+    }
+    /**
+     * Add a rule to the grammar. If the rule already exists, but the implementation differs, an error will be thrown.
+     */
+    addRuleRedundant(rule) {
+        const self = this;
+        const rules = self.rules;
+        if (rules[rule.name] !== undefined && rules[rule.name] !== rule) {
+            throw new Error(`Rule ${rule.name} already exists in the GeneratorBuilder`);
+        }
+        rules[rule.name] = rule;
+        return self;
+    }
+    /**
+     * Add a rule to the grammar. Will raise a typescript error if the rule already exists in the grammar.
+     */
+    addRule(rule) {
+        return this.addRuleRedundant(rule);
+    }
+    addMany(...rules) {
+        this.rules = { ...this.rules, ...listToRuleDefMap(rules) };
+        return this;
+    }
+    /**
+     * Delete a grammar rule by its name.
+     */
+    deleteRule(ruleName) {
+        delete this.rules[ruleName];
+        return this;
+    }
+    /**
+     * Merge this grammar GeneratorBuilder with another.
+     * It is best to merge the bigger grammar with the smaller one.
+     * If the two builders both have a grammar rule with the same name,
+     * no error will be thrown case they map to the same ruledef object.
+     * If they map to a different object, an error will be thrown.
+     * To fix this problem, the overridingRules array should contain a rule with the same conflicting name,
+     * this rule implementation will be used.
+     */
+    merge(GeneratorBuilder, overridingRules) {
+        // Assume the other grammar is bigger than yours. So start from that one and add this one
+        const otherRules = { ...GeneratorBuilder.rules };
+        const myRules = this.rules;
+        for (const rule of Object.values(myRules)) {
+            if (otherRules[rule.name] === undefined) {
+                otherRules[rule.name] = rule;
+            }
+            else {
+                const existingRule = otherRules[rule.name];
+                // If same rule, no issue, move on. Else
+                if (existingRule !== rule) {
+                    const override = overridingRules.find(x => x.name === rule.name);
+                    // If override specified, take override, else, inform user that there is a conflict
+                    if (override) {
+                        otherRules[rule.name] = override;
+                    }
+                    else {
+                        throw new Error(`Rule with name "${rule.name}" already exists in the GeneratorBuilder, specify an override to resolve conflict`);
+                    }
+                }
+            }
+        }
+        this.rules = otherRules;
+        return this;
+    }
+    build() {
+        return new DynamicGenerator(this.rules);
+    }
+}
+//# sourceMappingURL=generatorBuilder.js.map

package/lib/generator-builder/generatorBuilder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generatorBuilder.js","sourceRoot":"","sources":["generatorBuilder.ts"],"names":[],"mappings":"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","sourcesContent":["import type { CheckOverlap } from '../utils';\nimport type { GeneratorFromRules, GenNamesFromList, GenRuleMap, GenRulesToObject } from './builderTypes';\nimport { DynamicGenerator } from './dynamicGenerator';\nimport type { GeneratorRule } from './generatorTypes';\n\n/**\n * Converts a list of ruledefs to a record mapping a name to the corresponding ruledef.\n */\nfunction listToRuleDefMap<T extends readonly GeneratorRule[]>(rules: T): GenRulesToObject<T> {\n  const newRules: Record<string, GeneratorRule> = {};\n  for (const rule of rules) {\n    newRules[rule.name] = rule;\n  }\n  return <GenRulesToObject<T>>newRules;\n}\n\nexport class GeneratorBuilder<Context, Names extends string, RuleDefs extends GenRuleMap<Names>> {\n  /**\n   * Create a GeneratorBuilder from some initial grammar rules or an existing GeneratorBuilder.\n   * If a GeneratorBuilder is provided, a new copy will be created.\n   */\n  public static createBuilder<Context, Names extends string, RuleDefs extends GenRuleMap<Names>>(\n    args: GeneratorBuilder<Context, Names, RuleDefs>\n  ): GeneratorBuilder<Context, Names, RuleDefs>;\n  public static createBuilder<\n    Rules extends readonly GeneratorRule[] = readonly GeneratorRule[],\n    Context = Rules[0] extends GeneratorRule<infer context> ? context : never,\n    Names extends string = GenNamesFromList<Rules>,\n    RuleDefs extends GenRuleMap<Names> = GenRulesToObject<Rules>,\n  >(rules: Rules): GeneratorBuilder<Context, Names, RuleDefs>;\n  public static createBuilder<\n    Rules extends readonly GeneratorRule[] = readonly GeneratorRule[],\n    Context = Rules[0] extends GeneratorRule<infer context> ? context : never,\n    Names extends string = GenNamesFromList<Rules>,\n    RuleDefs extends GenRuleMap<Names> = GenRulesToObject<Rules>,\n  >(\n    start: Rules | GeneratorBuilder<Context, Names, RuleDefs>,\n  ): GeneratorBuilder<Context, Names, RuleDefs> {\n    if (start instanceof GeneratorBuilder) {\n      return new GeneratorBuilder({ ...start.rules });\n    }\n    return <GeneratorBuilder<Context, Names, RuleDefs>> <unknown> new GeneratorBuilder(listToRuleDefMap(start));\n  }\n\n  private rules: RuleDefs;\n\n  private constructor(startRules: RuleDefs) {\n    this.rules = startRules;\n  }\n\n  public typePatch<Patch extends {[Key in Names]?: any }>():\n  GeneratorBuilder<Context, Names, {[Key in Names]: Key extends keyof Patch ? (\n    RuleDefs[Key] extends GeneratorRule<Context, Key, any, infer Args> ?\n      GeneratorRule<Context, Key, Patch[Key], Args> : never\n  ) : (RuleDefs[Key] extends GeneratorRule<Context, Key> ? RuleDefs[Key] : never) }> {\n    return <GeneratorBuilder<Context, Names, {[Key in Names]: Key extends keyof Patch ? (\n      RuleDefs[Key] extends GeneratorRule<Context, Key, any, infer Args> ?\n        GeneratorRule<Context, Key, Patch[Key], Args> : never\n    ) : (RuleDefs[Key] extends GeneratorRule<Context, Key> ? RuleDefs[Key] : never) }>> <unknown> this;\n  }\n\n  /**\n   * Change the implementation of an existing generator rule.\n   */\n  public patchRule<U extends Names, RET, ARGS>(patch: GeneratorRule<Context, U, RET, ARGS>):\n  GeneratorBuilder<Context, Names, {[Key in Names]: Key extends U ?\n    GeneratorRule<Context, Key, RET, ARGS> :\n      (RuleDefs[Key] extends GeneratorRule<Context, Key> ? RuleDefs[Key] : never)\n  } > {\n    const self = <GeneratorBuilder<Context, Names, {[Key in Names]: Key extends U ?\n      GeneratorRule<Context, Key, RET, ARGS> :\n        (RuleDefs[Key] extends GeneratorRule<Context, Key> ? RuleDefs[Key] : never) }>>\n      <unknown> this;\n    self.rules[patch.name] = <any> patch;\n    return self;\n  }\n\n  /**\n   * Add a rule to the grammar. If the rule already exists, but the implementation differs, an error will be thrown.\n   */\n  public addRuleRedundant<U extends string, RET, ARGS>(rule: GeneratorRule<Context, U, RET, ARGS>):\n  GeneratorBuilder<Context, Names | U, {[K in Names | U]: K extends Names ?\n      (RuleDefs[K] extends GeneratorRule<Context, K> ? RuleDefs[K] : never)\n    : (K extends U ? GeneratorRule<Context, K, RET, ARGS> : never)\n  }> {\n    const self = <GeneratorBuilder<Context, Names | U, {[K in Names | U]: K extends Names ?\n        (RuleDefs[K] extends GeneratorRule<Context, K> ? RuleDefs[K] : never)\n      : (K extends U ? GeneratorRule<Context, K, RET, ARGS> : never) }>>\n      <unknown> this;\n    const rules = <Record<string, GeneratorRule<Context>>> self.rules;\n    if (rules[rule.name] !== undefined && rules[rule.name] !== rule) {\n      throw new Error(`Rule ${rule.name} already exists in the GeneratorBuilder`);\n    }\n    rules[rule.name] = rule;\n    return self;\n  }\n\n  /**\n   * Add a rule to the grammar. Will raise a typescript error if the rule already exists in the grammar.\n   */\n  public addRule<U extends string, RET, ARGS>(\n    rule: CheckOverlap<U, Names, GeneratorRule<Context, U, RET, ARGS>>,\n  ): GeneratorBuilder<Context, Names | U, {[K in Names | U]: K extends Names ?\n      (RuleDefs[K] extends GeneratorRule<Context, K> ? RuleDefs[K] : never)\n    : (K extends U ? GeneratorRule<Context, K, RET, ARGS> : never)\n  }> {\n    return this.addRuleRedundant(rule);\n  }\n\n  public addMany<U extends readonly GeneratorRule<Context>[]>(\n    ...rules: CheckOverlap<GenNamesFromList<U>, Names, U>\n  ): GeneratorBuilder<\n    Context,\n    Names | GenNamesFromList<U>,\n    {[K in Names | GenNamesFromList<U>]:\n      K extends keyof GenRulesToObject<typeof rules> ? (\n        GenRulesToObject<typeof rules>[K] extends GeneratorRule<Context, K> ? GenRulesToObject<typeof rules>[K] : never\n      ) : (\n        K extends Names ? (RuleDefs[K] extends GeneratorRule<Context, K> ? RuleDefs[K] : never) : never\n      )\n    }\n  > {\n    this.rules = { ...this.rules, ...listToRuleDefMap(rules) };\n    return <any> <unknown> this;\n  }\n\n  /**\n   * Delete a grammar rule by its name.\n   */\n  public deleteRule<U extends Names>(ruleName: U):\n  GeneratorBuilder<Context, Exclude<Names, U>, {[K in Exclude<Names, U>]:\n    RuleDefs[K] extends GeneratorRule<Context, K> ? RuleDefs[K] : never }> {\n    delete this.rules[ruleName];\n    return <GeneratorBuilder<Context, Exclude<Names, U>, {[K in Exclude<Names, U>]:\n      RuleDefs[K] extends GeneratorRule<Context, K> ? RuleDefs[K] : never }>>\n      <unknown> this;\n  }\n\n  /**\n   * Merge this grammar GeneratorBuilder with another.\n   * It is best to merge the bigger grammar with the smaller one.\n   * If the two builders both have a grammar rule with the same name,\n   * no error will be thrown case they map to the same ruledef object.\n   * If they map to a different object, an error will be thrown.\n   * To fix this problem, the overridingRules array should contain a rule with the same conflicting name,\n   * this rule implementation will be used.\n   */\n  public merge<\n    OtherNames extends string,\n    OtherRules extends GenRuleMap<OtherNames>,\n    OW extends readonly GeneratorRule<Context>[],\n  >(\n    GeneratorBuilder: GeneratorBuilder<Context, OtherNames, OtherRules>,\n    overridingRules: OW,\n  ):\n    GeneratorBuilder<\n      Context,\n      Names | OtherNames | GenNamesFromList<OW>,\n      {[K in Names | OtherNames | GenNamesFromList<OW>]:\n        K extends keyof GenRulesToObject<OW> ? (\n          GenRulesToObject<OW>[K] extends GeneratorRule<Context, K> ? GenRulesToObject<OW>[K] : never\n        )\n          : (\n              K extends Names ? (RuleDefs[K] extends GeneratorRule<Context, K> ? RuleDefs[K] : never)\n                : K extends OtherNames ? (OtherRules[K] extends GeneratorRule<Context, K> ? OtherRules[K] : never)\n                  : never\n            ) }\n    > {\n    // Assume the other grammar is bigger than yours. So start from that one and add this one\n    const otherRules: Record<string, GeneratorRule<Context>> = { ...GeneratorBuilder.rules };\n    const myRules: Record<string, GeneratorRule<Context>> = this.rules;\n\n    for (const rule of Object.values(myRules)) {\n      if (otherRules[rule.name] === undefined) {\n        otherRules[rule.name] = rule;\n      } else {\n        const existingRule = otherRules[rule.name];\n        // If same rule, no issue, move on. Else\n        if (existingRule !== rule) {\n          const override = overridingRules.find(x => x.name === rule.name);\n          // If override specified, take override, else, inform user that there is a conflict\n          if (override) {\n            otherRules[rule.name] = override;\n          } else {\n            throw new Error(`Rule with name \"${rule.name}\" already exists in the GeneratorBuilder, specify an override to resolve conflict`);\n          }\n        }\n      }\n    }\n\n    this.rules = <any> <unknown> otherRules;\n    return <any> <unknown> this;\n  }\n\n  public build(): GeneratorFromRules<Context, Names, RuleDefs> {\n    return <GeneratorFromRules<Context, Names, RuleDefs>> new DynamicGenerator(this.rules);\n  }\n}\n"]}

package/lib/generator-builder/generatorTypes.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Type used to declare generator rules.
+ */
+export type GeneratorRule<
+/**
+ * Context object available in rule implementation.
+ */
+Context = any, 
+/**
+ * Name of grammar rule, should be a strict subtype of string like 'myGrammarRule'.
+ */
+NameType extends string = string, 
+/**
+ * Type that will be returned after a correct parse of this rule.
+ * This type will be the return type of calling SUBRULE with this grammar rule.
+ */
+ReturnType = any, 
+/**
+ * Function arguments that can be given to convey the state of the current parse operation.
+ */
+ParamType = any> = {
+    name: NameType;
+    gImpl: (def: RuleDefArg) => (ast: ReturnType, context: Context, params: ParamType) => string;
+};
+export interface RuleDefArg {
+    SUBRULE: <T, U>(cstDef: GeneratorRule<any, any, T, U>, input: T, arg: U) => string;
+}

package/lib/generator-builder/generatorTypes.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=generatorTypes.js.map

package/lib/generator-builder/generatorTypes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generatorTypes.js","sourceRoot":"","sources":["generatorTypes.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * Type used to declare generator rules.\n */\nexport type GeneratorRule<\n  /**\n   * Context object available in rule implementation.\n   */\n  Context = any,\n  /**\n   * Name of grammar rule, should be a strict subtype of string like 'myGrammarRule'.\n   */\n  NameType extends string = string,\n  /**\n   * Type that will be returned after a correct parse of this rule.\n   * This type will be the return type of calling SUBRULE with this grammar rule.\n   */\n  ReturnType = any,\n  /**\n   * Function arguments that can be given to convey the state of the current parse operation.\n   */\n  ParamType = any,\n> = {\n  name: NameType;\n  gImpl: (def: RuleDefArg) =>\n  (ast: ReturnType, context: Context, params: ParamType) => string;\n};\n\nexport interface RuleDefArg {\n  SUBRULE: <T, U>(cstDef: GeneratorRule<any, any, T, U>, input: T, arg: U) => string;\n}\n"]}