Unit

A staged compilation unit.

Provides diagnostics and document nodes for one source file before emitting bytecode.

Example

let unit = compile "example.dol" "pub let answer = 42\n" document: true
for id node = unit.nodes()
  echo $id $node.span
let bytecode = unit.emit()

Fields

root @ (Root | nil) ^[get]

The Root node, or nil unless the unit was compiled with document: true.

Methods

byte_range span -> Range[Int]

Returns where a span of this unit lies in its source, as a range of byte offsets, which slices the source.

Parameters

Name	Type	Description
span	Span	A span of this unit.

Errors

Raises std.StateError if the unit was emitted.

diagnostics() -> Iter[Diagnostic]

Returns a fresh iterator of diagnostics.

emit() -> Bin

Consumes the unit and returns its bytecode.

Errors

Exception	Condition
std.CompileError	Compilation failed
std.StateError	The unit, its node iterators, or its nodes are used after emission

end span -> Pos

Returns the exclusive end position of a span of this unit.

Parameters

Name	Type	Description
span	Span	A span of this unit.

Errors

Raises std.StateError if the unit was emitted.

node id -> (Node | nil)

Looks up a node by NodeId.

Parameters

Name	Type	Description
id	NodeId	The ID to look up.

Returns

nil when the ID belongs to another unit.

nodes() -> Iter[Tuple[NodeId, Node]]

Returns a fresh iterator of node IDs paired with their nodes.

Empty unless the unit was compiled with document: true. An enabled unit always contains one Root, even for empty source.

Example

for id node = unit.nodes()
  echo $id $node.span

text span -> Str

Returns the source text of a span of this unit.

Parameters

Name	Type	Description
span	Span	A span of this unit.

Errors

Raises std.StateError if the unit was emitted.

Example

for id node = unit.nodes()
  if (node.span != nil)
    echo $unit.text(node.span)

tokens() -> Iter[Token]

Returns a fresh iterator of tokens covering the whole source, in source order.

Example

for token = unit.tokens()
  echo $token.kind $token.span