feat(parse)!: IParserTag return defaults to { ast, holes }

Author: michaelfig

packages/parse/src/boot-peg.js

@@ -773,7 +773,7 @@ pos = ${posSrc};`;
         /**
          * @template X
          * @param {ParserOptions} options
-         * @returns {IPegTag<IParserTag<X>>}
+         * @returns {IPegTag<IParserTag<X, any>>}
          */
         const makeExtensionTag = (options = {}) => {
           /**

packages/parse/src/peg.d.ts

@@ -31,7 +31,7 @@ interface ParserOptions {
   debug?: boolean;
 }
 
-interface IParserTag<T = any, U = any> {
+interface IParserTag<T = any, U = { holes: any[]; ast: any }> {
   (template: TemplateStringsArray, ...args: T[]): U;
   options(opts: Partial<ParserOptions>): IParserTag<T, U>;
   parserCreator: PegParserCreator;

packages/parse/src/quasi-json.js

@@ -16,7 +16,7 @@ const makeJSON = peg => {
   const { FAIL, HOLE, SKIP } = peg;
   return peg`
 # to be overridden or inherited
-start <- _WS assignExpr _EOF                ${v => () => v};
+start <- _WS assignExpr _EOF          ${ast => (...holes) => ({ ast, holes })};
 
 # to be extended
 primaryExpr <- dataStructure;

packages/parse/src/quasi-justin.js

@@ -22,9 +22,9 @@
 // See https://github.com/endojs/Jessie/blob/main/README.md
 // for documentation of the Jessie grammar.
 
-// Justin is defined to be extended into the Chainmail grammar, to
-// provide its expression language in a JS-like style. Chainmail
-// expressions need to be pure and should be terminating.
+// Justin is also intended to be extended into the Chainmail grammar, to provide
+// its expression language in a JS-like style. Chainmail expressions need to be
+// pure and should be terminating.
 
 /// <reference path="./peg.d.ts"/>
 
@@ -70,7 +70,7 @@ const makeJustin = peg => {
   const { SKIP } = peg;
   return peg`
     # to be overridden or inherited
-    start <- _WS assignExpr _EOF                       ${v => () => v};
+    start <- _WS assignExpr _EOF ${ast => (...holes) => ({ ast, holes })};
 
     # A.1 Lexical Grammar
 
@@ -147,11 +147,14 @@ const makeJustin = peg => {
     / "interface" / "private" / "public") _WSN;
 
     # Quasiliterals aka template literals
-    QUASI_CHAR <- "\\" . / ~"\`" .;
-    QUASI_ALL <- "\`" < (~"\${" QUASI_CHAR)* > "\`" _WS;
-    QUASI_HEAD <- "\`" < (~"\${" QUASI_CHAR)* > "\${" _WS;
-    QUASI_MID <- "}" < (~"\${" QUASI_CHAR)* > "\${" _WS;
-    QUASI_TAIL <- "}" < (~"\${" QUASI_CHAR)* > "\`" _WS;
+    QCHAR <- "\\" . / ~QQUOTE .;
+    QQUOTE <- "\`";
+    QHOLE <- "\${";
+    QHOLE_END <- "}";
+    QUASI_ALL <- QQUOTE < (~QHOLE QCHAR)* > QQUOTE _WS;
+    QUASI_HEAD <- QQUOTE < (~QHOLE QCHAR)* > QHOLE _WS;
+    QUASI_MID <- QHOLE_END < (~QHOLE QCHAR)* > QHOLE _WS;
+    QUASI_TAIL <- QHOLE_END < (~QHOLE QCHAR)* > QQUOTE _WS;
 
 
     # A.2 Expressions

packages/parse/test/parser-utils.js

@@ -153,7 +153,7 @@ const makeSerialParseWithTools = (testTag, assert) => {
     const dtag = doDebug ? testTag.options({ debug: true }) : testTag;
     const { result, tools } = dtag(tmpl);
     assert(result.status === 'fulfilled', 'parse failed');
-    const parsed = result.value;
+    const parsed = result.value.ast;
     currentTestTools = tools;
     if (doDump) {
       // tslint:disable-next-line:no-console

packages/parse/test/test-justin.js

@@ -35,6 +35,53 @@ test('data', t => {
   t.deepEqual(parse('"\\f\\r\\n\\t\\b"'), ast(0, 'data', '\f\r\n\t\b'));
 });
 
+test('holes', t => {
+  const parseBLD = units => {
+    const { testTag: testJustin } = makeParserUtils(justin, (val, message) =>
+      t.assert(val, message),
+    );
+    const {
+      result,
+      tools: { ast, nest, hole },
+    } = testJustin`make(BLD, ${units}, 'additional arg')`;
+    assert(result.status === 'fulfilled', 'parse failed');
+    const parsed = result.value;
+
+    t.deepEqual(
+      parsed.ast,
+      ast(
+        nest(
+          0,
+          'call',
+          nest(0, 'use', 'make'),
+          nest(
+            4,
+            nest(5, 'use', 'BLD'),
+            hole(0, 'exprHole', 0),
+            nest(2, 'data', 'additional arg'),
+          ),
+        ),
+      ),
+    );
+
+    t.assert(Array.isArray(parsed.holes));
+    const expected = [units];
+    t.is(parsed.holes.length, expected.length);
+    expected.map((v, i) => t.is(parsed.holes[i], v, `hole ${i} is ${v}`));
+
+    return parsed;
+  };
+
+  const p1 = parseBLD(BigInt(123));
+  const p2 = parseBLD(BigInt(123));
+  t.deepEqual(p1, p2);
+  t.is(p1.ast, p2.ast);
+
+  const p3 = parseBLD(456);
+  t.notDeepEqual(p2, p3);
+  t.is(p1.ast, p3.ast);
+});
+
 test('binops', t => {
   const { parse, ast } = makeParserUtils(justin, (val, message) =>
     t.assert(val, message),