1. Preface
This document describe the syntax of an Acceleo 4 module.
The syntax is described using the Backus Naur from (BNF).
2. Syntax
2.1. Comment
A comment can be used to document any part of the Module. It generates nothing if placed directly or indirectly in a File Statement. For simplification comments will not be present in the BNF representation of the grammar.
Comment = '[comment ' ... '/]'
2.2. Module
The module is the top level element of a .mtl file. It represent a namespace declaring Template and Query. The name of the module is qualified by the location of the file in the source folder.
Module =
(Module Documentation)* '[module ' Identifier '(' Metamodel ',' (Metamodel)* ')' ('extends ' Module Reference)? '/]'
Import*
Module Element*
2.3. Identifier
An identifier is used to name elements that need to be identified, or reference element that can be identified.
Identifier = [a-zA-Z_][a-zA-Z_0-9]*
2.4. Module Documentation
The module documentation should contains a description of the Module.
It can also contain metadata such as the author, version, and since (the version since this Module exists).
Module Documentation =
'[**'
...
('@author' ...)?
('@version' ...)?
('@since' ...)?
...
'/]'
2.5. Metamodel
This is the declaration of metamodels used by the module. Metamodels are referenced using their EPackage nsURI between simple quote.
Metamodel = '\'' ... '\''
2.6. Import
This allows a module to import other Module or service classes.
Import = '[import ' Module Reference '/]'
2.7. Module Reference
The module reference is a qualified reference to a Module
2.8. Module Qualified Name
A module’s name is qualified according to its location in the source folder of a project.
Module Qualified Name = Identifier ('::' Identifier)*
2.9. Module Element
2.10. Template
A template returns a String produced using its contained Statement, it can be called as a service. It can be preceded by a Module Element documentation.
Also a Module can contain a template used as entry point of the generation. This template will be identified with a Comment preceding the template and containing the tag '@main'.
Template =
'[template ' Visibility Identifier '(' Parameter(',' Parameter)* ')' ('?' AQL Expression)? ('post (' AQL Expression ')')? ']'
(Statement)*
'[/template]'
2.11. Visibility
The visibility defines the scope in which a Module Element can be called as a service.
Visibility = 'private' | 'protected' | 'public'
2.12. Parameter
A parameter is used to pass a value from the caller to a callee. This value can be later referenced using its identifier.
2.13. Statement
A statement is a directive used to produce an output or control the execution flow.
2.13.1. File Statement
This statement is used to start the generation of a new file. Strings returned by a statement contained directly or indirectly in the execution flow, will be generated into that file.
The file statement itself returns an empty String.
File Statement =
'[file ' '(' AQL Expression ',' [Open Mode Kind] (',' AQL Expression)? ')' ']'
(Statement)*
'[/file]'
2.13.2. For Statement
This statement loops over a list of values and return the concatenation of all returned String.
For Statement =
'[for ' '(' Identifier (':' AQL Type Literal)? '|' AQL Expression ')' ('separator(' AQL Expression ')')? ']'
(Statement)*
'[/for]'
2.13.3. If Statement
This statement create a branch in the execution flow and return the String of one of its branch according to the AQL Expression evaluated to true. If a condition doesn’t evaluate to a boolean an empty String is generated and an error is logged.
If Statement =
'[if ' '(' AQL Expression ')' ']'
(Statement)*
('[elseif ' '(' AQL Expression ')' ']'
(Statement)*)*
('[else]'
(Statement)*)?
'[/if]'
2.13.4. Let Statement
This statement allows to compute one or more AQL Expression and reference their value using an identifier. It can be used to improve readability of the template or increase performance when using the same AQL Expression many times in a block of Statement.
Let Statement =
'[let ' Identifier (':' AQL Type Literal)? '=' AQL Expression (',' Identifier (':' AQL Type Literal)? '=' AQL Expression)* ']'
(Statement)*)?
'[/let]'
2.13.5. Protected Area
This statement declares an identified area in the generated file. If the generated file exists and a protected area with the same identifier exists in its contents, then the existing content of this area is directly returned. If it doesn’t exist, then the concatenation of the body’s statements results is returned.
Protected Area =
'[protected ' '(' AQL Expression ')' ('startTagPrefix(' AQL Expression ')')? ('endTagPrefix(' AQL Expression ')')? ']'
(Statement)*)?
'[/protected]'
The start tag prefix and end tag prefix expressions allows to add a prefix to the intserted start and end tag to delimit the protected area in the generated document. If an unkown protected area id is encountered in a pre-existing generated document, a lost file is created to save its content.
2.13.6. Expression Statement
This statement returns the String representation of the evaluation of its AQL Expression.
Expression Statement = '[' AQL Expression '/]'
2.13.7. Text Statement
This is any other text outside of '[' and ']'.
2.14. AQL Expression
This is an Acceleo Query Language expression. It is used to navigate through models and call services. In the context of Acceleo, Template and Query can be called as services.
See the AQL documentation for more details about the language itself, the full list of standard services, and the differences with Acceleo/MTL.
2.15. AQL Type Literal
This is a type literal as defined in the Acceleo Query Language.
2.16. Query
A query references an AQL Expression with parameters and can be called as a service. It can be preceded by a Module Element documentation.
Query =
'[query ' Visibility Identifier '(' Parameter(',' Parameter)* ')' ':' AQL Type Literal '=' AQL Expression '/]'
2.17. Module Element documentation
Module Element documentation =
'[**'
...
'@param ' ...
...
'/]'