plugins/org.eclipse.acceleo.aql.doc/pages/Acceleo/index.asciidoc

= Acceleo
Acceleo 4 User Guide

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

== Introduction

Acceleo 4 is a a text generator based on templates. It can be used to generate any kind of text file: code, configuration, documentation, ... The template consists of imperative statements like conditionals, loops, and navigation expression used to retrieve data from models. When generating the engine use templates  statements and also replace navigation expressions by their values in order to produce the output text. 

== Generating

This section describe how to launch a generation from <<eclipse>> or <<_maventycho>>. Note that you can also use the <<_debugger>> to run a module or directly use Acceleo 4 programmatically, see <<_generation>>.

=== Eclipse

TODO

=== Maven/Tycho

Acceleo provides a specific eclipse application that can be used from command line or tycho in order to start a generation.
In order to use the launcher, you will need to first package all of your generator projects into an update site, then use this update site as input of the application.

An example is available in the Acceleo repository and can be checked out at https://git.eclipse.org/c/acceleo/org.eclipse.acceleo.git/tree/examples/MavenLauncher .

This example includes:

* A generator project `org.eclipse.acceleo.aql.launcher.sample`
* A feature including this project `org.eclipse.acceleo.aql.launcher.sample-feature`
* An update site including this feature `org.eclipse.acceleo.aql.launcher.sample-site`
* A pom.xml file that can be used to both package the generator and start the generation

The packaging can be started through the command line `mvn clean verify`.
Once packaged, generation can be started through the command line `mvn clean verify -Pgenerate`.

The application takes a number of arguments that will have to be customized through the pom.xml file:

----
<applicationsArgs>
	<args>-application</args>
	<args>org.eclipse.acceleo.aql.launcher.AcceleoLauncher</args>
	<args>-data</args>
	<args>${project.build.directory}/wks</args>
	<args>-bundle</args>
	<args>org.eclipse.acceleo.aql.launcher.sample</args>
	<args>-module</args>
	<args>org::eclipse::acceleo::aql::launcher::sample::main</args>
	<args>-models</args>
	<args>platform:/plugin/org.eclipse.acceleo.aql.launcher.sample/model/sample.xmi</args>
	<args>-target</args>
	<args>file:/${project.build.directory}/generated/</args>
</applicationsArgs>
----

application::
Standard Eclipse argument, this tells Eclipse which application it needs to run. The specific launcher for Acceleo generations is `org.eclipse.acceleo.aql.launcher.AcceleoLauncher`.
data::
Standard Eclipse argument, this can be used to modify the workspace path.
bundle::
This needs to be the identifier of the bundle containing the main module for this generation.
module::
The starting point of the generation that is to be started. This needs to the qualified name of the module containing an "@main"-annotated template.
models::
The URI of the models that will be fed to the main module of the generation. This cannot be empty and needs to be an URI that eclipse is capable of resolving. In this example we're using a `platform:/plugin/...` URI since we've bundled the input model into our generator project.
target::
The destination URI for this generation. Generated files will use this folder as their root to resolve against. *Note* that this needs to end in a trailing `/`.

== Module authoring

This section cover tools for template writing, debugging and testing. You can read to the link:language.html[language documentation] to understand Acceleo 4 language specificity. If you are looking for the syntax quick reference you can check the link:syntax.html[syntax page].

=== White spaces

When generating text, and especially code, white spaces and indentation is an important point. In order to keep template code indentation from interfering with the generated output, a few rules applies:

- each block has a mandatory indentation of two characters than will not be generated in the output (in yellow below)
- when generating a block if the last generated line is not empty, it is repeated at the beginning of each line generated by the block (in red below)

image::images/Indentation.png[Indentation] 

=== Editor

TODO

=== Debugger

TODO

=== Unit test module

You can unit test your modules using the same JUnit test suite we are using for the development of Acceleo 4. You will simply need to create a class extending the class org.eclipse.acceleo.tests.utils.AbstractEvaluationTestSuite and create a folder with you test folders. Those folders need to respect a naming convention. You can find a working example with the class https://git.eclipse.org/c/acceleo/org.eclipse.acceleo.git/tree/acceleo-aql/org.eclipse.acceleo.aql.tests/src/org/eclipse/acceleo/tests/evaluation/FileStatementTests.java?h=acceleo-aql[FileStatementTests] and the corresponding https://git.eclipse.org/c/acceleo/org.eclipse.acceleo.git/tree/acceleo-aql/org.eclipse.acceleo.aql.tests/resources/evaluation/fileStatement?h=acceleo-aql[folder].

== Using Acceleo 4 programmatically

Acceleo 4 can be used programmatically and for instance integrated in other products. 

=== Parsing

[source,java]
---------
URI destination = URI.createURI(...);
environment = new AcceleoEnvironment(new DefaultGenerationStrategy(), destination);
IQualifiedNameResolver moduleResolver = new ClassLoaderQualifiedNameResolver(getClass().getClassLoader(), environment.getQueryEnvironment());
environment.setModuleResolver(moduleResolver);
Module module = environment.getModule(qualifiedName);
---------


=== Validation

[source,java]
----
AcceleoValidator validator = new AcceleoValidator(environment);
List<IValidationMessage> messages = validator.validate(astResult, qualifiedName).getValidationMessages();
----

=== Completion

[source,java]
----
AcceleoCompletor completor = new AcceleoCompletor();
String source = ...;
List<ICompletionProposal> proposals = completor.getProposals(environment, source, position);
----

=== Generation

[source,java]
----
AcceleoEvaluator evaluator = new AcceleoEvaluator(environment);
ResourceSetImpl rs = new ResourceSetImpl();
Resource model = rs.getResource(..., true);
AcceleoUtil.generate(evaluator, environment, module, model);
----