@bablr/agast-vm 0.1.3 → 0.2.0

package/README.md

@@ -4,7 +4,7 @@ The agAST VM provides consistency guarantees when with CSTML documents to parse
 
 ## API
 
-The VM responds to several instructions, but its primary API is `advance(token)`, where `token` may be a `OpenFragmentTag`, `CloseFragmentTag`, `OpenNodeTag`, `CloseNodeTag`, `Literal`, `Reference`, or `Gap`.
+The VM responds to several instructions, but its primary API is `advance(token)`, where `token` may be a `OpenNodeTag`, `CloseNodeTag`, `Literal`, `Reference`, or `Gap`.
 
 The VM requires the basic invariants of CSTML to be followed, for example that `Reference` must be followed by either a `OpenNodeTag` or a `Gap`. In fact, `agast-vm` is the reference implementation of these invariants.
 
@@ -15,17 +15,7 @@ Finally the VM supports `bindAttribute(key, value)`. A node's attributes start u
 Here are the basic types used by the VM:
 
 ```ts
-type Token = OpenFragmentTag | CloseFragmentTag | OpenNodeTag | CloseNodeTag | Literal | Reference | Gap;
-
-type OpenFragmentTag {
-  type: 'OpenFragmentTag',
-  value: null
-}
-
-type CloseFragmentTag {
-  type: 'CloseFragmentTag',
-  value: null
-}
+type Token = OpenNodeTag | CloseNodeTag | Literal | Reference | Gap;
 
 type OpenNodeTag {
   type: 'OpenNodeTag',
@@ -35,8 +25,8 @@ type OpenNodeTag {
       trivia: boolean,
       escape: boolean
     },
-    language: string,
-    type: string,
+    language: string | null,
+    type: string | null, // null type indicates a fragment
     attributes: { [key: string]: boolean | number | string }
   }
 }

package/lib/context.js

@@ -24,7 +24,7 @@ function* allTerminalsFor(range, nextTerminals) {
 
   const pastEnd = nextTerminals.get(end);
 
-  for (let tag = start; tag !== pastEnd; tag = nextTerminals.get(tag)) {
+  for (let tag = start; tag && tag !== pastEnd; tag = nextTerminals.get(tag)) {
     yield tag;
   }
 }
@@ -91,7 +91,13 @@ export const Context = class AgastContext {
   }
 
   getProperty(result, name) {
-    return this.tagNodes.get(result[0] || result).properties.get(name);
+    let startTag = result[0] || result;
+
+    if (startTag.type === 'Reference') {
+      startTag = this.nextTerminals.get(startTag);
+    }
+
+    return this.tagNodes.get(startTag).properties.get(name);
   }
 
   isEmpty(range) {

package/lib/evaluate.js

@@ -2,12 +2,12 @@ import { Coroutine } from '@bablr/coroutine';
 import {
   buildNull,
   buildGap,
+  buildShift,
   buildReference,
   buildLiteral,
+  buildWriteEffect,
   buildDoctypeTag,
   buildNodeOpenTag,
-  buildFragmentOpenTag,
-  buildFragmentCloseTag,
   buildNodeCloseTag,
 } from '@bablr/agast-helpers/builders';
 import { StreamIterable, getStreamIterator } from '@bablr/agast-helpers/stream';
@@ -17,9 +17,10 @@ import { Path, Node } from './path.js';
 import { State } from './state.js';
 import { facades } from './facades.js';
 
-export const evaluate = (ctx, strategy) => new StreamIterable(__evaluate(ctx, strategy));
+export const evaluate = (ctx, strategy, options) =>
+  new StreamIterable(__evaluate(ctx, strategy, options));
 
-const __evaluate = function* agast(ctx, strategy) {
+const __evaluate = function* agast(ctx, strategy, options = {}) {
   let s = State.from(ctx);
 
   const co = new Coroutine(getStreamIterator(strategy(facades.get(ctx), facades.get(s))));
@@ -37,7 +38,7 @@ const __evaluate = function* agast(ctx, strategy) {
     const instr = reifyExpression(sourceInstr);
     let returnValue = undefined;
 
-    const { verb } = instr;
+    const { verb, arguments: args = [] } = instr;
 
     switch (verb) {
       case 'branch': {
@@ -66,7 +67,18 @@ const __evaluate = function* agast(ctx, strategy) {
       }
 
       case 'advance': {
-        const { arguments: { 0: terminal, 1: options } = [] } = instr;
+        const { 0: terminal, 1: options } = args;
+
+        if (
+          s.held &&
+          !(
+            terminal.type === 'OpenNodeTag' ||
+            terminal.type === 'Reference' ||
+            terminal.type === 'Gap'
+          )
+        ) {
+          throw new Error('Cannot advance while holding');
+        }
 
         switch (terminal?.type || 'Null') {
           case 'DoctypeTag': {
@@ -109,7 +121,7 @@ const __evaluate = function* agast(ctx, strategy) {
             const tag = buildReference(name, isArray);
 
             if (s.result.type === 'Reference') {
-              throw new Error('double reference');
+              throw new Error('A reference must have a non-reference value');
             }
 
             if (!s.path.depth) {
@@ -139,44 +151,47 @@ const __evaluate = function* agast(ctx, strategy) {
 
             const gapTag = buildGap();
 
+            s.held = null;
+
             yield* s.emit(gapTag);
 
             returnValue = gapTag;
             break;
           }
 
-          case 'Null': {
-            const reference = s.result;
+          case 'Shift': {
+            const { tagNodes, prevTerminals } = ctx;
+            const tag = buildShift();
 
-            if (reference?.type !== 'Reference') throw new Error();
+            const finishedNode = tagNodes.get(s.result);
+            const finishedPath = finishedNode.path;
 
-            s.path = s.path.parent;
+            s.held = { node: finishedNode, path: finishedPath };
 
-            const null_ = buildNull();
+            if (!finishedNode.openTag.value.flags.expression) {
+              throw new Error();
+            }
 
-            yield* s.emit(null_);
+            s.path = finishedPath;
 
-            returnValue = null_;
+            yield* s.emit(tag);
+
+            returnValue = tag;
             break;
           }
 
-          case 'OpenFragmentTag': {
-            const openTag = buildFragmentOpenTag();
-
-            s.node = Node.from(openTag);
+          case 'Null': {
+            const reference = s.result;
 
-            yield* s.emit(openTag);
+            if (reference?.type !== 'Reference') throw new Error();
 
-            returnValue = openTag;
-            break;
-          }
+            s.path = s.path.parent;
 
-          case 'CloseFragmentTag': {
-            const closeTag = buildFragmentCloseTag();
+            const null_ = buildNull();
 
-            yield* s.emit(closeTag);
+            yield* s.emit(null_);
 
-            returnValue = closeTag;
+            returnValue = null_;
             break;
           }
 
@@ -186,46 +201,51 @@ const __evaluate = function* agast(ctx, strategy) {
             const reference = s.result;
             const openTag = buildNodeOpenTag(flags, language, type, intrinsicValue, attributes);
 
-            if (!flags.trivia && !flags.escape && s.path.depth > 1) {
-              if (reference.type !== 'Reference' && reference.type !== 'OpenFragmentTag') {
-                throw new Error('Invalid location for OpenNodeTag');
+            if (!type) {
+              s.node = Node.from(s.path, openTag);
+              ctx.tagNodes.set(openTag, s.node);
+            } else {
+              if (!flags.trivia && !flags.escape && s.node.type) {
+                if (
+                  reference.type !== 'Reference' &&
+                  reference.type !== 'Shift' &&
+                  reference.type !== 'OpenFragmentTag'
+                ) {
+                  throw new Error('Invalid location for OpenNodeTag');
+                }
               }
-            }
 
-            const { flags: openFlags } = openTag.value;
+              const { flags: openFlags } = openTag.value;
 
-            if (!(openFlags.trivia || openFlags.escape) && !s.path.depth) {
-              const tag = buildReference('root', false);
-              s.path = s.path.push(ctx, tag);
-              s.node.resolver.consume(tag);
-            }
-
-            if (flags.expression && !flags.intrinsic) {
-              s.expressionDepth++;
-            }
+              if (!(openFlags.trivia || openFlags.escape) && !s.path.depth) {
+                const tag = buildReference('root', false);
+                s.path = s.path.push(ctx, tag);
+                s.node.resolver.consume(tag);
+              }
 
-            const newNode = s.node.push(openTag);
+              const newNode = s.node.push(s.path, openTag);
 
-            newNode.unboundAttributes = new Set(unboundAttributes);
+              newNode.unboundAttributes = new Set(unboundAttributes);
 
-            ctx.tagNodes.set(openTag, newNode);
+              ctx.tagNodes.set(openTag, newNode);
 
-            if (!intrinsicValue) {
-              s.node = newNode;
-            } else {
-              s.path = s.path.parent;
+              if (!intrinsicValue) {
+                s.node = newNode;
+              } else {
+                s.path = s.path.parent;
 
-              if (s.path.depth > 1) {
-                const { properties } = s.node;
-                const { name: refName, isArray } = reference.value;
+                if (s.path.depth > 1) {
+                  const { properties } = s.node;
+                  const { name: refName, isArray } = reference.value;
 
-                if (!isArray) {
-                  properties.set(refName, [openTag, openTag]);
-                } else {
-                  if (!properties.has(refName)) {
-                    properties.set(refName, []);
+                  if (!isArray) {
+                    properties.set(refName, [openTag, openTag]);
+                  } else {
+                    if (!properties.has(refName)) {
+                      properties.set(refName, []);
+                    }
+                    properties.get(refName).push([openTag, openTag]);
                   }
-                  properties.get(refName).push([openTag, openTag]);
                 }
               }
             }
@@ -241,48 +261,46 @@ const __evaluate = function* agast(ctx, strategy) {
             const { openTag } = s.node;
             const { flags, type: openType } = openTag.value;
 
-            if (s.node.unboundAttributes?.size)
-              throw new Error('Grammar failed to bind all attributes');
+            const closeTag = buildNodeCloseTag(type, language);
 
-            if (!type) throw new Error(`CloseNodeTag must have type`);
+            if (openType) {
+              if (s.node.unboundAttributes?.size)
+                throw new Error('Grammar failed to bind all attributes');
 
-            if (s.path.depth > 1 && type !== openType)
-              throw new Error(
-                `Grammar close {type: ${type}} did not match open {type: ${openType}}`,
-              );
+              if (!type) throw new Error(`CloseNodeTag must have type`);
 
-            const closeTag = buildNodeCloseTag(type, language);
+              if (s.path.depth > 1 && type !== openType)
+                throw new Error(
+                  `Grammar close {type: ${type}} did not match open {type: ${openType}}`,
+                );
 
-            if (!flags.escape && !flags.trivia) {
-              const { name: refName, isArray } = s.path.reference.value;
+              if (!flags.escape && !flags.trivia) {
+                const { name: refName, isArray } = s.path.reference.value;
 
-              // is this right?
-              if (s.path.depth > 2) {
-                const { properties } = s.node.parent;
+                // is this right?
+                if (s.path.depth > 2) {
+                  const { properties } = s.node.parent;
 
-                if (!isArray) {
-                  properties.set(refName, [openTag, closeTag]);
-                } else {
-                  if (!properties.has(refName)) {
-                    properties.set(refName, []);
+                  if (!isArray) {
+                    properties.set(refName, [openTag, closeTag]);
+                  } else {
+                    if (!properties.has(refName)) {
+                      properties.set(refName, []);
+                    }
+                    properties.get(refName).push([openTag, closeTag]);
                   }
-                  properties.get(refName).push([openTag, closeTag]);
                 }
               }
-            }
 
-            if (flags.expression) {
-              s.expressionDepth--;
-            }
+              ctx.tagNodes.set(closeTag, s.node);
 
-            ctx.tagNodes.set(closeTag, s.node);
+              s.node.closeTag = closeTag;
 
-            s.node.closeTag = closeTag;
+              s.node = s.node.parent;
 
-            s.node = s.node.parent;
-
-            if (!(flags.trivia || flags.escape)) {
-              s.path = s.path.parent;
+              if (!(flags.trivia || flags.escape)) {
+                s.path = s.path.parent;
+              }
             }
 
             yield* s.emit(closeTag, flags.expression);
@@ -298,18 +316,8 @@ const __evaluate = function* agast(ctx, strategy) {
         break;
       }
 
-      case 'shift': {
-        s.shift();
-        break;
-      }
-
-      case 'unshift': {
-        s.unshift();
-        break;
-      }
-
       case 'bindAttribute': {
-        const { arguments: { 0: key, 1: value } = [] } = instr;
+        const { 0: key, 1: value } = args;
 
         const { unboundAttributes } = s.node;
 
@@ -317,8 +325,8 @@ const __evaluate = function* agast(ctx, strategy) {
           throw new Error('No unbound attribute to bind');
         }
 
-        if (s.node.openTag.type === 'OpenFragmentTag') {
-          throw new Error();
+        if (!s.node.openTag.value.type) {
+          throw new Error('Cannot bind attribute to fragment');
         }
 
         if (key === 'span') throw new Error('too late');
@@ -378,6 +386,13 @@ const __evaluate = function* agast(ctx, strategy) {
         break;
       }
 
+      case 'write': {
+        if (options.emitEffects) {
+          yield buildWriteEffect(args[0], args[1]);
+        }
+        break;
+      }
+
       default: {
         throw new Error(`Unexpected call of {type: ${printExpression(verb)}}`);
       }

package/lib/path.js

@@ -1,15 +1,8 @@
 import { WeakStackFrame } from '@bablr/weak-stack';
 import { Resolver } from '@bablr/agast-helpers/tree';
-import { findRight } from './utils/array.js';
+import { skipToDepth, buildSkips } from './utils/skip.js';
 import { facades, actuals } from './facades.js';
 
-const skipLevels = 3;
-const skipShiftExponentGrowth = 4;
-const skipAmounts = new Array(skipLevels)
-  .fill(null)
-  .map((_, i) => 2 >> (i * skipShiftExponentGrowth));
-const skipsByPath = new WeakMap();
-
 export const NodeFacade = class AgastNodeFacade {
   constructor(path) {
     facades.set(path, this);
@@ -54,6 +47,10 @@ export const NodeFacade = class AgastNodeFacade {
   get attributes() {
     return actuals.get(this).attributes;
   }
+
+  at(depth) {
+    return facades.get(actuals.get(this).at(depth));
+  }
 };
 
 export const PathFacade = class AgastPathFacade {
@@ -74,17 +71,7 @@ export const PathFacade = class AgastPathFacade {
   }
 
   at(depth) {
-    let parent = this;
-
-    if (depth > this.depth) throw new Error();
-
-    let d = actuals.get(parent).depth;
-    for (; d > depth; ) {
-      const skips = skipsByPath.get(actuals.get(this));
-      parent = (skips && findRight(skips, (skip) => d - skip > depth)) || parent.parent;
-      d = actuals.get(parent).depth;
-    }
-    return parent;
+    return facades.get(actuals.get(this).at(depth));
   }
 
   *parents(includeSelf = false) {
@@ -97,11 +84,12 @@ export const PathFacade = class AgastPathFacade {
 };
 
 export const Node = class AgastNode extends WeakStackFrame {
-  static from(openTag) {
-    return AgastNode.create(openTag);
+  static from(path, openTag) {
+    return AgastNode.create(path, openTag);
   }
 
   constructor(
+    path,
     openTag,
     closeTag = null,
     properties = new Map(),
@@ -110,11 +98,14 @@ export const Node = class AgastNode extends WeakStackFrame {
   ) {
     super();
 
+    this.path = path;
     this.openTag = openTag;
     this.closeTag = closeTag;
     this.properties = properties;
     this.resolver = resolver;
     this.unboundAttributes = unboundAttributes;
+
+    buildSkips(this);
   }
 
   get language() {
@@ -122,7 +113,7 @@ export const Node = class AgastNode extends WeakStackFrame {
   }
 
   get type() {
-    return this.openTag.value?.type || Symbol.for('@bablr/fragment');
+    return this.openTag.value?.type || null;
   }
 
   get flags() {
@@ -133,10 +124,23 @@ export const Node = class AgastNode extends WeakStackFrame {
     return this.openTag.value?.attributes || {};
   }
 
+  at(depth) {
+    return skipToDepth(depth, this);
+  }
+
+  *parents(includeSelf = false) {
+    if (includeSelf) yield this;
+    let parent = this;
+    while ((parent = parent.parent)) {
+      yield parent;
+    }
+  }
+
   branch() {
-    const { openTag, closeTag, properties, resolver, unboundAttributes } = this;
+    const { path, openTag, closeTag, properties, resolver, unboundAttributes } = this;
 
     return this.replace(
+      path,
       openTag,
       closeTag,
       new Map(properties), // there is probably a better way
@@ -146,6 +150,7 @@ export const Node = class AgastNode extends WeakStackFrame {
   }
 
   accept(node) {
+    this.path = node.path;
     this.openTag = node.openTag;
     this.closeTag = node.closeTag;
     this.properties = node.properties;
@@ -172,36 +177,13 @@ export const Path = class AgastPath extends WeakStackFrame {
     this.context = context;
     this.reference = reference;
 
-    let skipIdx = 0;
-    let skipAmount = skipAmounts[skipIdx];
-    let skips;
-    while ((this.depth & skipAmount) === skipAmount) {
-      if (!skips) {
-        skips = [];
-        skipsByPath.set(this, skips);
-      }
-
-      skips[skipIdx] = this.at(this.depth - skipAmount);
-
-      skipIdx++;
-      skipAmount = skipAmounts[skipIdx];
-    }
+    buildSkips(this);
 
     new PathFacade(this);
   }
 
   at(depth) {
-    let parent = this;
-
-    if (depth > this.depth) throw new Error();
-
-    let d = this.depth;
-    for (; d > depth; ) {
-      const skips = skipsByPath.get(this);
-      parent = (skips && findRight(skips, (skip) => d - skip > depth)) || parent.parent;
-      d = parent.depth;
-    }
-    return parent;
+    return skipToDepth(depth, this);
   }
 
   *parents(includeSelf = false) {

package/lib/state.js

@@ -1,6 +1,7 @@
 import { WeakStackFrame } from '@bablr/weak-stack';
 import { startsDocument } from '@bablr/agast-helpers/stream';
 import { facades, actuals } from './facades.js';
+import { buildBeginningOfStreamToken } from '@bablr/agast-helpers/builders';
 
 export const StateFacade = class AgastStateFacade {
   constructor(state) {
@@ -45,10 +46,9 @@ export const State = class AgastState extends WeakStackFrame {
     context,
     path = null,
     node = null,
-    result = null,
+    result = buildBeginningOfStreamToken(),
     emitted = null,
     held = null,
-    expressionDepth = 0,
   ) {
     super();
 
@@ -60,7 +60,6 @@ export const State = class AgastState extends WeakStackFrame {
     this.result = result;
     this.emitted = emitted;
     this.held = held;
-    this.expressionDepth = expressionDepth;
 
     new StateFacade(this);
   }
@@ -73,39 +72,6 @@ export const State = class AgastState extends WeakStackFrame {
     return !!this.held;
   }
 
-  shift() {
-    const { tagNodes, prevTerminals, nextTerminals } = this.context;
-
-    const finishedNode = tagNodes.get(this.result);
-
-    if (!finishedNode.openTag.value.flags.expression) {
-      throw new Error();
-    }
-
-    this.result = prevTerminals.get(finishedNode.openTag);
-
-    nextTerminals.delete(this.result);
-
-    this.held = finishedNode;
-
-    // put the first expression node into the holding register
-  }
-
-  unshift() {
-    const { tagNodes, prevTerminals, nextTerminals } = this.context;
-
-    if (!this.held) {
-      throw new Error('cannot unshift when no expression is in the holding register');
-    }
-
-    nextTerminals.set(this.result, this.held.openTag);
-    prevTerminals.set(this.held.openTag, this.result);
-
-    this.result = this.held.closeTag;
-
-    this.held = null;
-  }
-
   *emit(terminal, suppressEmit) {
     const { prevTerminals, nextTerminals, tagNodes } = this.context;
 
@@ -118,13 +84,11 @@ export const State = class AgastState extends WeakStackFrame {
         this.result?.type === 'Reference' &&
         !['OpenNodeTag', 'Gap', 'Null'].includes(terminal.type)
       ) {
-        throw new Error('Bad reference emit');
+        throw new Error(`${terminal.type} is not a valid reference target`);
       }
 
       prevTerminals.set(terminal, this.result);
-      if (this.result) {
-        nextTerminals.set(this.result, terminal);
-      }
+      nextTerminals.set(this.result, terminal);
 
       this.result = terminal;
 
@@ -135,12 +99,16 @@ export const State = class AgastState extends WeakStackFrame {
       }
     }
 
-    if (!this.depth && !this.expressionDepth && !suppressEmit) {
+    if (!this.depth && !suppressEmit) {
       let emittable = nextTerminals.get(this.emitted);
 
       while (
         emittable &&
-        !(emittable.type === 'OpenNodeTag' && tagNodes.get(emittable).unboundAttributes?.size)
+        !(
+          emittable.type === 'OpenNodeTag' &&
+          emittable.value.type &&
+          tagNodes.get(emittable).unboundAttributes?.size
+        )
       ) {
         yield emittable;
         this.emitted = emittable;
@@ -164,16 +132,16 @@ export const State = class AgastState extends WeakStackFrame {
   }
 
   branch() {
-    const { context, path, node, result, emitted, held, expressionDepth } = this;
+    const { context, path, node, result, emitted, held } = this;
 
-    return this.push(context, path, node.branch(), result, emitted, held, expressionDepth);
+    return this.push(context, path, node.branch(), result, emitted, held);
   }
 
   accept() {
     const { parent } = this;
 
     if (!parent) {
-      throw new Error('accepted the root state');
+      return null;
     }
 
     parent.node.accept(this.node);
@@ -183,7 +151,6 @@ export const State = class AgastState extends WeakStackFrame {
     parent.result = this.result;
     parent.held = this.held;
     parent.path = this.path;
-    parent.expressionDepth = this.expressionDepth;
 
     return parent;
   }

package/lib/utils/skip.js

@@ -0,0 +1,39 @@
+import { findRight } from './array.js';
+
+const skipLevels = 3;
+const skipShiftExponentGrowth = 4;
+const skipAmounts = new Array(skipLevels)
+  .fill(null)
+  .map((_, i) => 2 >> (i * skipShiftExponentGrowth));
+const skipsByFrame = new WeakMap();
+
+export const buildSkips = (frame) => {
+  let skipIdx = 0;
+  let skipAmount = skipAmounts[skipIdx];
+  let skips;
+  while ((frame.depth & skipAmount) === skipAmount) {
+    if (!skips) {
+      skips = [];
+      skipsByFrame.set(frame, skips);
+    }
+
+    skips[skipIdx] = frame.at(frame.depth - skipAmount);
+
+    skipIdx++;
+    skipAmount = skipAmounts[skipIdx];
+  }
+};
+
+export const skipToDepth = (depth, frame) => {
+  let parent = frame;
+
+  if (depth > frame.depth) throw new Error();
+
+  let d = frame.depth;
+  for (; d > depth; ) {
+    const skips = skipsByFrame.get(frame);
+    parent = (skips && findRight(skips, (skip) => d - skip > depth)) || parent.parent;
+    d = parent.depth;
+  }
+  return parent;
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@bablr/agast-vm",
   "description": "A VM providing DOM-like guarantees about agAST trees",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "author": "Conrad Buck<conartist6@gmail.com>",
   "type": "module",
   "files": [
@@ -15,8 +15,8 @@
     "test": "node ./test/runner.js"
   },
   "dependencies": {
-    "@bablr/agast-helpers": "0.1.5",
-    "@bablr/agast-vm-helpers": "0.1.3",
+    "@bablr/agast-helpers": "0.1.6",
+    "@bablr/agast-vm-helpers": "0.1.5",
     "@bablr/coroutine": "0.1.0",
     "@bablr/weak-stack": "0.1.0"
   },