The template system

LLBLGen Pro uses templates to generate the code for the different classes. Templates are stored per target framework and eventually per database if a template is database specific.

Templates are bound to templateID's and these bindings are stored in templatebindings files, stored in Templates folders inside a target framework's folder. Templatebindings files contain language specific bindings, and the languages defined are stored in language files which contain target language specific information.

Templatebindings files define template bindings which define a relationship between a template ID and a template file. Tasks should be kept language and template independent and refer to template ID's. By binding a template file to these template IDs, the task performers which use / consume templates, can load the correct template file at runtime.

Template pre-processor and includes

The TDL parser and .lpt template parser contain a pre-processor which is able to process <# templateID #> tokens. These tokens are include statements which include the template file bound to the specified templateID at the spot of the <# templateID #> include token.

Included templates can contain include statements as well, cyclic references are ignored. The pre-processor is executed prior to the execution of the including template itself and results in a complete template file with all the included templates embedded into it, which is then parsed by the parser used and executed

Below you'll find the XML formats for the .templatebindings and .language files. To edit them, drag them onto the LLBLGen Pro designer to open them in the template editor. .templatebindings files are stored in the Templates folder of a target framework and .language files are stored in the SharedTemplates folder inside the general Frameworks folder, as they're shared among all frameworks supported. You can also store them in the additional templates folder specified in the project properties.

.Language files XML format

A Language Definition contains programming / output language aspects to be used by task performers. This way, a task performer can test on these definition's aspects without having to 'cheat' by testing other aspects to determine what the target language is for a given task.

A language definition is defined in a .language file and is defined in XML. The format is below. An example is C#.language and VBNet.language. Language files are placed in the Templates folder in the LLBLGen Pro installation folder and additional Templates folders.

<language
    name=""
    fileExtension=""
    arrayIndexOperatorOpenChar=""
    arrayIndexOperatorCloseChar=""
    hasArrayIndexOperatorOnIdentifier="bool"
    lineConcatenator=""
    attributeAssignmentOperator=""
    attributePattern=""
>
    <keywords>
        <keyword name="" value=""/>
    </keywords>
</language>

Attribute descriptions

  • name. The name of the language, for example CSharp, VB.NET or SQL. This name is important, as it is referenced in other config files. There can be just 1 definition for a language. If more than one is found, the first found is kept and the rest are skipped.
  • fileExtension. the extension to use for the output files, e.g. cs or vb. This extension is used where the filenameFormat specifier [extension] is used in the filenameFormat parameter for the code generator.
  • arrayIndexOperatorOpenChar. Character to use for array indexing operator. In C# this is the [ character, in VB.NET this is the ( character.
  • arrayIndexOperatorCloseChar. Character to use for array indexing operator. In C# this is the ] character, in VB.NET this is the ) character.
  • hasArrayIndexOperatorOnIdentifier. Flag to tell a code generator task performer to emit an empty array index operator when the tag <[ArrayIndexOperator]> is found and the type is an array type. True for VB.NET, false for C#.
  • lineConcatenator. Character that is appended at a line when the emitter decides a line will be too long. Normally this tag is empty, except for VB.NET which uses the _ character as a line concatenator character.
  • attributeAssignmentOperator. This is the string which is the replacement for the macro $= in attribute definitions in the designer. Optional
  • attributePattern. This is the pattern to use to emit attribute definitions into the output. It has to have a {0} definition in the string which will be replaced with the attribute definition. Optional

Child tags descriptions

  • keywords. This is a container for keyword tags which is meant to contain keyword definitions which can be important for code generators. You can add your own if you use a specific task performer which has to know a given keyword, or use one of the predefined keyword names, which are enlisted below.

Predefined keyword names The following list are predefined keyword names used by the LLBLGen Pro system.

  • trueKeyword. The keyword to use when 'true' has to be emitted.
  • falseKeyword. The keyword to use when 'false' has to be emitted.
  • thisKeyword. The keyword to use when 'this' has to be emitted.
  • nullKeyword. The keyword to use when 'null' has to be emitted.
  • partialKeyword. The keyword to use when a partial class has to be emitted.
  • typeofKeyword. The keyword to use when a typeof() statement has to be emitted.
  • byteKeyword. The keyword to use when a byte cast statement has to be emitted.
  • int16Keyword. The keyword to use when an int16 cast statement has to be emitted.
  • int32Keyword. The keyword to use when an int32 cast statement has to be emitted.
  • int64Keyword. The keyword to use when an int64 cast statement has to be emitted.
  • singleKeyword. The keyword to use when a single/float cast statement has to be emitted.
  • doubleKeyword. The keyword to use when a double cast statement has to be emitted.
  • decimalKeyword. The keyword to use when a decimal cast statement has to be emitted.

.Templatebindings files XML format

<templateBindings 
    name="" 
    databaseDriverID="" 
    description="" 
    precedenceLevel="0"
>
    <supportedPlatforms>
        <platform name=""/>
    </supportedPlatforms>
    <supportedFrameworks>
        <framework name="target framework name"/>
        <!-- more -->
    </supportedFrameworks>
    <language name="">
        <templateBinding templateID="" filename="" templateLanguage="" includeOnly="true/false"/>
        <!-- more -->
    </language>
</templateBindings>

Attribute descriptions

  • name. Unique name of the templateBindings set. This name is used in task definitions where a special templatebindings set is required, and this name is then specified as the value of the parameter templateBindingDefinitionName.
  • databaseDriverID. Optional attribute which holds a specific database driver ID (GUID), if specified. The driverid specified is the id for the driver for which these templatebindings are meant for, like the SqlServer templateID. When omitted, the template bindings are usable with any driver.
  • description The description of the group of template bindings.
  • precedenceLevel the level to use for determining where in the precedence list this templatebindings set has to be placed. A high number will make sure the templatebindings data will take precedence over all templatebindings with lower precedence. Templatebindings with equal precedence are sorted on a first come first served rule. All normal templatebindings files have a default precedence of 10. The backwards compatibility templatebindings files have a default precedence of 1.

Child tag descriptions

  • supportedPlatforms. Container for platform tags for which the bindings in this templatebindings file are meant. All bindings are for the platforms specified. If omitted, all platforms are assumed.
  • supportedFrameworks. Optional tag. Container for framework tags which specify for which target frameworks the task is valid. If not present, all target frameworks supported by LLBLGen Pro are assumed. Child element framework has one attribute: name, which is the full name of the target framework, e.g. "LLBLGen Pro Runtime Framework".
  • language Container, for language specific templatebindings. Per language tag, multiple templateBinding tags can be specified, which each illustrate a binding for a given templateID to a file, for that specific language. A templateID can be bound to a single file and therefore is unique for the given language-platform combination, where platform is any platform in the supportedPlatforms tag. The templateBinding attribute templateLanguage is optional, and if specified, specifies the language in which the template is written. If it's omitted, the templateLanguage will be the same as the name attribute's value of the parent language tag. The attribute includeOnly is optional, and can be used to specify that the template is used as include template only. This is required for .lpt include templates, as otherwise the template will be seen as a normal template and a separate code producer class is created for the template, which likely will cause compile errors as the template isn't a full template.