_section: Abstract Syntax Tree @<asm-ast>

Parsing a file using the [Ethers ASM Dialect](asm-dialect) will
generate an Abstract Syntax Tree. The root node will always
be a [[asm-scopenode]] whose name is ``_``.

To parse a file into an Abstract Syntax tree, use the [parse](asm-parse)
function.


_subsection: Types

_heading: Location @<asm-location>

_property: offset => number
The offset into the source code to the start of this node.

_property: length => number
The length of characters in the source code to the end of this node.

_property: source => string
The source code of this node.


_subsection: Nodes

@TODO: Place a diagram here showing the hierarchy

_heading: Node @<asm-node> @SRC<asm:class.Node>

_property: node.tag => string
A unique tag for this node for the lifetime of the process.

_property: node.location => [[asm-location]]
The source code and location within the source code that this
node represents.


_heading: ValueNode @<asm-valuenode> @INHERIT<[[asm-node]]> @SRC<asm:class.ValueNode>

A **ValueNode** is a node which may manipulate the stack.


_heading: LiteralNode @<asm-literalnode> @INHERIT<[[asm-valuenode]]> @SRC<asm:class.LiteralNode>

_property: literalNode.value => string
The literal value of this node, which may be a [[DataHexString]] or
string of a decimal number.

_property: literalNode.verbatim => boolean
This is true in a [[asm-datanode]] context, since in that case the
value should be taken verbatim and no ``PUSH`` operation should be
added, otherwise false.


_heading: PopNode @<asm-popnode> @INHERIT<[[asm-valuenode]]> @SRC<asm:class.PopNode>

A **PopNode** is used to store a place-holder for an implicit pop from the
stack. It represents the code for an implicit place-holder (i.e. ``$$``) or an
explicit place-holder (e.g. ``$1``), which indicates the expected stack position
to consume.

_property: literalNode.index => number

The index this **PopNode** is representing. For an implicit place-holder
this is ``0``.


_heading: LinkNode @<asm-linknode> @INHERIT<[[asm-valuenode]]> @SRC<asm:class.LinkNode>

A **LinkNode** represents a link to another [[asm-node]]'s data,
for example ``$foo`` or ``#bar``.

_property: linkNode.label => string
The name of the target node.

_property: linkNode.type => "offset" | "length"
Whether this node is for an offset or a length value of the
target node.


_heading: OpcodeNode @<asm-opcodenode> @INHERIT<[[asm-valuenode]]> @SRC<asm:class.OpcodeNode>

_property: opcodeNode.opcode => [[asm-opcode]]
The opcode for this Node.

_property: opcodeNode.operands => Array<[[asm-valuenode]]>
A list of all operands passed into this Node.


_heading: EvaluationNode @<asm-evaluationnode> @INHERIT<[[asm-valuenode]]> @SRC<asm:class.EvaluationNode>

An **EvaluationNode** is used to execute code and insert the results
but does not generate
any output assembly, using the ``{{! code here }}`` syntax.

_property: literalNode.verbatim => boolean
This is true in a [[asm-datanode]] context, since in that case the
value should be taken verbatim and no ``PUSH`` operation should be
added, otherwise false.

_property: evaluationNode.script => string
The code to evaluate and produce the result to use as a literal.


_heading: ExecutionNode @<asm-executionnode> @INHERIT<[[asm-node]]> @SRC<asm:class.ExecutionNode>

An **ExecutionNode** is used to execute code but does not generate
any output assembly, using the ``{{! code here }}`` syntax.

_property: evaluationNode.script => string
The code to execute. Any result is ignored.


_heading: LabelledNode @<asm-labellednode> @INHERIT<[[asm-node]]> @SRC<asm:class.LabelledNode>

A **LabelledNode** is used for any Node that has a name, and can therefore
be targeted by a [[asm-linknode]].

_property: labelledNode.name => string
The name of this node.


_heading: LabelNode @<asm-labelnode> @INHERIT<[[asm-labellednode]]> @SRC<asm:class.LabelNode>

A **LabelNode** is used as a place to ``JUMP`` to by referencing it
name, using ``@myLabel:``. A ``JUMPDEST`` is automatically inserted
at the bytecode offset.


_heading: DataNode @<asm-datanode> @INHERIT<[[asm-labellednode]]> @SRC<asm:class.DataNode>

A **DataNode** allows for data to be inserted directly into the output
assembly, using ``@myData[ ... ]``. The data is padded if needed to ensure
values that would otherwise be regarded as a ``PUSH`` value does not impact
anything past the data.

_property: dataNode.data => Array<[[asm-valuenode]]>
The child nodes, which each represent a verbatim piece of data in insert.

_heading: ScopeNode @<asm-scopenode> @INHERIT<[[asm-labellednode]]> @SRC<asm:class.ScopeNode>


A **ScopeNode** allows a new frame of reference that all [[asm-linknode]]'s
will use when resolving offset locations, using ``@myScope{ ... }``.

_property: scopeNode.statements => Array<[[asm-node]]>
The list of child nodes for this scope.