Menu

• Introduction
• Update site installation
• Quickstart
• First generator module
• Using Acceleo with GMF

Indent strategies

Abstract
This document describes the Acceleo services meant to handle the code indentation. It tackles the behavior of the Acceleo syntax, especially the scripts, if and for statements.

By William Piers, Obeo (France)

Introduction

This document's goal is to provide all the keys needed to generate a perfectly indented code i.e. handling spaces, tabs and carriage returns in your template.

The "script", "if" and "for" elements have a special impact on the generated code, their behavior has been defined in order to provide an easy way to handle code indentation keeping a good readability. The following section describes these behaviors and explain how you should use them.

if, for and script behavior

Common concerns

While generating code, spaces and tabs you may have after a "script", "if" or "for" are deleted. It means that only the "if" content will be generated in the following example.

The next screenshot shows :

at the top left side, the generated code preview (source tab)

at the bottom left, the generation template

on the right, the outline view describing the model structure

The tabs, spaces and carriage return inside the "if" (or "for") are generated as you may see in the following example :

The tabs and spaces between the start of a line and the opening tag or closing tag are ignored. It means these tags may be put anywhere on the line with no effect on the generated code. This is useful when you want to use your indentation in order to provide a readable template.

In this example, a tab has been added before the "if".

But if the area beginning at the start of the line and ending at the tag has text, this text will be generated as you may see with the Java comments (/* and */) in the following example.

For tag behavior

The "for" tag in the following example generates a line for each attribute including the starting tab and the carriage return at the end of the line.

In the next example a carriage return has been added inside the loop, this carriage return affects the code putting a new line between each attribute.

In order to prevent the for loop to start a new line for each iteration you may remove the last carriage return just before the closing tag. Then the loop generates all the code on a single line.

Scripts parameters

The "post" attribute

You may change the indent strategy using an optional attribute in the scrip header. This attribute is named "post" meaning "postprocessing".

<%script type="Type" name="javaType" post="trim()"%>

The trim() service

The trim() service removes the spaces from the generated text. It is useful when you want to structure your template adding lines and spaces and you don't want this organisation to impact the generated code.

The following example shows a script which maps Java types. This script has many "if"s and its readability is greatly improved with a nicely indented code. This template indentation has effect in the generated code which has many carriage returns, tabs and spaces.

Using trim(), these carriage returns, tabs and spaces are removed from the generated code.

The indentTab() and indentSpace() services

The default behavior for a script is to generate the code from the place where it is called, keeping the content indentation. When a subscript generating many lines is called, it is adviced to put this call at the beginning of the line, avoiding issues as you may see in the genAttributes script :

In models you often have recursive relations (subclassing, containement..). This may be reflected in the generated code thanks to indentSpace() and indentTab().

The following example shows the use of these services for nested classes generation. The main script "genClass" generates a class then calls the "genNestedClass" script. This one calls back the "genClass" script using the "indentTab()". This service will be applied on the "genClass" output.

At last, this example shows the result you'll have using indentSpace instead of indentTab.

Conclusion

This document describes the rules you should apply in order to have nicely indented generated code and template. The template indentation is an important concern because it eases the template maintenance and re-use.

While creating a generation module, it is advised to follow this process:

- coding the generator thinking about its features, resolving all the technical issues and correctly indenting the Acceleo template. In this first phase the generated code indentation should be ignored.

- checking the generated code, correcting indentation issues thanks to the services

Using this process helps in creating a readable generation module. Thanks to Acceleo it's easy, in a second step, to fix the generator in order to generate correctly indented code.