@bablr/agast-vm 0.8.0 → 0.9.0

package/README.md

@@ -1,58 +1,23 @@
 # @bablr/agast-vm
 
-The agAST VM provides consistency guarantees when with CSTML documents to parse or transform code. It has no language-specific functionality of any kind. Instead it acts as a streaming traversal engine for CSTML.
+The agAST VM's purpose is to define what is valid agAST. For complete documentation, see the [agast-vm API reference](https://docs.bablr.org/reference/agast-vm).
 
-## API
+## Usage
 
-The VM responds to several instructions, but its primary API is `advance(token)`, where `token` may be a `OpenNodeTag`, `CloseNodeTag`, `Literal`, `Reference`, or `Gap`.
+```js
+import { agast } from '@bablr/agast-vm';
+import * as b from '@bablr/agast-helpers/builders';
 
-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.
+let vm = agast();
+let step;
 
-The VM supports `branch()`, `accept()`, and `reject()` instructions, which allow a series of instructions to have their effects applied or discarded together in a kind of transaction.
+let openTag = b.buildOpenNodeTag(b.tokenFlags, 'Token');
+let closeTag = b.buildLiteralTag('OK');
+let closeTag = b.buildCloseNodeTag();
 
-Finally the VM supports `bindAttribute(key, value)`. A node's attributes start unbound, and this command is used to give them values. Once all declared attributes for a node are bound, that node's full start tag is known and can be emitted.
+step = vm.next(openTag);
+step = vm.next(literalTag);
+step = vm.next(closeTag);
 
-Here are the basic types used by the VM:
-
-```ts
-type Token = OpenNodeTag | CloseNodeTag | Literal | Reference | Gap;
-
-type OpenNodeTag {
-  type: 'OpenNodeTag',
-  value: {
-    flags: {
-      token: boolean,
-      trivia: boolean,
-      escape: boolean
-    },
-    language: string | null,
-    type: string | null, // null type indicates a fragment
-    attributes: { [key: string]: boolean | number | string }
-  }
-}
-
-type CloseNodeTag {
-  type: 'CloseNodeTag',
-  value: {
-    language: string,
-    type: string,
-  }
-}
-
-type Literal {
-  value: string
-}
-
-type Reference {
-  type: 'Reference',
-  value: {
-    name: string,
-    isArray: boolean
-  }
-}
-
-type Gap {
-  type: 'Gap',
-  value: null,
-}
+let node = step.value;
 ```

package/lib/evaluate.js

@@ -1,18 +1,3 @@
-import { Coroutine } from '@bablr/coroutine';
-import {
-  buildNullTag,
-  buildGapTag,
-  buildShiftTag,
-  buildReferenceTag,
-  buildLiteralTag,
-  buildDoctypeTag,
-  buildOpenNodeTag,
-  buildCloseNodeTag,
-  buildInitializerTag,
-} from '@bablr/agast-vm-helpers/internal-builders';
-import { getEmbeddedTag } from '@bablr/agast-vm-helpers/deembed';
-import { StreamIterable, getStreamIterator } from '@bablr/agast-helpers/stream';
-import { printExpression } from '@bablr/agast-helpers/print';
 import {
   DoctypeTag,
   OpenNodeTag,
@@ -23,186 +8,170 @@ import {
   NullTag,
   InitializerTag,
   LiteralTag,
+  AttributeDefinition,
+  BindingTag,
+  Property,
 } from '@bablr/agast-helpers/symbols';
 import { State } from './state.js';
-import { Context } from './context.js';
 import { facades } from './facades.js';
-import { add, TagPath } from '@bablr/agast-helpers/path';
-import { buildNullNode, defineAttribute } from '@bablr/agast-helpers/tree';
-
-export const agast = (strategy, options = {}) => {
-  const ctx = Context.create();
-  let s = State.from(ctx, options.expressions);
+import { getFirstNode, TagPath } from '@bablr/agast-helpers/path';
+import * as sumtree from '@bablr/agast-helpers/children';
+import { NodeFacade } from './node.js';
 
-  return new StreamIterable(__agast(ctx, s, strategy(facades.get(ctx), facades.get(s))));
-};
+let { isArray } = Array;
 
-function* __agast(ctx, s, instructions) {
-  const co = new Coroutine(getStreamIterator(instructions));
+export const agast = (options = {}) => {
+  if (options.held?.properties) throw new Error();
 
-  co.advance();
+  let state = State.from(options.held);
 
-  for (;;) {
-    if (co.current instanceof Promise) {
-      co.current = yield co.current;
-    }
+  let vm = __agast(state, options);
 
-    if (co.done) break;
+  vm.next();
 
-    const instr = co.value;
+  Object.freeze(options);
 
-    let returnValue = undefined;
+  return Object.freeze({ options, state: facades.get(state), vm });
+};
 
-    const { verb, arguments: args = [] } = instr;
+function* __agast(s) {
+  let tag = yield;
+  for (;;) {
+    let returnValue = null;
 
-    switch (verb) {
-      case 'advance': {
-        const { 0: embeddedTags } = args;
+    if (s.resultPath && !s.path) {
+      throw new Error('Cannot advance after completion');
+    }
 
-        const tag = getEmbeddedTag(embeddedTags);
+    if (
+      s.held &&
+      ![OpenNodeTag, ReferenceTag, InitializerTag, Property, BindingTag].includes(tag.type) &&
+      !(
+        (tag.type === Property &&
+          (sumtree.getSize(tag.value.node.children) <= 1 ||
+            getFirstNode(tag.value.node) === s.held.node)) ||
+        tag.value.node === s.held.node
+      )
+    ) {
+      throw new Error('Cannot advance while holding');
+    }
 
-        if (
-          s.held &&
-          !(tag.type === OpenNodeTag || tag.type === ReferenceTag || tag.type === GapTag)
-        ) {
-          throw new Error('Cannot advance while holding');
+    switch (tag.type) {
+      case DoctypeTag: {
+        if (s.path) {
+          throw new Error();
         }
 
-        switch (tag?.type || NullTag) {
-          case DoctypeTag: {
-            const { attributes } = tag.value;
+        s.advance(tag);
+        break;
+      }
 
-            if (s.path.depth !== 0) {
-              throw new Error();
-            }
+      case LiteralTag: {
+        if (!s.node.flags.token) {
+          throw new Error('literals must occur inside tokens');
+        }
 
-            returnValue = s.advance(buildDoctypeTag(attributes));
-            break;
-          }
+        if (s.held) {
+          throw new Error('Cannot consume input while hold register is full');
+        }
 
-          case LiteralTag: {
-            if (!s.node.flags.token) {
-              throw new Error('literals must occur inside tokens');
-            }
+        s.advance(tag);
+        break;
+      }
 
-            if (s.held) {
-              throw new Error('Cannot consume input while hold register is full');
-            }
+      case ReferenceTag: {
+        const { type } = tag.value;
 
-            returnValue = s.advance(buildLiteralTag(tag.value));
-            break;
-          }
+        if (s.node?.flags.token && type !== '@') {
+          throw new Error('A token node cannot contain a reference');
+        }
 
-          case ReferenceTag: {
-            const { name, isArray, flags } = tag.value;
+        s.advance(tag);
+        break;
+      }
 
-            if (s.node?.flags.token && name !== '@') {
-              throw new Error('A token node cannot contain a reference');
-            }
+      case BindingTag: {
+        const { languagePath } = tag.value;
 
-            returnValue = s.advance(buildReferenceTag(name, isArray, flags));
-            break;
-          }
+        if (languagePath && !isArray(languagePath)) throw new Error();
 
-          case GapTag: {
-            returnValue = s.advance(buildGapTag());
-            break;
-          }
+        s.advance(tag);
+        break;
+      }
 
-          case NullTag: {
-            returnValue = s.advance(buildNullTag());
-            break;
-          }
+      case NullTag:
+      case GapTag: {
+        s.advance(tag);
+        returnValue = new NodeFacade(s.resultPath.node);
+        break;
+      }
 
-          case InitializerTag: {
-            const { isArray } = tag.value;
-            const { reference } = s;
+      case AttributeDefinition: {
+        if (s.atReference) throw new Error();
 
-            if (reference?.type !== ReferenceTag) throw new Error();
+        s.advance(tag);
+        break;
+      }
 
-            returnValue = s.advance(buildInitializerTag(isArray));
-            break;
-          }
+      case InitializerTag: {
+        if (!s.atReference) throw new Error();
 
-          case ShiftTag: {
-            const { index } = tag.value;
-            if (s.resultPath.tag.type !== GapTag) throw new Error();
+        s.advance(tag);
+        break;
+      }
 
-            let prevRef = s.resultPath.previousSibling;
+      case ShiftTag: {
+        const { index } = tag.value;
+        if (s.resultPath.tag.type !== Property) throw new Error();
 
-            if (prevRef.tag.type === ShiftTag) {
-              if (prevRef.tag.value.index + 1 !== index) throw new Error('bad shift index');
-            }
+        let prevRef = s.resultPath.previousSibling.previousSibling;
 
-            const refPath = TagPath.from(
-              s.resultPath.path,
-              s.resultPath.childrenIndex - (index - 1) * 2 - 1,
-            );
+        if (prevRef.tag.type === ShiftTag) {
+          if (prevRef.tag.value.index + 1 !== index) throw new Error('bad shift index');
+        }
 
-            if (refPath.tag.type !== ReferenceTag) throw new Error();
+        let refPath = TagPath.from(
+          s.resultPath.path,
+          s.resultPath.childrenIndex - (index - 1) * 3 - 2,
+        );
 
-            if (!refPath.tag.value.flags.expression) {
-              throw new Error();
-            }
+        if (refPath.tag.type !== ReferenceTag) throw new Error();
 
-            returnValue = s.advance(buildShiftTag(index));
-            break;
-          }
+        if (!refPath.tag.value.flags.expression) {
+          throw new Error();
+        }
 
-          case OpenNodeTag: {
-            const { flags, language, type, attributes } = tag.value;
+        s.advance(tag);
+        break;
+      }
 
-            if (language && !language.startsWith('https://')) {
-              throw new Error('Expected an absolute-language tag');
-            }
+      case OpenNodeTag: {
+        s.advance(tag);
 
-            returnValue = s.advance(buildOpenNodeTag(flags, language, type, attributes));
-            break;
-          }
+        returnValue = new NodeFacade(s.node);
+        break;
+      }
 
-          case CloseNodeTag: {
-            for (const { 0: key, 1: value } of Object.entries(s.node.properties)) {
-              if (!Array.isArray(value)) {
-                if (value.node === undefined) {
-                  add(s.node, value.reference, buildNullNode());
-                }
-              }
-            }
-
-            for (const { 0: key, 1: value } of Object.entries(s.node.attributes)) {
-              if (value === undefined) {
-                defineAttribute(s.node, key, null);
-              }
-            }
+      case CloseNodeTag: {
+        returnValue = new NodeFacade(s.node);
 
-            returnValue = s.advance(buildCloseNodeTag());
-            break;
-          }
+        s.advance(tag);
+        break;
+      }
 
-          default:
-            throw new Error();
-        }
+      case Property: {
+        let { node } = tag.value;
 
-        yield returnValue;
+        s.advance(tag);
 
+        returnValue = new NodeFacade(node);
         break;
       }
 
-      default: {
-        throw new Error(`Unexpected call of {type: ${printExpression(verb)}}`);
-      }
+      default:
+        throw new Error();
     }
 
-    co.advance(returnValue);
+    tag = yield returnValue;
   }
-
-  if (s.depth > 0) {
-    throw new Error('Did not unwind state stack');
-  }
-
-  if (s.path) {
-    throw new Error('Did not unwind path stack');
-  }
-
-  return s.resultPath.path.node;
 }

package/lib/index.js

@@ -1,3 +1,4 @@
 export { agast } from './evaluate.js';
 
-export { Context } from './context.js';
+export { PathFacade, TagPathFacade } from './path.js';
+export { NodeFacade } from './node.js';

package/lib/node.js

@@ -0,0 +1,176 @@
+import {
+  buildPathSegment,
+  get,
+  getChildPropertyIndex,
+  getCloseTag,
+  getProperties,
+  getPropertyChildrenIndex,
+} from '@bablr/agast-helpers/path';
+import * as sumtree from '@bablr/agast-helpers/children';
+import * as btree from '@bablr/agast-helpers/btree';
+import { DoctypeTag, GapTag, NullTag, OpenNodeTag } from '@bablr/agast-helpers/symbols';
+import { nodeFlags } from '@bablr/agast-helpers/builders';
+import { nodeStates } from './state.js';
+
+let { freeze, hasOwn } = Object;
+
+export const nodes = new WeakMap();
+
+export class NodeChildrenFacade {
+  constructor(node) {
+    nodes.set(this, node);
+    let tree = node.children;
+
+    if (!Object.isFrozen(tree)) throw new Error(); // just a sanity check right now
+
+    this.size = sumtree.getSize(tree);
+
+    freeze(this);
+  }
+
+  at(idx) {
+    return sumtree.getAt(idx, nodes.get(this).children);
+  }
+
+  [Symbol.iterator]() {
+    return sumtree.traverse(nodes.get(this).children);
+  }
+}
+
+export class ListFacade {
+  constructor(tree) {
+    nodes.set(this, tree);
+
+    this.size = btree.getSize(tree);
+
+    freeze(this);
+  }
+
+  at(idx) {
+    return btree.getAt(idx, nodes.get(this));
+  }
+
+  [Symbol.iterator]() {
+    return btree.traverse(nodes.get(this));
+  }
+}
+
+export class NodePropertiesFacade {
+  constructor(node) {
+    nodes.set(this, node);
+
+    freeze(this);
+  }
+
+  at(name, index = -1, shiftIndex = 0) {
+    let { properties } = nodes.get(this);
+
+    if (hasOwn(properties, name)) {
+      let prop = properties[name];
+
+      if (Array.isArray(prop.node) && index === -1) {
+        return new ListFacade(prop.node);
+      }
+
+      if (Array.isArray(prop.node)) {
+        prop = btree.getAt(index ?? -1, prop.node);
+      }
+
+      if (!prop) return index === -1 ? prop : null;
+      if (prop.reference.flags.expression) {
+        return NodeFacade.from(btree.getAt(shiftIndex + 1, prop.node)?.node);
+      } else {
+        return NodeFacade.from(prop.node);
+      }
+    }
+    return null;
+  }
+
+  has(name, index = -1) {
+    let { properties } = nodes.get(this);
+    if (!hasOwn(properties, name)) return false;
+
+    if (index >= 0 && !getProperties(name, index, properties)) {
+      return false;
+    }
+
+    return true;
+  }
+
+  referenceAt(name, index = -1) {
+    return getProperties(buildPathSegment(name, index), nodes.get(this).properties)?.reference;
+  }
+
+  [Symbol.iterator]() {
+    return Object.entries(nodes.get(this))[Symbol.iterator]();
+  }
+}
+
+export class NodeFacade {
+  static from(node) {
+    return node && new NodeFacade(node);
+  }
+
+  constructor(node) {
+    let sigilTag = sumtree.getAt(0, node.children);
+
+    if (sigilTag.type === DoctypeTag) {
+      sigilTag = sumtree.getAt(1, node.children);
+    }
+
+    this.sigilTag = sigilTag;
+
+    if ([NullTag, GapTag].includes(sigilTag.type)) {
+      this.flags = nodeFlags;
+      this.type = null;
+    } else if (sigilTag.type === OpenNodeTag) {
+      let { flags, type } = sigilTag.value;
+
+      this.flags = flags;
+      this.type = type;
+    } else {
+      throw new Error();
+    }
+
+    nodes.set(this, node);
+
+    freeze(this);
+  }
+
+  get children() {
+    return new NodeChildrenFacade(nodes.get(this));
+  }
+
+  get properties() {
+    return new NodePropertiesFacade(nodes.get(this));
+  }
+
+  get attributes() {
+    return nodes.get(this).attributes;
+  }
+
+  get undefinedAttributes() {
+    return nodeStates.get(nodes.get(this)).undefinedAttributes;
+  }
+
+  get node() {
+    let node = nodes.get(this);
+
+    return getCloseTag(node) || [NullTag, GapTag].includes(sumtree.getAt(0, node.children).type)
+      ? node
+      : undefined;
+  }
+
+  get(path, shiftIndex = null) {
+    if (shiftIndex !== null) throw new Error('bad get');
+    return NodeFacade.from(get(path, nodes.get(this)));
+  }
+
+  getChildPropertyIndex(childrenIndex) {
+    return getChildPropertyIndex(nodes.get(this), childrenIndex);
+  }
+
+  getPropertyChildrenIndex(type, name) {
+    return getPropertyChildrenIndex(nodes.get(this), type, name);
+  }
+}