template_engine

Description:

template engine

template_engine #
A flexible Dart library to parse templates and render output such as:

Html
Programming code
Markdown
Xml, Json, Yaml
Etc...

Features #

Template expressions that can contain (combinations of):

Data types
Constants
Variables
Operators
Functions


Functions to import:

Pure files (to be imported as is)
Template files (to be parsed and rendered)
XML files (to be used as a data source)
JSON files (to be used as a data source)
YAML files (to be used as a data source)


All of the above can be customized or you could add your own.

Getting started #
See: Installing
Examples #
import 'package:shouldly/shouldly.dart';
import 'package:template_engine/template_engine.dart';

Future<void> main() async {
var engine = TemplateEngine();
var parseResult = await engine.parseText('Hello {{name}}.');
var renderResult = await engine.render(parseResult, {'name': 'world'});
renderResult.text.should.be('Hello world.');
}

copied to clipboard
Note the documentation of the template_engine package was generated by itself.
See: tool/generate_documentation.dart
For more see: Examples
Tags #
Tags are specific texts in templates that are replaced by the
TemplateEngine with other information.
A tag:

Starts with some bracket and/or character combination, e.g.: {{
Followed by some contents
Ends with some closing bracket and/or character combination, e.g.: }}

A tag example: {{customer.name}}
By default the TemplateEngine tags start with {{ and end with }} brackets,
just like the popular template engines Mustache
and Handlebars.
You can also define alternative tag brackets in the TemplateEngine constructor
parameters. See TemplateEngine.tagStart and TemplateEngine.tagEnd.
It is recommended to use a start and end combination that is not used
elsewhere in your templates, e.g.: Do not use < > as tag start and end
if your template contains HTML or XML.
The TemplateEngine comes with default tags. You can replace or add your
own tags by manipulating the the TemplateEngine.tags field.

ExpressionTag
description:Evaluates an expression that can contain:* Data Types (e.g. boolean, number or String)* Constants (e.g. pi)* Variables (e.g. person.name )* Operators (e.g. + - * /)* Functions (e.g. cos(7) )* or any combination of the above
expression example:The volume of a sphere = {{ round( (3/4) * pi * (radius ^ 3) )}}.
code example:tag_expression_parser_test.dart

Data types in tag expressions #
A data type defines what the
possible values an expression, such as a variable, operator
or a function call, might take.
The TemplateEngine supports several default DataTypes.
Custom DataTypes #
You can adopt existing DataTypes or add your own custom DataTypes by
manipulating the TemplateEngine.dataTypes field.
See Example.
Available DataTypes #

String
description:A form of data containing a sequence of characters
syntax:A string is declared with a chain of characters, surrounded by two single (') or double (") quotes to indicate the start and end of a string. In example: 'Hello' or "Hello"
example:string_test.dart


Number
description:A form of data to express the size of something.
syntax:A number is declared with:* optional: positive (e.g. +12) or negative (e.g. -12) prefix or no prefix (12=positive)* one or more digits (e.g. 12)* optional fragments (e.g. 0.12)* optional: scientific notation: the letter E is used to mean"10 to the power of." (e.g. 1.314E+1 means 1.314 * 10^1which is 13.14).
example:num_test.dart


Boolean
description:A form of data with only two possible values: true or false
syntax:A boolean is declared with the word true or false. The letters are case insensitive.
example:bool_test.dart

Constants in tag expressions #
A Constant is a value that does not change value over time.
The TemplateEngine comes with several mathematical constants.
Custom Constants #
You can create and add your own Constants by
manipulating the TemplateEngine.constants field.
See Example.
Available Constants #

e
description:Base of the natural logarithms.
return type:double
code example:e_test.dart


ln10
description:Natural logarithm of 10.
return type:double
code example:ln10_test.dart


ln2
description:Natural logarithm of 2.
return type:double
code example:ln2_test.dart


log10e
description:Base-10 logarithm of e.
return type:double
code example:log10e_test.dart


log2e
description:Base-2 logarithm of e.
return type:double
code example:log2e_test.dart


pi
description:The ratio of a circle's circumference to its diameter
return type:double
code example:pi_test.dart

Variables in tag expressions #
A Variable is
a named container for some type of information
(like number, boolean, String etc...)

Variables are stored as key, value pairs in a dart Map<String, Object> where:

String=Variable name
Object=Variable value


Variables can be used in a tag expression
Initial variable values are passed to the TemplateEngine.render method
Variables can be modified during rendering

The variable name:

must be unique and does not match a other [Tag] syntax
must start with a letter, optionally followed by letters and or digits
is case sensitive (convention: use camelCase)

Variables can be nested. Concatenate variable names separated with dot's
to get the variable value of a nested variable.
E.g.:
Variable map: {'person': {'name': 'John Doe', 'age',30}}
Variable Name person.name: refers to the variable value of 'John Doe'
Examples:

Variable Example
Nested Variable Example

Functions in tag expressions #
A function is a piece of dart code that performs a specific task.
So a function can basically do anything that dart code can do.
A function can be used anywhere in an tag expression
wherever that particular task should be performed.
The TemplateEngine supports several default functions.
Custom Functions #
You can adopt existing functions or add your own custom functions by
manipulating the TemplateEngine.functionGroups field.
See Example.
Available Functions #
Math Functions #

exp
description:Returns the natural exponent e, to the power of the value
return type:number
expression example:{{exp(7)}} should render: 1096.6331584284585
code example:exp_test.dart
parameter:valuenumbermandatory


log
description:Returns the natural logarithm of the value
return type:number
expression example:{{log(7)}} should render: 1.9459101490553132
code example:log_test.dart
parameter:valuenumbermandatory


sin
description:Returns the sine of the radians
return type:number
expression example:{{sin(7)}} should render: 0.6569865987187891
code example:sin_test.dart
parameter:radiansnumbermandatory


asin
description:Returns the values arc sine in radians
return type:number
expression example:{{asin(0.5)}} should render: 0.5235987755982989
code example:asin_test.dart
parameter:valuenumbermandatory


cos
description:Returns the cosine of the radians
return type:number
expression example:{{cos(7)}} should render: 0.7539022543433046
code example:cos_test.dart
parameter:radiansnumbermandatory


acos
description:Returns the values arc cosine in radians
return type:number
expression example:{{acos(0.5)}} should render: 1.0471975511965979
code example:acos_test.dart
parameter:valuenumbermandatory


tan
description:Returns the the tangent of the radians
return type:number
expression example:{{tan(7)}} should render: 0.8714479827243188
code example:tan_test.dart
parameter:radiansnumbermandatory


atan
description:Returns the values arc tangent in radians
return type:number
expression example:{{atan(0.5)}} should render: 0.4636476090008061
code example:atan_test.dart
parameter:valuenumbermandatory


sqrt
description:Returns the positive square root of the value.
return type:number
expression example:{{sqrt(9)}} should render: 3.0
code example:sqrt_test.dart
parameter:valuenumbermandatory


round
description:Returns the a rounded number.
return type:number
expression example:{{round(4.445)}} should render: 4
code example:round_test.dart
parameter:valuenumbermandatory

String Functions #

length
description:Returns the length of a string
return type:number
expression example:{{length("Hello")}} should render: 5
code example:length_test.dart
parameter:stringStringmandatory

Documentation Functions #

tagDocumentation
description:Generates markdown documentation of all the tags within a TemplateEngine
return type:String
expression example:{{ tagDocumentation() }}
parameter:titleLevelnumberoptional (default=1)The level of the tag title


dataTypeDocumentation
description:Generates markdown documentation of all the data types that can be used within a ExpressionTag of a TemplateEngine
return type:String
expression example:{{ dataTypeDocumentation() }}
parameter:titleLevelnumberoptional (default=1)The level of the tag title


constantDocumentation
description:Generates markdown documentation of all the constants that can be used within a ExpressionTag of a TemplateEngine
return type:String
expression example:{{ constantDocumentation() }}
parameter:titleLevelnumberoptional (default=1)The level of the tag title


functionDocumentation
description:Generates markdown documentation of all the functions that can be used within a ExpressionTag of a TemplateEngine
return type:String
expression example:{{ functionDocumentation() }}
parameter:titleLevelnumberoptional (default=1)The level of the tag title


operatorDocumentation
description:Generates markdown documentation of all the operators that can be used within a ExpressionTag of a TemplateEngine
return type:String
expression example:{{ operatorDocumentation() }}
parameter:titleLevelnumberoptional (default=1)The level of the tag title


exampleDocumentation
description:Generates markdown documentation of all the examples. This could be used to generate example.md file.
return type:String
expression example:{{ exampleDocumentation() }}
parameter:titleLevelnumberoptional (default=1)The level of the tag title

Template Functions #

templateSource
description:Gives the relative path of the current template
return type:String
expression example:{{templateSource()}}
code example:template_test.dart

Import Functions #

importTemplate
description:Imports, parses and renders a template file
return type:IntermediateRenderResult
expression example:{{importTemplate('doc/template/common/generated_comment.template')}}
code example:import_template_test.dart
parameter:sourceStringmandatoryThe project path of the template file


importPure
description:Imports a file as is (without parsing and rendering)
return type:String
expression example:{{importPure('test/src/template_engine_template_example_test.dart')}}
code example:import_pure_test.dart
parameter:sourceStringmandatoryThe project path of the file. This path can be a absolute or relative file path or URI.


importJson
description:Imports a JSON file and decode it to a Map
return type:Map
expression example:{{json=importJson('test/src/parser/tag/expression/function/import/person.json')}}{{json.person.child.name}}
code example:import_json_test.dart
parameter:sourceStringmandatoryThe project path of the JSON file. This path can be a absolute or relative file path or URI.


importXml
description:Imports a XML file and decode it to a Map
return type:Map
expression example:{{xml=importXml('test/src/parser/tag/expression/function/import/person.xml')}}{{xml.person.child.name}}
code example:import_xml_test.dart
parameter:sourceStringmandatoryThe project path of the XML file. This path can be a absolute or relative file path or URI.


importYaml
description:Imports a YAML file and decode it to a Map
return type:Map
expression example:{{yaml=importYaml('test/src/parser/tag/expression/function/import/person.yaml')}}{{yaml.person.child.name}}
code example:import_yaml_test.dart
parameter:sourceStringmandatoryThe project path of the YAML file. This path can be a absolute or relative file path or URI.

Operator #
An operator behaves generally like functions,
but differs syntactically or semantically.
Common simple examples include arithmetic (e.g. addition with +) and
logical operations (e.g. &).
An operator can be used anywhere in an tag expression
wherever that particular Operator should be performed.
The TemplateEngine supports several standard operators.
Custom Operators #
You can adopt existing operators or add your own custom operators by
manipulating the TemplateEngine.operatorGroups field.
See custom_operator_test.dart.
Available Operators #
Parentheses #

operator: ( ... )
description:Groups expressions together so that the are calculated first
expression example:{{(2+1)*3}} should render: 9
code example:parentheses_test.dart

Prefixes #

operator: +
parameter type: number
description:Optional prefix for positive numbers
expression example:{{+3}} should render: 3
code example:positive_test.dart


operator: -
parameter type: number
description:Prefix for a negative number
expression example:{{-3}} should render: -3
code example:negative_test.dart


operator: !
parameter type: boolean
description:Prefix to invert a boolean, e.g.: !true =false
expression example:{{!true}} should render: false
code example:not_test.dart

Multiplication #

operator: ^
parameter type: number
description:Calculates a number to the power of the exponent number
expression example:{{2^3}} should render: 8
code example:num_power_test.dart
parameter type: boolean
description:Logical XOR with two booleans
expression example:{{true^false}} should render: true
code example:bool_xor_test.dart


operator: *
parameter type: number
description:Multiplies 2 numbers
expression example:{{2*3}} should render: 6
code example:num_multiply_test.dart


operator: /
parameter type: number
description:Divides 2 numbers
expression example:{{6/4}} should render: 1.5
code example:num_divide_test.dart


operator: %
parameter type: number
description:Calculates the modulo (rest value of a division)
expression example:{{8%3}} should render: 2
code example:num_modulo_test.dart


operator: &
parameter type: boolean
description:Logical AND operation on two booleans
expression example:{{true&true}} should render: true
code example:bool_and_test.dart
parameter type: String
description:Concatenates two strings
expression example:{{"Hel"&"lo"}} should render: Hello
code example:string_concatenate_test.dart

Additions #

operator: +
parameter type: number
description:Adds two numbers
expression example:{{2+3}} should render: 5
code example:num_addition_test.dart
parameter type: String
description:Concatenates two strings
expression example:{{"Hel"+"lo"}} should render: Hello
code example:string_concatenate_test.dart


operator: -
parameter type: number
description:Subtracts two numbers
expression example:{{5-3}} should render: 2
code example:num_subtract_test.dart


operator: |
parameter type: boolean
description:Logical OR operation on two booleans
expression example:{{false|true}} should render: true
code example:bool_or_test.dart

Comparisons #

operator: ==
parameter type: Object
description:Checks if two values are equal
expression example:{{5==2+3}} should render: true
code example:equals_test.dart


operator: !=
parameter type: Object
description:Checks if two values are NOT equal
expression example:{{4!=2+3}} should render: true
code example:not_equals_test.dart


operator: >=
parameter type: number
description:Checks if the left value is greater than or equal to the right value
expression example:{{2>=2}} should render: true
code example:greater_than_or_equal_test.dart


operator: >
parameter type: number
description:Checks if the left value is greater than the right value
expression example:{{2>1}} should render: true
code example:greater_than_test.dart


operator: <=
parameter type: number
description:Checks if the left value is less than or equal to the right value
expression example:{{2<=2}} should render: true
code example:less_than_or_equal_test.dart


operator: <
parameter type: number
description:Checks if the left value is less than the right value
expression example:{{2>1}} should render: true
code example:less_than_test.dart

Assignment #

operator: =
description:Assigns a value to a variable. A new variable will be created when it did not exist before, otherwise it will be overridden with a new value.
expression example:{{x=2}}{{x=x+3}}{{x}} should render: 5
code example:assignment_test.dart