feat: Add recoverIterOrder to extras.

Author: pdubroy

packages/ohm-js/extras/index.d.ts

@@ -1,4 +1,4 @@
-import type {MatchResult, Grammar, Semantics} from '../index.d.ts';
+import type {Grammar, MatchResult, Node, Semantics} from '../index.d.ts';
 
 interface LineAndColumnInfo {
   offset: number;
@@ -44,3 +44,9 @@ interface Example {
  * `//- "shouldn't match"`. The examples text is a JSON string.
  */
 export function extractExamples(grammarsDef: string): [Example];
+
+/*
+  Given an array of nodes, return a new array where (a) all iter nodes are replaced by
+  their children, and (b) nodes appear in the correct source order.
+ */
+export function recoverIterOrder(nodes: Node[]): Node[];

packages/ohm-js/extras/index.mjs

@@ -2,3 +2,4 @@ export {getLineAndColumnMessage, getLineAndColumn} from '../src/util.js';
 export {VisitorFamily} from './VisitorFamily.js';
 export {semanticsForToAST, toAST} from './semantics-toAST.js';
 export {extractExamples} from './extractExamples.js';
+export {recoverIterOrder} from './recoverIterOrder.js';

packages/ohm-js/extras/recoverIterOrder.js

@@ -0,0 +1,48 @@
+/*
+  To find iter nodes that are derived from the same repetition expression, we
+  look for adjacent iter nodes that have the same source interval and the same
+  number of children.
+
+  A few things to note:
+  - The children of `*` and `+` nodes can't be nullable, so the associated iter
+    nodes always consume some input, and therefore consecutive nodes that have
+    the same interval must come from the same repetition expression.
+  - We *could* mistake `a? b?` for (a b)?`, if neither of them comsume any input.
+    However, for the purposes of this module, those two cases are equivalent
+    anyways, since we only care about finding the correct order of the non-iter
+    nodes.
+ */
+const isIterSibling = (refNode, n) => {
+  return (
+    n.isIteration() &&
+    n.source.startIdx === refNode.source.startIdx &&
+    n.source.endIdx === refNode.source.endIdx &&
+    n.children.length === refNode.children.length
+  );
+};
+
+export function recoverIterOrder(nodes, depth = 0) {
+  const ans = [];
+  for (let i = 0; i < nodes.length; i++) {
+    const n = nodes[i];
+    if (!n.isIteration()) {
+      ans.push(n);
+      continue;
+    }
+
+    // We found an iter node, now find its siblings.
+    const siblings = [n];
+    // Find the first node that's *not* part of the current list.
+    for (let j = i + 1; j < nodes.length && isIterSibling(n, nodes[j]); j++) {
+      siblings.push(nodes[j]);
+      i = j;
+    }
+    const cousins = [];
+    const numRows = siblings[0].children.length;
+    for (let row = 0; row < numRows; row++) {
+      cousins.push(...siblings.map(sib => sib.children[row]));
+    }
+    ans.push(...recoverIterOrder(cousins, depth + 1));
+  }
+  return ans;
+}

packages/ohm-js/test/extras/test-recoverIterOrder.js

@@ -0,0 +1,42 @@
+import test from 'ava';
+import {recoverIterOrder} from '../../extras/recoverIterOrder.js';
+import * as ohm from '../../index.mjs';
+
+const g = ohm.grammar(String.raw`
+  G {
+    start = test1 | test2 | test3 | test4
+    test1 = (a b)+ c*
+    test2 = (a b)? c? "."
+    test3 = ((a b)* c)+
+    test4 = (c? (a b*)+)*
+    a = "a"
+    b = "b"
+    c = "c"
+  }
+`);
+
+test('visitInOrder', t => {
+  const semantics = g.createSemantics().addOperation('fix()', {
+    start: child => child.fix(),
+    _default(...children) {
+      return recoverIterOrder(children)
+        .map(c => `${c.ctorName}[${c.source.startIdx}..${c.source.endIdx}]`)
+        .join(' ');
+    },
+  });
+
+  const sig1 = semantics(g.match('abc', 'test1')).fix();
+  t.is(sig1, 'a[0..1] b[1..2] c[2..3]');
+
+  let sig2 = semantics(g.match('.', 'test2')).fix();
+  t.is(sig2, '_terminal[0..1]');
+
+  sig2 = semantics(g.match('ab.', 'test2')).fix();
+  t.is(sig2, 'a[0..1] b[1..2] _terminal[2..3]');
+
+  const sig3 = semantics(g.match('ababcabc', 'test3')).fix();
+  t.is(sig3, 'a[0..1] b[1..2] a[2..3] b[3..4] c[4..5] a[5..6] b[6..7] c[7..8]');
+
+  const sig4 = semantics(g.match('abbabab', 'test4')).fix();
+  t.is(sig4, 'a[0..1] b[1..2] b[2..3] a[3..4] b[4..5] a[5..6] b[6..7]');
+});