<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<title>ANTLR3C: Using Sections Within Grammar Files</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript">
$(document).ready(initResizable);
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<!-- Generated by Doxygen 1.7.3 -->
<div id="top">
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td style="padding-left: 0.5em;">
<div id="projectname">ANTLR3C <span id="projectnumber">3.1.2</span></div>
</td>
</tr>
</tbody>
</table>
</div>
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="index.html"><span>Main Page</span></a></li>
<li class="current"><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="modules.html"><span>Modules</span></a></li>
<li><a href="annotated.html"><span>Data Structures</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
<li><a href="dirs.html"><span>Directories</span></a></li>
</ul>
</div>
</div>
<div id="side-nav" class="ui-resizable side-nav-resizable">
<div id="nav-tree">
<div id="nav-tree-contents">
</div>
</div>
<div id="splitbar" style="-moz-user-select:none;"
class="ui-resizable-handle">
</div>
</div>
<script type="text/javascript">
initNavTree('atsections.html','');
</script>
<div id="doc-content">
<div class="header">
<div class="headertitle">
<h1>Using Sections Within Grammar Files </h1> </div>
</div>
<div class="contents">
<div class="textblock"><h2><a class="anchor" id="intro"></a>
Introduction</h2>
<p>A C targeted grammar can make use of special annotations within a grammar file, which are prefixed with the <b>@</b> character. These sections cause the the placement of their contents within the generated code at defined points such as within the generated C header file.</p>
<p>The general form of these annotations is:</p>
<div class="fragment"><pre class="fragment"> section
: <span class="charliteral">'@'</span> (( <span class="stringliteral">'parser'</span> | <span class="stringliteral">'lexer'</span> ) <span class="stringliteral">'::'</span>)? SECTIONNAME <span class="charliteral">'{'</span> yourcode <span class="charliteral">'}'</span>
;
</pre></div><p>If the 'parser' or lexer keywords are left out of the specification, then the ANTLR tool assumes a lexer target for a lexer grammar, a parser target for a parser or tree parser grammar, and a parser target for a combined lexer/parser grammar. You are advised as a matter of course to include the parser or lexer target keyword.</p>
<p>Documentation regarding the @sections available for a grammar targeted at C now follows.</p>
<h3><a class="anchor" id="psrinit"></a>
Sections @init and @declarations</h3>
<p>Java targeted grammars allow the special section <code>@init</code> to be placed after the declaration of a rule (lexer, parser and tree parser rules). This allows you to both declare and initialize variables that are local to the code generated for that rule. You can then reference them within your rule action code.</p>
<p>With the C target, the generated code is subject to the restrictions of C semantics and this means that you must declare any local variables, then assign to them afterwards. As well as the <code>@init</code> section, which C programmers should use to initialize their local variables, the C target provides the <code>@declarations</code> section, which is also a rule based section. This section is where the C programmer should declare the local variables, thus separating their declaration from their initialization. Here is an example:</p>
<div class="fragment"><pre class="fragment"> translation_unit
@declarations
{
<a class="code" href="antlr3defs_8h.html#a7c1b3bad112a645fd775b7b1481a700c">pANTLR3_BOOLEAN</a> hasUsing;
}
@init
{
<span class="comment">// Assume no Using directives</span>
<span class="comment">//</span>
hasUsing = <a class="code" href="antlr3errors_8h.html#a3baea4fe1963323e5757ee2c8f471d1c">ANTLR3_FALSE</a>;
}
: rulea ruleb ...
</pre></div><p>Using the <code>@declarations</code> and <code>@init</code> sections guarantees that your generated code will compile correctly on any standard C compiler (assuming, of course, that you type in valid C code.)</p>
<h3><a class="anchor" id="psrheader"></a>
@header section.</h3>
<p>The <code>@parser::header</code> or <code>@lexer::header</code> annotations cause the code they encapsulate to be placed at the start of each generated file, regardless of whether it is a .c or .h file. This can be useful for inserting copyright information and so on in all your generated files.</p>
<p>: Be careful not to confuse this concept with placing code in the generated .h header file. The name choice is unfortunate, but was already used in the Java target to allow the placement of <code>imports</code> statements in generated java classes. We have therefore kept the intent of this section the same.</p>
<p>Here is an example:</p>
<div class="fragment"><pre class="fragment"> @lexer::header
{
<span class="comment">// Copyright (c) Jim Idle 2007 - All your grammar are belong to us.</span>
}
@parser::header
{
<span class="comment">// Copyright (c) Jim Idle 2007 - All your grammar are belong to us.</span>
}
</pre></div><h3><a class="anchor" id="hdrinclude"></a>
@includes section</h3>
<p>The <code>@parser::includes</code> or <code>@lexer::includes</code> annotations cause the code they encapsulate to be placed in the generated .h file, <b>after</b> the standard includes required by the ANTLR generated code.</p>
<p>Here you could for instance place a <code>#include</code> statement to cause your grammar code to include some standard definitions. Because you may use multiple parsers and lexers in your solution, you should probably not place <code>#define</code> statements here, but in the <code>@postinclude</code> section. Then you may create different <code>#defines</code> for different recognizers.</p>
<p>Here is an example:</p>
<div class="fragment"><pre class="fragment"> @lexer::includes
{
<span class="preprocessor"> #include "myprojectcommondefs.h"</span>
}
@parser::includes
{
<span class="preprocessor"> #include "myprojectcommondefs.h"</span>
}
</pre></div><h3><a class="anchor" id="hdrpreinclude"></a>
@preincludes section</h3>
<p>The <code>@parser::preincludes</code> or <code>@lexer::preincludes</code> annotations cause the code they encapsulate to be placed in the generated .h file, <b>before</b> the standard includes required by the ANTLR generated code.</p>
<p>You should use this section when you wish to place #defines and other definitions in the code before the standard ANTLR runtime includes defined them. This allows you to override any predefined symbols and options that the includes otherwise take defaults for. For instance, if you have built a version of the runtime with a special version of malloc, you can <code>#define</code> <a class="el" href="antlr3defs_8h.html#a3ba818e88ae972c4f77e55e80ed8abd5" title="Default definition of ANTLR3_MALLOC.">ANTLR3_MALLOC</a> to match the definition you used for the ANTLR runtime library.</p>
<h3><a class="anchor" id="hdrpostinclude"></a>
@postinclude section</h3>
<p>The <code>@parser::postinclude</code> or <code>@lexer::postinclude</code> annotations cause the code they encapsulate to be placed in the generated <b>.C</b> file, after the generated include file (which includes the standard ANTLR3C library includes.</p>
<p>Code you place here then will be subject to any macros defined by your own includes, by the generated include and by the standard ANTLR3 includes. This is a good place to <code>#undef</code> anything that you don;t like the default values of, but cannot override before the includes define them.</p>
<p>This is also a good place to <code>#define</code> any macros you may wish to use in the generated .c file. As you can include multiple parsers in your projects, you will need to include the generated .h file of each of them, possibly globally, but almost certainly in a context where you are including more than one .h file simultaneously. Hence if you commonly use the same macro names for accessing structures and so on, and they change from grammar to grammar, you should define them here to avoid creating conflicting definitions in the header files. </p>
</div></div>
</div>
<div id="nav-path" class="navpath">
<ul>
<li class="navelem"><a class="el" href="main.html">ANTLR3 C Runtime API and Usage Guide.</a> </li>
<li class="navelem"><a class="el" href="using.html">Using the ANTLR3 C Target</a> </li>
<li class="footer">Generated on Tue Feb 8 2011 for ANTLR3C by 
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.7.3 </li>
</ul>
</div>
</body>
</html>
