compile

Compiles Do source to bytecode and describes what it declares.

Usage

let source = "let x = 1 + 2"
let unit = compile "example.dol" $source
let bytecode = unit.emit()

Document nodes

A unit compiled with document: true also describes what the source declares, as a tree of Node objects reached through Unit.nodes. Most of a node's interesting text is reported as a Span rather than a string: the source is already in hand, so a span says where a name was written without copying it.

let unit = compile "example.dol" $source document: true
for id node = unit.nodes()
  echo $id $node.span

Types

Type	Description
Alias	A type alias.
Annotation	An additional highlighted region attached to a Diagnostic.
AppType	Type arguments applied to a type, such as Array[Int].
Bind	A let or other binding.
Binder	Supertype of binders: names standing for types within the function, method, or class that is their parent.
Block	Supertype of the nodes that introduce a nested body.
Break	A break. Its target is the loop broken out of.
Catch	A catch handler.
Class	A class declaration.
ConstType	A constant, such as :TARGET: or nil.
Continue	A continue. Its target is the loop continued.
Declaration	Supertype of the nodes that bind a name.
Decorator	A decorator.
Diagnostic	A compiler diagnostic.
Else	An else body.
EntryRestTypeParam	A rest parameter for arbitrary keyed entries, such as ...K: V.
ExpandTypeArg	An expansion of a pack into further arguments, such as ...T.
Field	A field declaration in a class body. Its class is its parent.
Finally	A finally body.
For	A for body.
ForElem	A comprehension for.
Function	A def at statement level.
FuncType	A function type, such as (Int, ?Int) -> Int.
If	An if or else if body.
IfElem	A comprehension if.
Import	Supertype of the nodes that bind a name to something imported.
ImportItem	An item bound from a module, as in import foo: - bar.
ImportModule	A module bound by import foo or import foo: bar.
KeyBinder	A keyed binder, such as :K.
KeyParam	A keyword parameter.
KeyRestBinder	A rest binder for keyed items only, such as **R.
KeyRestParam	A rest parameter for keyed items only, such as **rest.
KeyRestTypeParam	A rest parameter for keyed items only, such as **T.
KeyTypeArg	A keyword argument, such as name: T.
KeyTypeParam	A keyed parameter, such as name: T or (K): T.
Lambda	A do block.
Method	A def in a class body. Its class is its parent.
MixedRestBinder	A rest binder for positional and keyed items, such as ...R.
MixedRestParam	A rest parameter for positional and keyed items, such as ...rest.
MixedRestTypeParam	A rest parameter for positional and keyed items, such as ...T.
NameType	A possibly dotted name, such as Str or time.Duration.
Node	Supertype of every document node.
NodeId	An opaque handle identifying one node within a Unit.
Note	An auxiliary note attached to a Diagnostic.
OpenRestTypeParam	An unrestricted schema rest parameter, written ....
Param	Supertype of a function's parameters. The function is the parent.
Patch	A suggested source edit attached to a Diagnostic.
Pos	A position within source text. All coordinates are zero-based.
PosBinder	A positional binder, such as T.
PositionalParam	A positional parameter.
PosRestBinder	A rest binder for positional items only, such as *R.
PosRestParam	A rest parameter for positional items only, such as *rest.
PosRestTypeParam	A rest parameter for positional items only, such as *T.
PosTypeArg	A positional argument, such as T.
PosTypeParam	A positional parameter, such as T.
PreludeItem	An item bound by the prelude.
PreludeModule	A module bound by the prelude.
Reference	Supertype of the nodes that name another node.
RestBinder	Supertype of rest binders. Its subtype says which items it stands for.
RestParam	Supertype of rest parameters. Its subtype says which items it takes, and its name is nil when it is anonymous.
RestTypeParam	Supertype of rest parameters with a type. Its subtype says which items it describes.
Return	A return. Its target is the function returned from.
Root	The complete source document.
SchemaType	A schema, such as {name: Str, ?port: Int}.
SelfParam	The self parameter of a method.
Span	A region of source text.
SpecialMethod	A method implementing a protocol, such as (init) or (next). Its class is its parent.
Token	A syntactic token.
Try	A try body.
Type	A type in an annotation, return type, or superclass list.
TypeArg	Supertype of the type arguments in the [] of an AppType.
TypeExpr	Supertype of the forms a type takes.
TypeParam	Supertype of the parameters of a SchemaType or FuncType.
UnionType	A union, such as (Str | Path).
Unit	A staged compilation unit.
While	A while body.
Prelude	Imports to bind before compiled source: a module name, an array of module names, or a dictionary of module names to their bindings.
PreludeBinding	What a prelude binds a module to: an alias, an array of items, or a dictionary of items to their aliases.
TokenKind	The kind of a Token.

Prelude = (Str | Sym | Array[Str | Sym] | Dict[Str | Sym, PreludeBinding])

Imports to bind before compiled source: a module name, an array of module names, or a dictionary of module names to their bindings.

PreludeBinding = (Str | Sym | Array[Str | Sym] | Dict[Str | Sym, Str | Sym])

What a prelude binds a module to: an alias, an array of items, or a dictionary of items to their aliases.

TokenKind = (:ANNOTATION: | :BINDER: | :COMMENT: | :CONSTANT: | :DELIM: | :ESCAPE: | :FIELD: | :METHOD: | :KEY: | :MODULE_NAME: | :MODULE_ITEM: | :KEYWORD: | :LITERAL: | :NUMBER: | :OPERATOR: | :STRING_DELIM: | :TYPE: | :TYPE_KEY: | :VARIABLE: | :SIGIL:)

The kind of a Token.

Value	Meaning
:ANNOTATION:	An @ annotation marker
:BINDER:	A type binder declaration
:COMMENT:	A comment
:CONSTANT:	A non-numeric, non-string constant such as nil or false
:DELIM:	A delimiter such as (, [, etc
:ESCAPE:	An escape within a string
:FIELD:	A field, e.g. bar in foo.bar
:METHOD:	A method declaration name
:KEY:	A key such as foo:
:MODULE_NAME:	A module name
:MODULE_ITEM:	A module item
:KEYWORD:	A keyword such as while, for, do, import
:LITERAL:	A literal string, including non-escape, non-interpolated portions of quoted strings
:NUMBER:	A numeric constant
:OPERATOR:	A unary or binary operator such as + or -
:STRING_DELIM:	A string delimiter (")
:TYPE:	A name within a type expression
:TYPE_KEY:	A keyed argument within a type expression
:VARIABLE:	A variable
:SIGIL:	A sigil like $ or ...

Functions

compile path source … -> Unit

Parses and elaborates Do source into a staged compilation unit.

Parameters

Name	Type	Description
path	Str	Source path, used in debug information and diagnostics.
source	(Str | Bin)	Source code to compile.
:module?	Str	Compile in module mode under this name.
:prelude?	Prelude	Additional imports to bind before the source, in the shapes the LSP prelude settings take.
:recover?	Bool	Continue parsing after syntax errors. Defaults to false.
:document?	Bool	Build document nodes. Defaults to false.

:module

Without it the source is compiled as a script, and running the bytecode yields the value of the final expression or of an early return. In module mode, running it yields a module object holding the exported bindings, or the value of an early return.

:recover

Recovery is what lets a file be described while it is still being written, at the cost of a document that is missing whatever the compiler could not read. Check Unit.diagnostics before trusting one.

Returns

A Unit, which exposes diagnostics and, with document: true, document nodes before emission. Ordinary compiler diagnostics are reported through Unit.diagnostics rather than thrown.

Errors

Exception	Condition
TypeError	source is not Str or Bin
TypeError	module is present but not Str
ValueError	prelude is malformed

Example

# Additional prelude modules
compile "test.dol" $source
  prelude:
    - sys
    - fs

# Module with alias
compile "test.dol" $source
  prelude:
    sys: shell

# Import specific items
compile "test.dol" $source
  prelude:
    sys:
      - echo
      - exit

# Items with aliases
compile "test.dol" $source
  prelude:
    sys:
      echo: echo_alias