plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/syntax.adoc

= Acceleo
Acceleo 4 Syntax

:source-highlighter: highlightjs
:listing-caption: Listing
:toc:
:toclevels: 3
:sectnums:
:icons: image

== Preface

This document describe the syntax of an Acceleo 4 module.

The syntax is described using the https://en.wikipedia.org/wiki/Backus%E2%80%93Naur_form[Backus Naur from] (BNF).

== Syntax

=== 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.

[source,ebnf,subs=+macros]
----
<<Comment>> = '[comment ' ... '/]'
----

=== 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.

[source,ebnf,subs=+macros]
----
<<Module>> =

(<<Module Documentation>>)* '[module ' <<Identifier>> '(' <<Metamodel>> ',' (<<Metamodel>>)* ')' ('extends ' <<Module Reference>>)? '/]'

<<Import>>*

<<Module Element>>*
----

=== Identifier

An identifier is used to name elements that need to be identified, or reference element that can be identified.

[source,ebnf,subs=+macros]
----
<<Identifier>> = [a-zA-Z_][a-zA-Z_0-9]*
----

=== 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).

[source,ebnf,subs=+macros]
----
<<Module Documentation>> =

'[**'

...

('@author' ...)?

('@version' ...)?

('@since' ...)?

...

'/]'
----

=== Metamodel

This is the declaration of metamodels used by the module. Metamodels are referenced using their EPackage nsURI between simple quote.

[source,ebnf,subs=+macros]
----
<<Metamodel>> = '\'' ... '\''
----

=== Import

This allows a module to import other <<Module>> or service classes.

[source,ebnf,subs=+macros]
----
<<Import>> = '[import ' <<Module Reference>> '/]'
----

=== Module Reference

The module reference is a qualified reference to a <<Module>>

[source,ebnf,subs=+macros]
----
<<Module Reference>> = <<Module Qualified Name>>
----

=== Module Qualified Name

A module's name is qualified according to its location in the source folder of a project.

[source,ebnf,subs=+macros]
----
<<Module Qualified Name>> = <<Identifier>> ('::' <<Identifier>>)*
----

=== Module Element

A module element is either a <<Template>> or a <<Query>>.

[source,ebnf,subs=+macros]
----
<<Module Element>> = <<Template>> | <<Query>>
----

=== 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'.

[source,ebnf,subs=+macros]
----
<<Template>> =

'[template ' <<Visibility>> <<Identifier>> '(' <<Parameter>>(',' <<Parameter>>)* ')' ('?' <<AQL Expression>>)? ('post (' <<AQL Expression>> ')')? ']'

(<<Statement>>)*

'[/template]'
----

=== Visibility

The visibility defines the scope in which a <<Module Element>> can be called as a service.

[source,ebnf,subs=+macros]
----
<<Visibility>> = 'private' | 'protected' | 'public'
----

=== Parameter

A parameter is used to pass a value from the caller to a callee. This value can be later referenced using its identifier.

[source,ebnf,subs=+macros]
----
<<Parameter>> = <<Identifier>> ':' <<AQL Type Literal>>
----

=== Statement

A statement is a directive used to produce an output or control the execution flow.

[source,ebnf,subs=+macros]
----
<<Statement>> =

<<File Statement>> | <<For Statement>> | <<If Statement>> | <<Let Statement>> | <<Protected Area>> | <<Expression Statement>> | <<Text Statement>>
----

==== 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.

[source,ebnf,subs=+macros]
----
<<File Statement>> =

'[file ' '(' <<AQL Expression>> ',' <<Open Mode Kind>> (',' <<AQL Expression>>)? ')' ']'

(<<Statement>>)*

'[/file]' 
----

==== For Statement

This statement loops over a list of values and return the concatenation of all returned String.

[source,ebnf,subs=+macros]
----
<<For Statement>> =

'[for ' '(' <<Identifier>> (':' <<AQL Type Literal>>)? '|' <<AQL Expression>> ')' ['separator(' <<AQL Expression>> ')'] ']'

(<<Statement>>)*

'[/for]'
----

==== 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.

[source,ebnf,subs=+macros]
----
<<If Statement>> =

'[if ' '(' <<AQL Expression>> ')' ']'

(<<Statement>>)*

('[elseif ' '(' <<AQL Expression>> ')' ']'

(<<Statement>>)*)*

('[else]'

(<<Statement>>)*)?

'[/if]'
----

==== 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>>.

[source,ebnf,subs=+macros]
----
<<Let Statement>> =

'[let ' <<Identifier>> (':' <<AQL Type Literal>>)? '=' <<AQL Expression>> (',' <<Identifier>> (':' <<AQL Type Literal>>)? '=' <<AQL Expression>>)* ']'

(<<Statement>>)*)?

'[/let]'
----

==== 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.

[source,ebnf,subs=+macros]
----
<<Protected Area>> =

'[protected ' '(' <<AQL Expression>> ')' ']'

(<<Statement>>)*)?

'[/protected]'
----

==== Expression Statement

This statement returns the String representation of the evaluation of its <<AQL Expression>>.

[source,ebnf,subs=+macros]
----
<<Expression Statement>> = '[' <<AQL Expression>> '/]'
----

==== Text Statement

This is any other text outside of '[' and ']'.

=== 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.

TODO link AQL documentation

=== AQL Type Literal

This is a type literal as defined in the Acceleo Query Language.

TODO link AQL documentation

=== 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>>.

[source,ebnf,subs=+macros]
----
<<Query>> =

'[query ' <<Visibility>> <<Identifier>> '(' <<Parameter>>(',' <<Parameter>>)* ')' ':' <<AQL Type Literal>> '=' <<AQL Expression>> '/]'
----

=== Module Element documentation

The documentation of a <<Template>> or a <<Query>>.

[source,ebnf,subs=+macros]
----
<<Module Element documentation>> =

'[**'

...

'@param ' ...

...

'/]'
----