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

  • 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_block

This macro implements expression block reification ‘qmacro_block’

qmacro_expr

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

qmacro_template_function

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

qmacro

This macro implements expression reification ‘qmacro’

qmacro_method

This macro implements expression reification for class methods.

qmacro_type

This macro implements type declaration reification ‘qmacro_type’

qmacro_function

This macro implements expression reification for functions.

qmacro_variable

This macro implements expression reification for variables.

qmacro_template_class

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

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: string)

Adds a rule to the template to rename a call.

Arguments:

  • self : Template

  • name : string

  • newName : string

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

10.5.3.2. renameField

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

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

Arguments:

  • self : Template

  • name : string

  • newName : string

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

10.5.3.3. renameVariable

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

Adds a rule to the template to rename a variable.

Arguments:

  • self : Template

  • name : string

  • newName : string

renameVariable(self: Template; name: string; newName: das_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: dasvector`ptr`Expression)

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

Arguments:

  • self : Template

  • name : string

  • expr : vector<Expression*>

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

10.5.4. Template application

10.5.4.1. apply_template

apply_template(rules: Template; at: LineInfo; typ: TypeDecl?; forceAt: bool = true): TypeDeclPtr

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(rules: Template; at: LineInfo; expr: Expression?; forceAt: bool = true): Expression?
apply_template(at: LineInfo; expr: Expression?&; blk: block<(var rules:Template):void>): Expression?
apply_template(at: LineInfo; typ: TypeDecl?&; blk: block<(var rules:Template):void>): TypeDeclPtr
apply_template(expr: Expression?&; blk: block<(var rules:Template):void>): Expression?

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: dasvector`ptr`Expression): ExprBlock?

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

Arguments:

  • exprs : vector<Expression*>

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

10.5.7. Block helpers

move_unquote_block(expr: Expression?&): ExprBlock?

Moves the corresponding block subexpression expression from the ExprMakeBlock.

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; blk: block<(var v:VariablePtr):void>): bool

Add global variable to the module, given name and type. priv specifies if the variable is private to the block.

Arguments:
add_global_var(mod: Module?; vname: string; vat: LineInfo; value: Expression?): bool
add_global_var(mod: Module?; vname: string; typ: TypeDeclPtr; vat: LineInfo; priv: bool): 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.

Warning

The assumption is that line info is unique for the context of the unique name generation. If it is not, additional measures must be taken to ensure uniqueness of prefix.

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(st: Structure?; flags: TypeDeclFlags): TypeDeclPtr

Implementation details for the reification. Creates a type declaration from a structure pointer.

Arguments:
add_type_ptr_ref(a: TypeDeclPtr; flags: TypeDeclFlags): TypeDeclPtr
add_type_ptr_ref(st: Enumeration?; flags: TypeDeclFlags): TypeDeclPtr
add_type_ptr_ref(anything: auto(TT); 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; baseClass: Structure?; mod: Module?): Structure?

Creates a class structure derived from baseClass. Adds __rtti, __finalize fields.

Arguments:
make_class(name: string; 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: