feat(extras): Add stored attributes

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

@@ -1,4 +1,4 @@
-import {MatchResult, Grammar, Semantics} from 'ohm-js';
+import {BaseActionDict, Grammar, MatchResult, Node, Semantics} from 'ohm-js';
 
 interface LineAndColumnInfo {
   offset: number;
@@ -44,3 +44,17 @@ interface Example {
  * `//- "shouldn't match"`. The examples text is a JSON string.
  */
 export function extractExamples(grammarsDef: string): [Example];
+
+export type StoredAttributeSetter<T> = (node: Node, val: T) => T;
+
+/**
+ * Add a stored attribute named `attrName` to `semantics`. A stored attribute
+ * is similar to a normal attribute, but instead of being lazily computed, the
+ * value for each node is initialized by an initialization operation.
+ */
+export function addStoredAttribute<T>(
+  semantics: Semantics,
+  attrName: string,
+  initSignature: string,
+  actionProducer: (setter: StoredAttributeSetter<T>) => BaseActionDict<void>
+): Semantics;

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 {addStoredAttribute} from './storedAttributes.js';

packages/ohm-js/extras/storedAttributes.js

@@ -0,0 +1,24 @@
+/*
+  Normal attributes are lazily computed. A stored attribute is initialized
+  by a separate initialization operation. After initialization, you can read
+  a stored attribute's value just like a normal (computed) attribute.
+ */
+export function addStoredAttribute(semantics, attrName, initSignature, fn) {
+  semantics.addAttribute(attrName, {
+    _default() {
+      throw new Error(`Attribute '${attrName}' not initialized`);
+    }
+  });
+
+  // Create the attribute setter, which the semantic actions of the init
+  // operation will close over.
+  const key = semantics._getSemantics().attributeKeys[attrName];
+  const setAttr = (wrapper, val) => {
+    wrapper._node[key] = val;
+    return val;
+  };
+
+  // Create the init operation. It's the user's responsibility to call it.
+  semantics.addOperation(initSignature, fn(setAttr));
+  return semantics;
+}

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

@@ -0,0 +1,48 @@
+import test from 'ava';
+import fs from 'node:fs';
+import {URL} from 'node:url';
+
+import {addStoredAttribute} from '../../extras/storedAttributes.js';
+import * as ohm from '../../index.mjs';
+
+const grammarPath = new URL('../data/arithmetic.ohm', import.meta.url);
+const g = ohm.grammar(fs.readFileSync(grammarPath));
+
+test('stored attributes', t => {
+  const semantics = g.createSemantics();
+  const exp = semantics(g.match('3 + 4 - 1'));
+
+  // A meaningless stored attribute, where nodes have a "polarity" depending
+  // on the type of operation they are involved in. All nodes pass their
+  // polarity downwards, and the default action gives the child the polarity
+  // of its parent.
+  addStoredAttribute(semantics, 'polarity', 'initPolarity(pol)', setPolarity => ({
+    AddExp_plus(expA, _, expB) {
+      setPolarity(this, '+');
+      // Note that we explicitly skip initializing the operator.
+      expA.initPolarity(this.polarity);
+      expB.initPolarity(this.polarity);
+    },
+    AddExp_minus(expA, _, expB) {
+      setPolarity(this, '-');
+      // Note that we explicitly skip initializing the operator.
+      expA.initPolarity(this.polarity);
+      expB.initPolarity(this.polarity);
+    },
+    _default(...children) {
+      // By default, inherit polarity from the parent node.
+      setPolarity(this, this.args.pol);
+      children.forEach(c => c.initPolarity(this.args.pol));
+    }
+  }));
+  exp.initPolarity('=');
+  t.is(exp.polarity, '='); // Exp
+  t.is(exp.child(0).polarity, '='); // AddExp
+  t.is(exp.child(0).child(0).polarity, '-'); // AddExp_minus
+  t.is(exp.child(0).child(0).child(0).polarity, '-'); // AddExp
+  t.is(exp.child(0).child(0).child(0).child(0).polarity, '+'); // AddExp_plus
+
+  t.throws(() => exp.child(0).child(0).child(1).polarity, {
+    message: 'Attribute \'polarity\' not initialized'
+  });
+});