08 Functions in tag expressions - domain-centric/template_engine GitHub Wiki

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.

An example of a function call: cos(pi) Should result in: -1

Parameters and Arguments

Function & Parameter & argument names:

  • are case sensitive
  • must start with a lower case letter, optionally followed by (lower or upper case) letters and or digits.
  • conventions: use lowerCamelCase
  • must be unique and does not match a other tag syntax

Parameters vs Arguments

  • Parameters are the names used in the function definition.
  • Arguments are the actual values passed when calling the function.

Parameters:

  • A function can have zero or more parameters
  • Parameters are defined as either mandatory or optional
  • Optional parameters can have a default value

Arguments:

  • Multiple arguments are separated with a comma, e.g. single argument: cos(pi) multiple arguments: volume(10,20,30)
  • There are different types of arguments
    • Positional Arguments: These are passed in the order the function defines them. e.g.: volume(10, 20, 30)
    • Named Arguments: You can specify which parameter you're assigning a value to, regardless of order. e.g.: volume(l=30, h=10, w=20)
  • Arguments can set a parameter only once
  • You can mix positional arguments and named arguments, but positional arguments must come first
  • Named arguments remove ambiguity: If you want to skip an optional argument or specify one out of order, you must name it explicitly

Argument values:

  • must match the expected parameter type. e.g. area(length='hello', width='world') will result in a failure
  • may be a tag expression such as a variable, constant, operation, function, or combination. e.g. cos(2*pi)

Custom Functions

You can use prepackaged [template_engine] functions or add your own custom functions by manipulating the TemplateEngine.functionGroups field.
See Example.

Available Functions

Math Functions

exp Function

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: value number mandatory

log Function

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: value number mandatory

sin Function

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

asin Function

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: value number mandatory

cos Function

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

acos Function

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: value number mandatory

tan Function

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: radians number mandatory

atan Function

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: value number mandatory

sqrt Function

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: value number mandatory

round Function

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

String Functions

length Function

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

Documentation Functions

tagDocumentation Function

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

dataTypeDocumentation Function

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: titleLevel number optional (default=1) The level of the tag title

constantDocumentation Function

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: titleLevel number optional (default=1) The level of the tag title

variableDocumentation Function

description: Generates markdown documentation of variables that can be used within a ExpressionTag of a TemplateEngine
return type: String
expression example: {{ variableDocumentation() }}
parameter: titleLevel number optional (default=1) The level of the tag title

functionDocumentation Function

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: titleLevel number optional (default=1) The level of the tag title

operatorDocumentation Function

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: titleLevel number optional (default=1) The level of the tag title

exampleDocumentation Function

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

Path Functions

templateSource Function

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

Import Functions

importTemplate Function

description: Imports, parses and renders a template file
return type: IntermediateRenderResult
expression example: {{importTemplate('test/src/parser/tag/expression/function/import/to_import.md.template')}}
code example: import_template_test.dart
parameter: source String mandatory The project path of the template file

importPure Function

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: source String mandatory The project path of the file. This path can be a absolute or relative file path or URI.

importJson Function

description: Imports a JSON file and decode it to a Map, which could be assigned it to a variable.
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: source String mandatory The project path of the JSON file. This path can be a absolute or relative file path or URI.

importXml Function

description: Imports a XML file and decode it to a Map, which could be assigned it to a variable.
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: source String mandatory The project path of the XML file. This path can be a absolute or relative file path or URI.

importYaml Function

description: Imports a YAML file and decode it to a Map, which could be assigned it to a variable.
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: source String mandatory The project path of the YAML file. This path can be a absolute or relative file path or URI.
⚠️ **GitHub.com Fallback** ⚠️