Google Git
Sign in
eclipse / acceleo / org.eclipse.acceleo / refs/heads/R3_3_maintenance / . / doc / org.eclipse.acceleo.doc / pages / reference / textproductionrules.html
blob: 8643b2b4f46e2d905532cb237b26703c6850ef65 [file] [log] [blame]
<!DOCTYPE html>
<html lang="en">
<!--
/********************************************************************************
** Copyright (c) 2012 Obeo.
** All rights reserved. This program and the accompanying materials
** are made available under the terms of the Eclipse Public License v1.0
** which accompanies this distribution, and is available at
** http://www.eclipse.org/legal/epl-v10.html
**
** Contributors:
** Stephane Begaudeau (Obeo) - initial API and implementation
*********************************************************************************/
-->
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="description" content="">
<meta name="author" content="St&eacute;phane B&eacute;gaudeau">
<!-- IE6-8 support of HTML elements -->
<!--[if lt IE 9]>
<script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
<![endif]-->
<link href="../../assets/css/bootstrap.css" rel="stylesheet">
<link href="../../assets/css/docs.css" rel="stylesheet">
<title>Acceleo</title>
</head>
<body>
<div class="container">
<section id="introduction">
<div class="page-header">
<h1>Text Production Rules <small>formatting rules</small></h1>
</div>
<p>
This is still a draft and is only provided as information. Though this document is still missing some formatting
and examples, it can be used to get a precise idea as to how indentation and carriage returns are handled in
Acceleo.
</p>
</section>
<section id="definitions">
<div class="page-header">
<h1>Definitions <small></small></h1>
</div>
<p>
Text production rules will apply to all body elements. Each body element can be either stand alone or embedded
within other body elements. It will be easier to understand text production rules by splitting these body elements
in five main categories : expressions, static text, comments, template invocation and blocks.
</p>
<p>
"Blocks" include template, for, if, let, protected area, file, trace and macro blocks. A block will be considered
"stand-alone" if it is either one of:
</p>
<ul>
<li>A single line block that is not surrounded with any other body element, except for white spaces, block tails and comments</li>
<li>A multi-line block that is not surrounded with any other body element, except for white spaces, block tails and comments, on the lines where the block head and tail occur</li>
</ul>
<p>
Any block that does not fall into these categories will be considered an "embedded" block.
</p>
<h2>Examples</h2>
<h3>Stand-alone single-line blocks</h3>
<p>
Nothing relevant for generation between the line start and the block head, nothing relevant between the block
tail and the line end; both head and tail on the same line. All of the following are in this category.
</p>
<pre>[for (Sequence{false, false, false})][self/][/for]</pre>
<br />
<pre>[if (true)]output[/if]</pre>
<br />
<pre>[/if] [comment .../] [if (true)]output[/if]</pre>
<br />
<pre>[/if] [if (true)]output[/if]</pre>
<br />
<h3>Embedded single-line blocks</h3>
<p>
Head and tail of the block are on the same line, but there is something relevant to the generation other than
the block on that same line.
</p>
<pre>Some text[for (Sequence{false, false, false})]output[/for]</pre>
<br />
<pre>[if (true)]output[/if] and some text</pre>
<br />
<pre>[for (Sequence{false, false, false})] [self/][/for] and some text.</pre>
<br />
<h3>Stand-alone multi-line blocks</h3>
<p>
Nothing relevant for generation between the line start and the block head, nothing relevant between the block
tail and the line end; head and tail on different lines.
</p>
<pre>
[for (Sequence{false, false, false})]
[self/]
[/for]
</pre>
<pre>
[if (true)]output
[/if]
</pre>
<pre>
[if (true)]
output[/if]
</pre>
<pre>
[comment]Generate booleans [/comment][for (Sequence{false, false, false})]
[self/][/for]
</pre>
<pre>
[for (Sequence{false, false, false})]
[self/]
[/for]
</pre>
<h3>Embedded multi-line blocks</h3>
<p>
Head and tail of the block are on different lines, but there is something relevant to the generation other
than the block on that same line.
</p>
<pre>
text[for (Sequence{false, false, false})]
[self/]
[/for]
</pre>
<pre>
[if (true)]
output[/if] text
</pre>
</section>
<section id="boundaries">
<div class="page-header">
<h1>Boundaries <small>identifying body element boundaries</small></h1>
</div>
<h2>Block Body</h2>
<h3>Single-line block</h3>
<p>
Body starts after the closing bracket of the block head and ends before the starting bracket of the block tail.
</p>
<h3>Multi-line block</h3>
<p>
If the closing bracket of the block head is directly followed by a new line, the block's body starts at the
beginning of the next line after the block head. Otherwise the block's body starts after the closing bracket
of its head. The body ends before the starting bracket of the block tail, be it directly preceded by a new
line or not.
</p>
<h3>Special handling of "Template" blocks</h3>
<p>
If the last characters preceding the starting bracket of the block tail is a new line followed by optional
white spaces, the template body ends before the last new line character preceding its tail.
</p>
<h2>Static Text</h2>
<p>
We need to define the concept of line relevance to properly identify these boundaries. For this purpose, we
will describe as "white spaces" the white space characters contained in a static text, whatever their position
in the text.
</p>
<p>
A line is considered "relevant" if it contains anything else than white spaces, block head, block tail and
comment. Note, however, that lines consisting of white spaces only are also considered relevant.
</p>
<ul>
<li>If a static text is entirely located on a non relevant line, it does not produce any text.</li>
<li>If a static text starts on a non relevant line, all characters located on this line are ignored and the
static text is considered to start with the character after its very first new line character.</li>
<li>If a static text ends on a non relevant line, all characters located on this line are ignored and the
static text is considered to end with the character before its very last new line character.</li>
<li>Special handling of static text following a « protected area » block: all white spaces following a
protected area tail are retained, including the new line character. The static text then starts right
after the closing bracket of the protected area tail.</li>
</ul>
</section>
<section id="rules">
<div class="page-header">
<h1>Rules <small></small></h1>
</div>
<p>
Considering the boundaries outlined in section Identifying Body Element Boundaries above, the text production
rules stand as follows:
</p>
<ul>
<li>The text produced by the execution of expressions is output as is;</li>
<li>The text produced by the execution of static text is output as is;</li>
<li>Comments do not produce any text;</li>
<li>
Each line of the text produced by a template invocation will be indented to
match the indentation of the line sporting the invocation;
</li>
<li>
The text produced by the execution of embedded blocks, be they multi-line
blocks or single line blocks, is output as is along with all text produced by
the surrounding body elements.
</li>
<li>
The text produced by the execution of stand-alone, single line blocks is
output as is. White spaces located before and after the block are retained;
</li>
<li>
The text produced by the execution of stand-alone, multi-line blocks will be
output as is considering the aforementioned boundaries: if the very first
character of the block body is a new line, it is ignored.
Please note that if a stand-alone, multi-line block doesn't produce any text,
not even a new line character will be present in the resulting text.
</li>
</ul>
</section>
<section id="examples">
<div class="page-header">
<h1>Examples <small></small></h1>
</div>
<p>
In the following examples, invisible characters have been materialized:
</p>
<table class="table table-striped table-bordered table-condensed">
<colgroup>
<col width="24%" />
<col width="76%" />
</colgroup>
<tbody valign="top">
<tr>
<td>·</td>
<td>indicates a space character</td>
</tr>
<tr>
<td>↪</td>
<td>indicates a horizontal tab character</td>
</tr>
<tr>
<td>¶</td>
<td>indicates a carriage return</td>
</tr>
</tbody>
</table>
<h2>Embedded blocks</h2>
<h3>Example 1</h3>
<p>The Acceleo code:</p>
<blockquote>
<tt class="docutils literal">Some</tt> · <tt class="docutils literal">text</tt> · <tt class="docutils literal">[for</tt> · <tt class="docutils literal">(Sequence{false,</tt> ·
<tt class="docutils literal">false,</tt> · <tt class="docutils literal">false})</tt> · <tt class="docutils literal">separator</tt> · <tt class="docutils literal">('</tt> ·
<tt class="docutils literal">-</tt> · <tt class="docutils literal"><span class="pre">')]output[/for]</span></tt></blockquote>
<p>produces the following result:</p>
<blockquote>
<tt class="docutils literal">Some</tt> · <tt class="docutils literal">text</tt> · <tt class="docutils literal">output</tt> · <tt class="docutils literal">-</tt> · <tt class="docutils literal">output</tt>
· <tt class="docutils literal">-</tt> · <tt class="docutils literal">output</tt></blockquote>
<hr class="docutils" />
<h3>Example 2</h3>
<p>The Acceleo code:</p>
<blockquote>
<tt class="docutils literal">[if</tt> · <tt class="docutils literal"><span class="pre">(true)]output[/if]</span></tt> · <tt class="docutils literal">and</tt> · <tt class="docutils literal">some</tt>
· <tt class="docutils literal">text</tt></blockquote>
<p>produces:</p>
<blockquote>
<tt class="docutils literal">output</tt> · <tt class="docutils literal">and</tt> · <tt class="docutils literal">some</tt> · <tt class="docutils literal">text</tt></blockquote>
<hr class="docutils" />
<h3>Example 3</h3>
<p>The Acceleo code:</p>
<blockquote>
↪ <tt class="docutils literal">[for</tt> · <tt class="docutils literal">(Sequence{false,</tt> · <tt class="docutils literal"><span class="pre">false})]</span></tt> ·
<tt class="docutils literal"><span class="pre">[self/][/for]</span></tt> · <tt class="docutils literal">and</tt> · <tt class="docutils literal">some</tt> · <tt class="docutils literal">text</tt></blockquote>
<p>produces:</p>
<blockquote>
↪ · <tt class="docutils literal">false</tt> · <tt class="docutils literal">false</tt> · <tt class="docutils literal">and</tt> · <tt class="docutils literal">some</tt>
· <tt class="docutils literal">text</tt></blockquote>
<hr class="docutils" />
<h3>Example 4</h3>
<p>The Acceleo code:</p>
<blockquote>
<p><tt class="docutils literal">text[for</tt> · <tt class="docutils literal">(Sequence{false,</tt> · <tt class="docutils literal"><span class="pre">false})]</span></tt> ¶</p>
<p>↪ <tt class="docutils literal">[self/]</tt> ¶</p>
<p><tt class="docutils literal">[/for]text</tt></p>
</blockquote>
<p>produces:</p>
<blockquote>
<p><tt class="docutils literal">text</tt> ↪ <tt class="docutils literal">false</tt> ¶</p>
<p>↪ <tt class="docutils literal">false</tt> ¶</p>
<p><tt class="docutils literal">text</tt></p>
</blockquote>
<hr class="docutils" />
<h3>Example 5</h3>
<p>The Acceleo code:</p>
<blockquote>
<p><tt class="docutils literal">text[for</tt> · <tt class="docutils literal">(Sequence{false,</tt> · <tt class="docutils literal"><span class="pre">false})]</span></tt> ¶</p>
<p>↪ <tt class="docutils literal"><span class="pre">output[/for]text</span></tt></p>
</blockquote>
<p>produces:</p>
<blockquote>
<tt class="docutils literal">text</tt> ↪ <tt class="docutils literal">output</tt> ↪ <tt class="docutils literal">outputtext</tt> ¶</blockquote>
<h2>Stand alone single-line blocks</h2>
<h3>Example 1</h3>
<p>The Acceleo code:</p>
<blockquote>
<tt class="docutils literal">[for</tt> · <tt class="docutils literal">(Sequence{false,</tt> · <tt class="docutils literal">false,</tt> ·
<tt class="docutils literal"><span class="pre">false})][self/][/for]</span></tt></blockquote>
<p>produces:</p>
<blockquote>
<tt class="docutils literal">falsefalsefalse</tt></blockquote>
<hr class="docutils" />
<h3>Example 2</h3>
<p>The Acceleo code:</p>
<blockquote>
<tt class="docutils literal">[if</tt> · <tt class="docutils literal"><span class="pre">(true)]output[/if]</span></tt></blockquote>
<p>produces:</p>
<blockquote>
<tt class="docutils literal">output</tt></blockquote>
<hr class="docutils" />
<h3>Example 3</h3>
<p>The Acceleo code:</p>
<blockquote>
↪ <tt class="docutils literal">[for</tt> · <tt class="docutils literal">(Sequence{false,</tt> · <tt class="docutils literal">false,</tt> ·
<tt class="docutils literal"><span class="pre">false})][self/][/for]</span></tt></blockquote>
<p>produces:</p>
<blockquote>
↪ <tt class="docutils literal">falsefalsefalse</tt></blockquote>
<hr class="docutils" />
<h3>Example 4</h3>
<p>The Acceleo code:</p>
<blockquote>
<tt class="docutils literal">[/if]</tt> ↪ ↪ <tt class="docutils literal">[if</tt> · <tt class="docutils literal"><span class="pre">(true)]output[/if]</span></tt></blockquote>
<p>produces:</p>
<blockquote>
↪ ↪ <tt class="docutils literal">output</tt></blockquote>
<hr class="docutils" />
<h3>Example 5</h3>
<p>The Acceleo code:</p>
<blockquote>
<tt class="docutils literal">[/if]</tt> · <tt class="docutils literal">[comment <span class="pre">.../]</span></tt> ↪ <tt class="docutils literal">[if</tt> · <tt class="docutils literal"><span class="pre">(true)]output[/if]</span></tt></blockquote>
<p>produces:</p>
<blockquote>
· ↪ <tt class="docutils literal">output</tt></blockquote>
<h2>Stand alone multi-line blocks</h2>
<h3>Example 1</h3>
<p>The Acceleo code:</p>
<blockquote>
<p><tt class="docutils literal">[for</tt> · <tt class="docutils literal">(Sequence{false,</tt> · <tt class="docutils literal">false,</tt> · <tt class="docutils literal"><span class="pre">false})]</span></tt> ¶</p>
<p>↪ <tt class="docutils literal">[self/]</tt> ¶</p>
<p><tt class="docutils literal">[/for]</tt></p>
</blockquote>
<p>produces:</p>
<blockquote>
<p>↪ <tt class="docutils literal">false</tt> ¶</p>
<p>↪ <tt class="docutils literal">false</tt> ¶</p>
<p>↪ <tt class="docutils literal">false</tt> ¶</p>
</blockquote>
<hr class="docutils" />
<h3>Example 2</h3>
<p>The Acceleo code:</p>
<blockquote>
<p><tt class="docutils literal">[if</tt> · <tt class="docutils literal"><span class="pre">(false)]output</span></tt> ¶</p>
<p><tt class="docutils literal">[/if]</tt></p>
</blockquote>
<p>produces nothing, neither whitespace nor empty line.</p>
<hr class="docutils" />
<h3>Example 3</h3>
<p>The Acceleo code:</p>
<blockquote>
<p><tt class="docutils literal">[if</tt> · <tt class="docutils literal">(true)]</tt> ¶</p>
<p>↪ <tt class="docutils literal"><span class="pre">output[/if]</span></tt></p>
</blockquote>
<p>produces:</p>
<blockquote>
↪ <tt class="docutils literal">output</tt></blockquote>
<hr class="docutils" />
<h3>Example 4</h3>
<p>The Acceleo code:</p>
<blockquote>
<p><tt class="docutils literal">[comment]for</tt> · <tt class="docutils literal"><span class="pre">loop[/comment][for</span></tt> ·
<tt class="docutils literal">(Sequence{false,</tt> · <tt class="docutils literal"><span class="pre">false})]</span></tt> ¶</p>
<p>↪ <tt class="docutils literal">[if</tt> · <tt class="docutils literal">(self)]</tt> ¶</p>
<p>↪ ↪ <tt class="docutils literal">[self/]</tt> ¶</p>
<p>↪ <tt class="docutils literal">[/if]</tt> ¶</p>
<p><tt class="docutils literal">[/for]</tt></p>
</blockquote>
<p>produces nothing, neither whitespace nor empty line.</p>
<hr class="docutils" />
<h3>Example 5</h3>
<p>The Acceleo code:</p>
<blockquote>
<p>↪ <tt class="docutils literal">[for</tt> · <tt class="docutils literal">(Sequence{false,</tt> · <tt class="docutils literal">false,</tt> ·
<tt class="docutils literal"><span class="pre">false})]</span></tt> ¶</p>
<p><tt class="docutils literal">[self/]</tt> ¶</p>
<p>↪ <tt class="docutils literal">[/for]</tt> ¶</p>
</blockquote>
<p>produces:</p>
<blockquote>
<p><tt class="docutils literal">false</tt> ¶</p>
<p><tt class="docutils literal">false</tt> ¶</p>
<p><tt class="docutils literal">false</tt> ¶</p>
</blockquote>
<br />
<br />
</section>
<footer class="footer">
<p>
The material in these guides are Copyright (c) 2008, 2012 Obeo. This material is available under the Eclipse Public License v1.0
</p>
</footer>
</div>
</body>
</html>