10.3. Boost package for the AST

The AST_BOOST module provides high-level utilities for working with the AST. It includes helpers for creating expressions, types, and declarations, quote-based AST construction, and common AST query and transformation patterns used by macro authors.

All functions and symbols are in “ast_boost” module, use require to get access to it.

require daslib/ast_boost

10.3.1. Type aliases

AnnotationDeclarationPtr = AnnotationDeclaration?

Type alias for AnnotationDeclaration?, used when constructing or attaching annotation declarations to functions, blocks, or structures.

bitfield DebugExpressionFlags

Bitfield controlling debug_expression output formatting.

Fields:

  • refCount (0x1) - refCount — include smart pointer reference counts in the dump.

  • lineInfo (0x2) - lineInfo — include source file and line:column spans on each AST node. For call expressions, also shows atEnclosure when set.

10.3.2. Function annotations

macro

The [macro] function annotation — marks a function to run only during macro module compilation, gating its body behind is_compiling_macros.

tag_function

The [tag_function] function annotation — attaches named tags to a function so that [tag_function_macro]-based annotations can discover and process it.

10.3.3. Variant macros

better_rtti_in_expr

Variant macro that enables improved RTTI type matching in is and as expressions. Varian macro better_rtti_in_expr

10.3.4. Structure macros

variant_macro

The [variant_macro] structure annotation — registers an AstVariantMacro subclass as a named macro that can customize is, as, and ?as variant operations.

global_lint_macro

The [global_lint_macro] structure annotation — registers an AstPassMacro subclass that is invoked during the global lint compilation pass.

contract

The [contract] structure annotation — registers an AstFunctionAnnotation subclass as a named function contract that validates arguments or return values.

tag_structure

The [tag_structure] structure annotation — attaches named boolean tags to a structure, allowing macro code to discover and process tagged structures.

infer_macro

The [infer_macro] structure annotation — registers an AstPassMacro subclass that is invoked during the type inference compilation pass.

call_macro

The [call_macro] structure annotation — registers an AstCallMacro subclass as a named call-expression macro available during compilation.

tag_function_macro

The [tag_function_macro] structure annotation — registers an AstFunctionAnnotation that is automatically applied to every function carrying a matching [tag_function(tag)] tag.

lint_macro

The [lint_macro] structure annotation — registers an AstPassMacro subclass that is invoked during the lint compilation pass.

enumeration_macro

The [enumeration_macro] structure annotation — registers an AstEnumerationAnnotation subclass as a named annotation applicable to enumerations.

dirty_infer_macro

The [dirty_infer_macro] structure annotation — registers an AstPassMacro subclass that is invoked during the dirty infer compilation pass.

reader_macro

The [reader_macro] structure annotation — registers an AstReaderMacro subclass as a named reader macro invoked by the %name~...~~ syntax during parsing.

comment_reader

The [comment_reader] structure annotation — registers an AstCommentReader subclass as a named comment reader invoked during parsing.

capture_macro

The [capture_macro] structure annotation — registers an AstCaptureMacro subclass as a named capture macro that can customize lambda capture behavior.

type_macro

The [type_macro] structure annotation — registers an AstTypeMacro subclass as a named macro that can intercept and transform type expressions.

block_macro

The [block_macro] structure annotation — registers an AstBlockAnnotation subclass as a named block-level annotation available to the compiler.

function_macro

The [function_macro] structure annotation — registers an AstFunctionAnnotation subclass as a named function annotation available to the compiler.

optimization_macro

The [optimization_macro] structure annotation — registers an AstPassMacro subclass that is invoked during the optimization compilation pass.

simulate_macro

The [simulate_macro] structure annotation — registers an AstSimulateMacro subclass as a named macro invoked during the simulation (code generation) phase.

for_loop_macro

The [for_loop_macro] structure annotation — registers an AstForLoopMacro subclass as a named macro that can transform for loop expressions.

structure_macro

The [structure_macro] structure annotation — registers an AstStructureAnnotation subclass as a named annotation applicable to structures and classes.

typeinfo_macro

The [typeinfo_macro] structure annotation — registers an AstTypeInfoMacro subclass as a named macro that extends the typeinfo name(...) built-in.

10.3.5. Classes

MacroMacro : AstFunctionAnnotation

Implements the [macro] function annotation, which wraps the function body so it only executes during macro module compilation.

MacroMacro.apply(func: FunctionPtr; group: ModuleGroup; args: AnnotationArgumentList; errors: das_string): bool

Wraps the annotated function body in an is_compiling_macros guard and sets macroInit flag so it only runs during macro module compilation.

Arguments:
TagFunctionAnnotation : AstFunctionAnnotation

Implements the [tag_function] function annotation, which attaches named boolean tags to functions so they can be discovered and processed by [tag_function_macro].

TagFunctionAnnotation.apply(func: FunctionPtr; group: ModuleGroup; args: AnnotationArgumentList; errors: das_string): bool

Validates that all [tag_function(...)] annotation arguments are tag names (boolean flags) and rejects any non-boolean arguments with an error.

Arguments:
TagStructureAnnotation : AstStructureAnnotation

Implements the [tag_structure] structure annotation, which attaches named boolean tags to structures for later discovery by macro code.

TagStructureAnnotation.apply(str: StructurePtr; group: ModuleGroup; args: AnnotationArgumentList; errors: das_string): bool

Validates that all [tag_structure(...)] annotation arguments are tag names (boolean flags) and rejects any non-boolean arguments with an error.

Arguments:
SetupAnyAnnotation : AstStructureAnnotation

This is base class for any annotation or macro setup.

Fields:

  • annotation_function_call : string = “” - Function call name, which is used to setup any annotation.

  • name : string - Name of the annotation to setup.

SetupAnyAnnotation.apply(st: StructurePtr; group: ModuleGroup; args: AnnotationArgumentList; errors: das_string): bool

Generates a macro-init function that constructs an instance of the annotated class and registers it with the compiler under the specified name.

Arguments:
SetupAnyAnnotation.setup_call(st: StructurePtr; cll: ExprCall?)

Populates the registration call arguments — by default adds the annotation name as a string constant; overridden in subclasses to add extra parameters.

Arguments:
SetupFunctionAnnotation : SetupAnyAnnotation
Fields:

  • annotation_function_call : string = “add_new_function_annotation” - Base class for creating function annotations via the [function_macro] structure annotation; registers an AstFunctionAnnotation with the compiler.

SetupBlockAnnotation : SetupAnyAnnotation
Fields:

  • annotation_function_call : string = “add_new_block_annotation” - Base class for creating block annotations via the [block_macro] structure annotation; registers an AstBlockAnnotation with the compiler.

SetupStructureAnnotation : SetupAnyAnnotation
Fields:

  • annotation_function_call : string = “add_new_structure_annotation” - Base class for creating structure annotations via the [structure_macro] structure annotation; registers an AstStructureAnnotation with the compiler.

SetupEnumerationAnnotation : SetupAnyAnnotation
Fields:

  • annotation_function_call : string = “add_new_enumeration_annotation” - Base class for creating enumeration annotations via the [enumeration_macro] structure annotation; registers an AstEnumerationAnnotation with the compiler.

SetupContractAnnotation : SetupAnyAnnotation
Fields:

  • annotation_function_call : string = “add_new_contract_annotation” - Base class for creating function contract annotations via the [contract] structure annotation; registers an AstFunctionAnnotation as a contract.

SetupReaderMacro : SetupAnyAnnotation
Fields:

  • annotation_function_call : string = “add_new_reader_macro” - Base class for creating reader macros via the [reader_macro] structure annotation; registers an AstReaderMacro with the compiler.

SetupCommentReader : SetupAnyAnnotation
Fields:

  • annotation_function_call : string = “add_new_comment_reader” - Base class for creating comment readers via the [comment_reader] structure annotation; registers an AstCommentReader with the compiler.

SetupVariantMacro : SetupAnyAnnotation
Fields:

  • annotation_function_call : string = “add_new_variant_macro” - Base class for creating variant macros via the [variant_macro] structure annotation; registers an AstVariantMacro with the compiler.

SetupForLoopMacro : SetupAnyAnnotation
Fields:

  • annotation_function_call : string = “add_new_for_loop_macro” - Base class for creating for-loop macros via the [for_loop_macro] structure annotation; registers an AstForLoopMacro with the compiler.

SetupCaptureMacro : SetupAnyAnnotation
Fields:

  • annotation_function_call : string = “add_new_capture_macro” - Base class for creating capture macros via the [capture_macro] structure annotation; registers an AstCaptureMacro with the compiler.

SetupTypeMacro : SetupAnyAnnotation
Fields:

  • annotation_function_call : string = “add_new_type_macro” - Base class for creating type macros via the [type_macro] structure annotation; registers an AstTypeMacro with the compiler.

SetupSimulateMacro : SetupAnyAnnotation
Fields:

  • annotation_function_call : string = “add_new_simulate_macro” - Base class for creating simulate macros via the [simulate_macro] structure annotation; registers an AstSimulateMacro with the compiler.

SetupCallMacro : SetupAnyAnnotation
Fields:

  • annotation_function_call : string = “add_new_call_macro” - Base class for creating call macros via the [call_macro] structure annotation; registers an AstCallMacro with the compiler.

SetupTypeInfoMacro : SetupAnyAnnotation
Fields:

  • annotation_function_call : string = “add_new_typeinfo_macro” - Base class for creating typeinfo macros via the [typeinfo_macro] structure annotation; registers an AstTypeInfoMacro with the compiler.

SetupInferMacro : SetupAnyAnnotation
Fields:

  • annotation_function_call : string = “add_new_infer_macro” - Base class for creating infer pass macros via the [infer_macro] structure annotation; registers an AstPassMacro that runs during the type inference pass.

SetupDirtyInferMacro : SetupAnyAnnotation
Fields:

  • annotation_function_call : string = “add_new_dirty_infer_macro” - Base class for creating dirty-infer pass macros via the [dirty_infer_macro] structure annotation; registers an AstPassMacro that runs during the dirty infer pass.

SetupLintMacro : SetupAnyAnnotation
Fields:

  • annotation_function_call : string = “add_new_lint_macro” - Base class for creating lint pass macros via the [lint_macro] structure annotation; registers an AstPassMacro that runs during the lint pass.

SetupGlobalLintMacro : SetupAnyAnnotation
Fields:

  • annotation_function_call : string = “add_new_global_lint_macro” - Base class for creating global lint pass macros via the [global_lint_macro] structure annotation; registers an AstPassMacro that runs during the global lint pass.

SetupOptimizationMacro : SetupAnyAnnotation
Fields:

  • annotation_function_call : string = “add_new_optimization_macro” - Base class for creating optimization pass macros via the [optimization_macro] structure annotation; registers an AstPassMacro that runs during the optimization pass.

TagFunctionMacro : SetupAnyAnnotation

[tag_function_macro] implementation.

Fields:

  • annotation_function_call : string = “setup_tag_annotation” - Name of the function call, which setups up the annotation.

  • tag : string - Name of the tag.

TagFunctionMacro.apply(st: StructurePtr; group: ModuleGroup; args: AnnotationArgumentList; errors: das_string): bool

Extends SetupAnyAnnotation apply to extract the required tag argument and register a setup_tag_annotation call that links the annotation to tagged functions.

Arguments:
TagFunctionMacro.setup_call(st: StructurePtr; cll: ExprCall?)

Overrides the default setup_call to pass both the annotation name and the tag string as arguments to setup_tag_annotation.

Arguments:
BetterRttiVisitor : AstVariantMacro

An AstVariantMacro that replaces is, as, and ?as variant operations on Expression subclasses with runtime __rtti string checks and casts.

BetterRttiVisitor.visitExprIsVariant(prog: ProgramPtr; mod: Module?; expr: ExprIsVariant?): ExpressionPtr

Visitor override that replaces expr is Type on Expression subclasses with an __rtti string comparison, returning true if the runtime type matches.

Arguments:
BetterRttiVisitor.visitExprAsVariant(prog: ProgramPtr; mod: Module?; expr: ExprAsVariant?): ExpressionPtr

Visitor override that replaces expr as Type on Expression subclasses with an RTTI-checked cast via __rtti, panicking on mismatch.

Arguments:
BetterRttiVisitor.visitExprSafeAsVariant(prog: ProgramPtr; mod: Module?; expr: ExprSafeAsVariant?): ExpressionPtr

Visitor override that replaces expr ?as Type on Expression subclasses with an RTTI-checked cast via __rtti, returning null on mismatch instead of panicking.

Arguments:

10.3.6. Containers

10.3.6.1. emplace_new

emplace_new(vec: VectorTypeDeclPtr; ptr: TypeDecl?)

Moves a newly created pointer (Expression, TypeDecl, Variable, or MakeFieldDecl) into a vector container.

Arguments:
emplace_new(vec: dasvector`ptr`Expression; ptr: Expression?)
emplace_new(vec: array<VariablePtr>; ptr: Variable?)
emplace_new(vec: dasvector`ptr`Variable; ptr: Variable?)
emplace_new(vec: MakeStruct; ptr: MakeFieldDecl?)

10.3.7. Textual descriptions of the objects

debug_expression(expr: Expression?; deFlags: DebugExpressionFlags = bitfield(0x0)): string

Returns a hierarchical, Lisp-like textual dump of an ExpressionPtr tree showing RTTI types, field values, and nested sub-expressions for debugging.

Arguments:

10.3.7.1. describe

describe(ann: AnnotationDeclaration): string

Returns a human-readable textual representation of an AST object (AnnotationArgumentList, AnnotationDeclaration, AnnotationList, Variable, or Expression).

Arguments:
describe(vvar: VariablePtr): string
describe(list: AnnotationArgumentList): string
describe(list: AnnotationList): string
describe_bitfield(bf: auto; merger: string = ""): auto

Returns a textual representation of the set bits in a bitfield value, listing the names of all active flags joined by the specified merger string.

Arguments:

  • bf : auto

  • merger : string

describe_function_short(func: FunctionPtr): string

Returns a short human-readable description of the given function, including its name and signature.

Arguments:

10.3.8. Queries

find_annotation(mod_name: string; ann_name: string): Annotation const?

Looks up an Annotation by name within the specified module during compilation and returns a pointer to it, or null if not found.

Arguments:

  • mod_name : string

  • ann_name : string

10.3.8.1. find_arg

find_arg(args: AnnotationArgumentList; argn: string): RttiValue

Searches an AnnotationArgumentList for an argument by name and returns its RttiValue; returns nothing if the argument is not present.

Arguments:
find_arg(argn: string; args: AnnotationArgumentList): RttiValue
find_argument_index(typ: TypeDeclPtr; name: string): int

Searches the argNames of a TypeDeclPtr (tuple or variant) for the given name and returns its zero-based index, or -1 if not found.

Arguments:
find_unique_function(mod: Module?; name: string; canfail: bool = false): Function?

Searches the compiling program for exactly one non-generic function with the given name; returns it or null if zero or multiple matches exist.

Arguments:

  • mod : Module?

  • name : string

  • canfail : bool

find_unique_generic(mod: Module?; name: string; canfail: bool = false): Function?

Searches the compiling program for exactly one generic function with the given name; returns it or null if zero or multiple matches exist.

Arguments:

  • mod : Module?

  • name : string

  • canfail : bool

getVectorElementCount(bt: Type): int

Returns the number of scalar elements in a vector Type (e.g., 2 for float2/range, 3 for float3, 4 for float4), or 0 for non-vector types.

Arguments:
getVectorElementSize(bt: Type): int

Returns the byte size of a single scalar element in a vector Type — 8 for range64/urange64, 4 for all other vector types.

Arguments:
getVectorElementType(bt: Type): Type

Returns the scalar Type of each element in a vector type (e.g., tFloat for float2, tInt for int3 and range, tInt64 for range64).

Arguments:
getVectorOffset(bt: Type; ident: string): int

Returns the zero-based element index for a named swizzle component (x/y/z/w or r/g/b/a) within a vector Type, or -1 if out of bounds.

Arguments:

  • bt : Type

  • ident : string

10.3.8.2. get_for_source_index

get_for_source_index(expr: ExprFor?; svar: VariablePtr): int

Returns the zero-based index of a given iterator variable or source expression within a for loop’s source list, or -1 if not found.

Arguments:
get_for_source_index(expr: ExprFor?; source: Expression?): int
get_workhorse_types(): Type[34]

Returns a fixed array of all commonly used Type values — booleans, strings, pointers, numeric scalars, enumerations, bitfields, vectors, and ranges.

isCMRES(fun: FunctionPtr): bool

Returns true if the given function uses copy-on-return elimination (CMRES), meaning its return value is constructed directly in the caller’s memory rather than being copied.

Arguments:
isCMRESType(blockT: TypeDeclPtr): bool

Returns true if a TypeDeclPtr represents a reference type without an explicit ref flag, meaning it will use copy-or-move-on-stack semantics.

Arguments:
isExprCallFunc(expr: Expression?): bool

Returns true if the expression’s RTTI tag is ExprCallFunc, ExprOp, ExprNew, or ExprCall — i.e., any function-call-like expression.

Arguments:
isExpression(t: TypeDeclPtr; top: bool = true): bool

Returns true if the given TypeDeclPtr refers to an ast module handled type whose name starts with Expr, including pointer-to-expression types.

Arguments:
isMakeLocal(expr: Expression?): bool

Returns true if the expression is any ExprMakeLocal subclass: ExprMakeStruct, ExprMakeArray, ExprMakeTuple, or ExprMakeVariant.

Arguments:
isVectorType(typ: Type): bool

Returns true if the given Type is a vector, range, or urange type (int2..``int4``, uint2..``uint4``, float2..``float4``, range, urange, range64, urange64).

Arguments:
is_class_method(cinfo: StructurePtr; finfo: TypeDeclPtr): bool

Returns true if a TypeDeclPtr field represents a class method — a non-dim tFunction whose first argument is the class structure (or a parent of it).

Arguments:
is_same_or_inherited(parent: Structure const?; child: Structure const?): bool

Returns true if child is the same Structure as parent or is transitively inherited from parent by walking the parent chain.

Arguments:

10.3.9. Annotations

10.3.9.1. add_annotation_argument

add_annotation_argument(arguments: AnnotationArgumentList; argName: string; val: string): int

Adds a typed annotation argument (bool, int, float, string, or AnnotationArgument) to an AnnotationArgumentList and returns the new argument index.

Arguments:
add_annotation_argument(arguments: AnnotationArgumentList; argName: string; val: bool): int
add_annotation_argument(arguments: AnnotationArgumentList; argName: string; val: int): int
add_annotation_argument(arguments: AnnotationArgumentList; ann: AnnotationArgument): int
add_annotation_argument(arguments: AnnotationArgumentList; argName: string; val: float): int

10.3.9.2. append_annotation

append_annotation(blk: ExprBlock?; mod_name: string; ann_name: string; args: array<tuple<argname:string;argvalue:variant<tBool:bool;tInt:int;tUInt:uint;tInt64:int64;tUInt64:uint64;tFloat:float;tDouble:double;tString:string;nothing:any>>>)

Creates an AnnotationDeclaration for the named annotation (with optional typed arguments) and attaches it to a Function, ExprBlock, or Structure.

Arguments:

  • blk : ExprBlock?

  • mod_name : string

  • ann_name : string

  • args : array<tuple<argname:string;argvalue: RttiValue>>

append_annotation(func: FunctionPtr; mod_name: string; ann_name: string; args: array<tuple<argname:string;argvalue:variant<tBool:bool;tInt:int;tUInt:uint;tInt64:int64;tUInt64:uint64;tFloat:float;tDouble:double;tString:string;nothing:any>>>)
append_annotation(st: Structure?; mod_name: string; ann_name: string; args: array<tuple<argname:string;argvalue:variant<tBool:bool;tInt:int;tUInt:uint;tInt64:int64;tUInt64:uint64;tFloat:float;tDouble:double;tString:string;nothing:any>>>)
append_annotation(blk: ExprBlock?; mod_name: string; ann_name: string)
append_annotation(mod_name: string; ann_name: string): AnnotationDeclaration?
append_annotation(mod_name: string; ann_name: string; args: array<tuple<argname:string;argvalue:variant<tBool:bool;tInt:int;tUInt:uint;tInt64:int64;tUInt64:uint64;tFloat:float;tDouble:double;tString:string;nothing:any>>>): AnnotationDeclaration?
append_annotation(func: FunctionPtr; mod_name: string; ann_name: string)
append_annotation(st: Structure?; mod_name: string; ann_name: string)

10.3.10. Expression generation

10.3.10.1. convert_to_expression

convert_to_expression(value: auto ==const): auto

Converts a runtime value of any supported type to an equivalent AST ExpressionPtr that would produce that value when compiled, using typeinfo for reflection.

Arguments:

  • value : auto!

convert_to_expression(value: auto ==const; at: LineInfo): auto
convert_to_expression(value: auto& ==const; at: LineInfo): auto
convert_to_expression(value: auto ==const): auto
make_static_assert_false(text: string; at: LineInfo): ExprStaticAssert?

Creates an ExprStaticAssert expression node that always fails at compile time with the given error message text.

Arguments:
override_method(str: StructurePtr; name: string; funcName: string): bool

Replaces the initializer of a field named name in the given structure with an @@funcName function address cast, effectively overriding that class method.

Arguments:
panic_expr_as(): void?

Helper function that panics with "invalid 'as' expression or null pointer dereference" and returns null — used as the failure branch in as variant casts.

10.3.11. Type generation

function_to_type(fn: FunctionPtr): TypeDeclPtr

Constructs a TypeDeclPtr of tFunction base type from a FunctionPtr, capturing its argument types and names plus the return type.

Arguments:

10.3.12. Type casts

operator as BuiltInFunction(foo: Function?): BuiltInFunction?

Casts a Function? to BuiltInFunction? via reinterpret, verifying the target is a built-in function first (panics otherwise).

Arguments:
operator as ExternalFnBase(foo: Function?): ExternalFnBase?

Casts a Function? to ExternalFnBase? via reinterpret, verifying it is a property-flagged built-in function first (panics otherwise).

Arguments:
operator as FunctionAnnotation(foo: Annotation?): FunctionAnnotation?

Casts an Annotation? to FunctionAnnotation? via reinterpret, verifying the annotation kind first (panics otherwise).

Arguments:
operator as StructureAnnotation(foo: Annotation?): StructureAnnotation?

Casts an Annotation? to StructureAnnotation? via reinterpret, verifying the annotation kind first (panics otherwise).

Arguments:

10.3.12.1. operator is BuiltInFunction

operator is BuiltInFunction(foo: Function?): bool

Returns true if the given Function? has the builtIn flag set, indicating it is a BuiltInFunction; returns false for any other type.

Arguments:
operator is BuiltInFunction(anything: auto): auto

10.3.12.2. operator is ExternalFnBase

operator is ExternalFnBase(anything: auto): auto

Returns true if the given Function? is both builtIn and has the propertyFunction flag, indicating it is an ExternalFnBase; returns false otherwise.

Arguments:

  • anything : auto

operator is ExternalFnBase(foo: Function?): bool

10.3.12.3. operator is FunctionAnnotation

operator is FunctionAnnotation(anything: auto): auto

Returns true if the given Annotation? is a FunctionAnnotation according to its isFunctionAnnotation property.

Arguments:

  • anything : auto

operator is FunctionAnnotation(foo: Annotation?): bool

10.3.12.4. operator is StructureAnnotation

operator is StructureAnnotation(anything: auto): auto

Returns true if the given Annotation? is a StructureAnnotation according to its isStructureAnnotation property.

Arguments:

  • anything : auto

operator is StructureAnnotation(foo: Annotation?): bool
walk_and_convert(data: uint8 const?; info: TypeDeclPtr; at: LineInfo): Expression?

Recursively walks raw data bytes using a TypeDeclPtr schema and builds an equivalent AST expression tree that would reproduce that data when compiled.

Arguments:

10.3.13. Setup

10.3.13.1. setup_call_list

setup_call_list(name: string; at: LineInfo; isInit: bool = false; isPrivate: bool = true; isLateInit: bool = false): ExprBlock?

Creates or locates a compilation-phase setup function (__setup_macros) and returns its body ExprBlock so callers can append registration calls to it.

Arguments:

  • name : string

  • at : LineInfo

  • isInit : bool

  • isPrivate : bool

  • isLateInit : bool

setup_call_list(name: string; at: LineInfo; subblock: block<(var fn:FunctionPtr):void>): ExprBlock?
setup_macro(name: string; at: LineInfo): ExprBlock?

Creates or locates a macro initialization function (__setup_macros) guarded by is_compiling_macros and returns its body block for appending macro registration code.

Arguments:
setup_tag_annotation(name: string; tag: string; classPtr: auto): auto

Creates an AstFunctionAnnotation instance and automatically applies it to every function that carries a matching [tag_function(tag)] annotation in the module.

Arguments:

  • name : string

  • tag : string

  • classPtr : auto