<!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 the ANTLR3 C Target</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('using.html','');
</script>
<div id="doc-content">
<div class="header">
<div class="headertitle">
<h1>Using the ANTLR3 C Target </h1> </div>
</div>
<div class="contents">
<div class="textblock"><h2><a class="anchor" id="intro"></a>
Introduction</h2>
<p>Using the ANTLR target involves gaining knowledge of a number of elements:</p>
<ol type="1">
<li>Writing ANTLR grammars (not covered in this manual);</li>
<li>How ANTLR works (not covered in this manual);</li>
<li>How to use the @sections with the C target</li>
<li>Interoperation with the runtime within rule actions;</li>
<li>Implementing custom versions of the standard library methods;</li>
</ol>
<p>If you are as yet unfamiliar with how ANTLR works in general, then it is suggested that you read the various <a href="http://www.antlr.org/wiki">wiki pages</a> concerned with getting started. However there are a few things that you should note:</p>
<ul>
<li>The lexer is independent of the parser. You <b>cannot</b> control the lexer from within the parser;</li>
<li>The tree parser is independent of the parser. You <b>cannot</b> control the parser from within the tree parser(s);</li>
<li>Each tree parser is independent of other tree parsers.</li>
</ul>
<p>This means that your lexer runs first and consumes all the input stream until you stop it programmatically, or it reaches the end of the input stream. It produces a complete stream of tokens, which the parser then consumes.</p>
<h2><a class="anchor" id="Using"></a>
@sections in a C Targeted Grammar</h2>
<p>Within a grammar file there are a number of special sections you can add that cause the code within them to be placed at strategic points in the generated code such as before or after the #include statements in the .c file, within the generated header file or within the constructor for the recognizer.</p>
<p>Many of the @sections used within a Java targeted grammar have some equivalent function within a C targeted grammar, but their use may well be subtly different. There are also additional sections that have meaning only within a grammar targeted for the C runtime.</p>
<p>Detailed documentation of these sections is given here: <a class="el" href="atsections.html">Using Sections Within Grammar Files</a></p>
<h2><a class="anchor" id="interop"></a>
Interacting with the Generated Code</h2>
<p>Rule actions have a limited number of elements they can access by name, independently of the target language generated. These are elements such as $line, $pos, $text and so on. Where the $xxx returns a basic type such as <code>int</code>, then you can use these in C as you would in the Java target, but where a reference returns a string, you will get a pointer to the C runtime string implementation <a class="el" href="group___a_n_t_l_r3___s_t_r_i_n_g.html#ga36bbe7362079348864db4b4dbdcce56b" title="Pointer to an instantiation of 'class' ANTLR3_STRING.">pANTLR3_STRING</a>. This will give you access to things like token text but also provides some convenience methods such as <a class="el" href="group___a_n_t_l_r3___s_t_r_i_n_g.html#ga36bbe7362079348864db4b4dbdcce56b" title="Pointer to an instantiation of 'class' ANTLR3_STRING.">pANTLR3_STRING</a>->substring() and <a class="el" href="group___a_n_t_l_r3___s_t_r_i_n_g.html#ga36bbe7362079348864db4b4dbdcce56b" title="Pointer to an instantiation of 'class' ANTLR3_STRING.">pANTLR3_STRING</a>->toUTF8().</p>
<p>The generated code provides a number of C MACROs, which make it easier to access runtime components. Always use these macros when available, to protect your action code from changes to the underlying implementation.</p>
<p>Detailed documentation of macros and rule action interoperation is given here: <a class="el" href="using.html">Interacting with the Generated Code</a></p>
<h2><a class="anchor" id="Custom"></a>
Implementing Customized Methods</h2>
<p>Unless you wish to create your own tree structures using the built in ANTLR AST rewriting notation, you will rarely need to override the default implementation of runtime methods. The exception to this will be the syntax err reporting method, which is essentially a stub function that you will usually want to provide your own implementation for. You should consider the built in function <a class="el" href="group__p_a_n_t_l_r3___b_a_s_e___r_e_c_o_g_n_i_z_e_r.html#ga3c88e896255781a0ace9fd1110900424" title="Standard/Example error display method.">displayRecognitionError()</a> as an example of where to start as there can be no really useful generic error message display. </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="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>
