10.5. Template application helpers

The TEMPLATES_BOOST module extends template utilities with high-level macros for common code generation patterns, including template function generation, type-parameterized struct creation, and compile-time code expansion.

See also decltype macro and template function annotation for decltype and [template] annotations.

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

require daslib/templates_boost

10.5.1. Structures

Template

This structure contains collection of substitution rules for a template.

Fields:

  • kaboomVar : table<string;tuple<prefix:string;suffix:string>> - variable field access replacement rules

  • call2name : table<string;string> - call name replacement rules

  • field2name : table<string;string> - field name replacement rules

  • var2name : table<string;string> - variable name replacement rules

  • var2expr : table<string; Expression?> - variable expression replacement rules (peel-aware: also strips ExprRef2Value wrappers around the target)

  • var2exprList : table<string;array< Expression?>> - variable expression list replacement rules

  • type2type : table<string;string> - type name replacement rules

  • type2etype : table<string; TypeDeclPtr> - type to type declaration replacement rules

  • struct2etype : table< Structure?; TypeDeclPtr> - structure to type declaration replacement rules

  • blockArgName : table<string;string> - block argument name replacement rules

  • annArg : table<string;lambda<(ann: AnnotationDeclaration):void>> - annotation argument replacement rules

  • blkArg : table<string;array< VariablePtr>> - block argument replacement rules

  • tag2expr : table<string; Expression?> - tag expression replacement rules

10.5.2. Call macros

qmacro_template_function

Call macro for quoting named template functions. This macro implements expression reification for the named expressions (function, variable, etc.)

qmacro_variable

This macro implements expression reification for variables.

qmacro_type

This macro implements type declaration reification ‘qmacro_type’

qmacro_function

This macro implements expression reification for functions.

qmacro

This macro implements expression reification ‘qmacro’

qmacro_template_class

Call macro for quoting named template class methods. This macro implements expression reification for the named expressions (function, variable, etc.)

qmacro_method

This macro implements expression reification for class methods.

qmacro_block

This macro implements expression block reification ‘qmacro_block’

qmacro_expr

This macro implements first line of the expression block reification ‘qmacro_expr’

qmacro_block_to_array

This macro implements expression block to array reification ‘qmacro_block_to_array’

10.5.3. Template rules

kaboomVarField(self: Template; name: string; prefix: string; suffix: string )

Adds a rule to to the template to replace a variable field access with a prefix and suffix. I.e. foo.bar into prefix + bar + suffix

Arguments:

  • self : Template

  • name : string

  • prefix : string

  • suffix : string

10.5.3.1. renameCall

renameCall(self: Template; name: string; newName: das_string )

Adds a rule to the template to rename a call.

Arguments:
renameCall(self: Template; name: string; newName: string )

10.5.3.2. renameField

renameField(self: Template; name: string; newName: das_string )

Adds a rule to the template to rename any field lookup (., ?., as, is, etc)

Arguments:
renameField(self: Template; name: string; newName: string )

10.5.3.3. renameVariable

renameVariable(self: Template; name: string; newName: das_string )

Adds a rule to the template to rename a variable.

Arguments:
renameVariable(self: Template; name: string; newName: string )
replaceAnnotationArgument(self: Template; name: string; cb: lambda<(var ann:AnnotationDeclaration):void> )

Adds a rule to the template to replace an annotation argument with the result of a callback.

Arguments:
replaceArgumentWithList(self: Template; name: string; blka: array<VariablePtr> )

Adds a rule to the template to replace a block argument with a list of variables.

Arguments:
replaceBlockArgument(self: Template; name: string; newName: string )

Adds a rule to the template to rename a block argument.

Arguments:

  • self : Template

  • name : string

  • newName : string

replaceStructWithTypeDecl(self: Template; pstruct: Structure?; expr: TypeDeclPtr )

Adds a rule to the template to replace a type alias with another type alias, specified by type declaration.

Arguments:
replaceType(self: Template; name: string; newName: string )

Adds a rule to the template to replace a type alias with another type alias, specified by name.

Arguments:

  • self : Template

  • name : string

  • newName : string

replaceTypeWithTypeDecl(self: Template; name: string; expr: TypeDeclPtr )

Adds a rule to the template to replace a type alias with another type alias, specified by type declaration.

Arguments:
replaceVarTag(self: Template; name: string; expr: Expression? )

Adds a rule to the template to replace a variable tag with an expression.

Arguments:
replaceVariable(self: Template; name: string; expr: Expression? )

Adds a rule to the template to replace a variable with an expression.

Arguments:

10.5.3.4. replaceVariableWithList

replaceVariableWithList(self: Template; name: string; expr: array<Expression?> )

Adds a rule to the template to replace a variable with an expression list.

Arguments:
replaceVariableWithList(self: Template; name: string; expr: dasvector`ptr`Expression )

10.5.4. Template application

10.5.4.1. apply_template

apply_template(at: LineInfo; expr: Expression?&; blk: block<(var rules:Template):void> ): Expression?

Applies the template to the given expression. If forceAt is set, the resulting expression will have the same line info as ‘at’.

Arguments:
apply_template(at: LineInfo; typ: TypeDecl?&; blk: block<(var rules:Template):void> ): TypeDeclPtr
apply_template(expr: Expression?&; blk: block<(var rules:Template):void> ): Expression?
apply_template(rules: Template; at: LineInfo; expr: Expression?; forceAt: bool = true ): Expression?
apply_template(rules: Template; at: LineInfo; typ: TypeDecl?; forceAt: bool = true ): TypeDeclPtr
bind_block_argument(blk: ExprBlock?; argname: string; bound: Expression?; at: LineInfo ): Expression?

Clones the body of a block literal with its argument argname replaced by the expression bound, and returns it as a plain (argument-less) block.

Arguments:
clone_and_rename_var(src: Expression?; from_name: string; to_name: string ): Expression?

Clones src and renames every ExprVar named from_name to to_name. One-shot clone_expression + renameVariable + apply_template — the common idiom for safely reusing a captured sub-expression under a fresh variable name. A null src returns null (null-in, null-out).

Arguments:

  • src : Expression?

  • from_name : string

  • to_name : string

10.5.5. Expression helpers

expression_at(expr: Expression?; at: LineInfo ): Expression?

Force expression location, then return it.

Arguments:
remove_deref(varname: string; expr: Expression? )

Removes dereferences of the variable varname from the expression. This is typically used when replacing ‘workhorse’ variable with constant.

Arguments:
visit_expression(expr: Expression?&; adapter: VisitorAdapter? )

Visits the expression with the given visitor adapter.

Arguments:

10.5.6. Expression generation

10.5.6.1. make_expression_block

make_expression_block(exprs: array<Expression?> ): ExprBlock?

Create ExprBlock and move all expressions from expr to the list of the block.

Arguments:
make_expression_block(exprs: dasvector`ptr`Expression ): ExprBlock?

10.5.7. Block helpers

move_unquote_block(expr: Expression?& ): ExprBlock?

Moves the corresponding block subexpression expression from the ExprMakeBlock.

Arguments:
push_block_list(stmts: array<Expression?>; blockExpr: Expression? )

Splice every statement from a qmacro_block(...) { ... } result into stmts, cloning each. Use in place of a cluster of stmts |> push <| qmacro_expr() { single_stmt } calls when emitting multi-statement snippets.

Arguments:
unquote_block(expr: Expression? ): ExprBlock?

Returns the corresponding block subexpression expression from the ExprMakeBlock.

Arguments:

10.5.8. Global variable helpers

add_global_let(mod: Module?; vname: string; vat: LineInfo; value: Expression? ): bool

Add global variable to the module, given name and initial value. Variable type will be constant.

Arguments:
add_global_private_let(mod: Module?; vname: string; vat: LineInfo; value: Expression? ): bool

Add global variable to the module, given name and initial value. It will be private, and type will be constant.

Arguments:
add_global_private_var(mod: Module?; vname: string; vat: LineInfo; value: Expression? ): bool

Add global variable to the module, given name and initial value. It will be private.

Arguments:

10.5.8.1. add_global_var

add_global_var(mod: Module?; vname: string; typ: TypeDeclPtr; vat: LineInfo; priv: bool ): bool

Add global variable to the module, given name and type.

Arguments:
add_global_var(mod: Module?; vname: string; typ: TypeDeclPtr; vat: LineInfo; priv: bool; blk: block<(var v:VariablePtr):void> ): bool
add_global_var(mod: Module?; vname: string; vat: LineInfo; value: Expression? ): bool

10.5.9. Hygienic names

make_unique_private_name(prefix: string; vat: LineInfo ): string

Generates unique private name for the variable, given prefix and line info.

Arguments:

10.5.10. Quoting macros

apply_qblock(expr: Expression?; blk: block<(var rules:Template):void> ): Expression?

Implementation details for the expression reification. This is a block reification.

Arguments:
apply_qblock_expr(expr: Expression?; blk: block<(var rules:Template):void> ): Expression?

Implementation details for the expression reification. This is a first line of the block as expression reification.

Arguments:
apply_qblock_to_array(expr: Expression?; blk: block<(var rules:Template):void> ): array<Expression?>

Implementation details for the expression reification. This is a block reification.

Arguments:
apply_qmacro(expr: Expression?; blk: block<(var rules:Template):void> ): Expression?

Implementation details for the expression reification.

Arguments:
apply_qmacro_function(fname: string; expr: Expression?; blk: block<(var rules:Template):void> ): FunctionPtr

Implementation details for reification. This is a function generation reification.

Arguments:
apply_qmacro_method(fname: string; parent: StructurePtr; expr: Expression?; blk: block<(var rules:Template):void> ): FunctionPtr

Implementation details for reification. This is a class method function generation reification.

Arguments:
apply_qmacro_template_class(instance_name: string; template_type: TypeDecl?; blk: block<(var rules:Template):void> ): TypeDeclPtr

Implementation details for the expression reification. This is a template class instantiation reification.

Arguments:

  • instance_name : string

  • template_type : TypeDecl?

  • blk : block<(rules: Template):void>

apply_qmacro_template_function(func: FunctionPtr; blk: block<(var rules:Template):void> ): FunctionPtr

Applies template rules to a function, cloning it with substituted types.

Arguments:
apply_qmacro_variable(vname: string; expr: Expression?; blk: block<(var rules:Template):void> ): VariablePtr

Implementation details for reification. This is a variable generation reification.

Arguments:
apply_qtype(expr: Expression?; blk: block<(var rules:Template):void> ): TypeDeclPtr

Implementation details for the expression reification. This is a type declaration reification.

Arguments:

10.5.11. Type pointer helpers

add_array_ptr_ref(a: array<smart_ptr<auto(TT)>> ): array<smart_ptr<TT>>

Implementation details for the reification. This adds any array to the rules.

Arguments:

  • a : array<smart_ptr<auto(TT)>>

10.5.11.1. add_type_ptr_ref

add_type_ptr_ref(a: TypeDeclPtr; flags: TypeDeclFlags ): TypeDeclPtr

Implementation details for the reification. Clones a type declaration and applies given flags.

Arguments:
add_type_ptr_ref(anything: auto(TT); flags: TypeDeclFlags ): TypeDeclPtr
add_type_ptr_ref(st: Enumeration?; flags: TypeDeclFlags ): TypeDeclPtr
add_type_ptr_ref(st: Structure?; flags: TypeDeclFlags ): TypeDeclPtr

10.5.12. Structure helpers

add_structure_field(cls: StructurePtr; name: string; t: TypeDeclPtr; init: Expression? ): int

Adds a field to the structure.

Arguments:

10.5.13. Class generation

enum_class_type(st: auto ): auto

return underlying type for the enumeration

Arguments:

  • st : auto

10.5.13.1. make_class

make_class(name: string; mod: Module? ): Structure?

Creates a class structure. Adds __rtti, __finalize fields.

Arguments:
make_class(name: string; baseClass: Structure?; mod: Module? ): Structure?
make_class_constructor(cls: StructurePtr; ctor: FunctionPtr ): Function?

Adds a class constructor from a constructor function.

Arguments:
modify_to_class_member(cls: StructurePtr; fun: FunctionPtr; isExplicit: bool; Constant: bool )

Modifies function to be a member of a particular class.

Arguments: