1  # @bablr/agast-vm
 2  
 3  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.
 4  
 5  ## API
 6  
 7  The VM responds to several instructions, but its primary API is `advance(token)`, where `token` may be a `OpenNodeTag`, `CloseNodeTag`, `Literal`, `Reference`, or `Gap`.
 8  
 9  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.
10  
11  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.
12  
13  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.
14  
15  Here are the basic types used by the VM:
16  
17  ```ts
18  type Token = OpenNodeTag | CloseNodeTag | Literal | Reference | Gap;
19  
20  type OpenNodeTag {
21    type: 'OpenNodeTag',
22    value: {
23      flags: {
24        token: boolean,
25        trivia: boolean,
26        escape: boolean
27      },
28      language: string | null,
29      type: string | null, // null type indicates a fragment
30      attributes: { [key: string]: boolean | number | string }
31    }
32  }
33  
34  type CloseNodeTag {
35    type: 'CloseNodeTag',
36    value: {
37      language: string,
38      type: string,
39    }
40  }
41  
42  type Literal {
43    value: string
44  }
45  
46  type Reference {
47    type: 'Reference',
48    value: {
49      name: string,
50      isArray: boolean
51    }
52  }
53  
54  type Gap {
55    type: 'Gap',
56    value: null,
57  }
58  ```