<!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: How to build Generated C Code</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('buildrec.html','');
</script>
<div id="doc-content">
<div class="header">
<div class="headertitle">
<h1>How to build Generated C Code </h1> </div>
</div>
<div class="contents">
<div class="textblock"><h2><a class="anchor" id="generated"></a>
Generated Files</h2>
<p>The antlr tool jar, run against a grammar file that targets the C language, will generate the following files according to whether your grammar file contains a lexer, parser, combined or treeparser specification. Your grammar file name and the subject of the grammar line in your file are expected to match. Here the generic name G is used:</p>
<table class="doxtable">
<tr>
<th>Suffix </th><th>Generated files </th></tr>
<tr>
<td>lexer grammar (G.g3l) </td><td>GLexer.c GLexer.h </td></tr>
<tr>
<td>parser grammar (G.g3p) </td><td>GParser.c GParser.h </td></tr>
<tr>
<td>grammar G (G.g3pl) </td><td>GParser.c GParser.h GLexer.c GLexer.h </td></tr>
<tr>
<td>tree grammar G; (G.g3t) </td><td>G.c G.h </td></tr>
</table>
<p>The generated .c files reference the .h files using <G.h>, so you must use <code>-I.</code> on your compiler command line (or include the current directory in your include paths in Visual Studio). Additionally, the generated .h files reference <code><a class="el" href="antlr3_8h.html">antlr3.h</a></code>, so you must use <code>-I/path/to/antlr/include</code> (E.g. <code>-I /usr/local/include</code>) to reference the standard ANTLR include files.</p>
<p>In order to reference the library file at compile time (you can/should only reference one) you need to use the <code>-L/path/to/antlr/lib</code> (E.g. <code>-L /usr/local/lib</code>) on Unix, or add the path to your "Additional Library Path" in Visual Studio. You also need to specify the library using <code>-L</code> on Unix (E.g. <code>-L /usr/local/lib -l antlr3c</code>) or add <code>antlr3c_dll.lib</code> to your Additional Library Dependencies in Visual Studio.</p>
<p>In case it isn't obvious, the generated files may be used to produce either a library or an executable (.EXE on Windows) file.</p>
<p>If you use the shared version of the libraries, DLL or .so/.so/.a then you must ship the library with your application must run in an environment whereby the library can be found by the runtime linker/loader. This usually involves specifying the directory in which the library lives to an environment variable. On Windows, X:{yourwininstalldir} will be searched automatically.</p>
<h2><a class="anchor" id="invoke"></a>
Invoking Your Generated Recognizer</h2>
<p>In order to run your lexer/parser/tree parser combination, you will need a small function (or main) function that controls the sequence of events, from reading the input file or string, through to invoking the tree parser(s) and retrieving the results. See "Using the ANTLR3C C Target" for more detailed instructions, but if you just want to get going as fast as possible, study the following code example.</p>
<div class="fragment"><pre class="fragment"> <span class="comment">// You may adopt your own practices by all means, but in general it is best</span>
<span class="comment">// to create a single include for your project, that will include the ANTLR3 C</span>
<span class="comment">// runtime header files, the generated header files (all of which are safe to include</span>
<span class="comment">// multiple times) and your own project related header files. Use <> to include and</span>
<span class="comment">// -I on the compile line (which vs2005 now handles, where vs2003 did not).</span>
<span class="comment">//</span>
<span class="preprocessor"> #include <treeparser.h></span>
<span class="comment">// Main entry point for this example</span>
<span class="comment">//</span>
<span class="keywordtype">int</span> <a class="code" href="antlr3defs_8h.html#a91c919dd260a95cc88a0cd9b5c0a11cc">ANTLR3_CDECL</a>
main (<span class="keywordtype">int</span> argc, <span class="keywordtype">char</span> *argv[])
{
<span class="comment">// Now we declare the ANTLR related local variables we need.</span>
<span class="comment">// Note that unless you are convinced you will never need thread safe</span>
<span class="comment">// versions for your project, then you should always create such things</span>
<span class="comment">// as instance variables for each invocation.</span>
<span class="comment">// -------------------</span>
<span class="comment">// Name of the input file. Note that we always use the abstract type pANTLR3_UINT8</span>
<span class="comment">// for ASCII/8 bit strings - the runtime library guarantees that this will be</span>
<span class="comment">// good on all platforms. This is a general rule - always use the ANTLR3 supplied</span>
<span class="comment">// typedefs for pointers/types/etc.</span>
<span class="comment">//</span>
<a class="code" href="antlr3defs_8h.html#a95c800abcac5d607fd9e3e775ace78c5">pANTLR3_UINT8</a> fName;
<span class="comment">// The ANTLR3 character input stream, which abstracts the input source such that</span>
<span class="comment">// it is easy to privide inpput from different sources such as files, or </span>
<span class="comment">// memory strings.</span>
<span class="comment">//</span>
<span class="comment">// For an ASCII/latin-1 memory string use:</span>
<span class="comment">// input = antlr3NewAsciiStringInPlaceStream (stringtouse, (ANTLR3_UINT32) length, NULL);</span>
<span class="comment">//</span>
<span class="comment">// For a UCS2 (16 bit) memory string use:</span>
<span class="comment">// input = antlr3NewUCS2StringInPlaceStream (stringtouse, (ANTLR3_UINT32) length, NULL);</span>
<span class="comment">//</span>
<span class="comment">// For input from a file, see code below</span>
<span class="comment">//</span>
<span class="comment">// Note that this is essentially a pointer to a structure containing pointers to functions.</span>
<span class="comment">// You can create your own input stream type (copy one of the existing ones) and override any</span>
<span class="comment">// individual function by installing your own pointer after you have created the standard </span>
<span class="comment">// version.</span>
<span class="comment">//</span>
<a class="code" href="struct_a_n_t_l_r3___i_n_p_u_t___s_t_r_e_a_m__struct.html" title="Master context structure for an ANTLR3 C runtime based input stream.">pANTLR3_INPUT_STREAM</a> input;
<span class="comment">// The lexer is of course generated by ANTLR, and so the lexer type is not upper case.</span>
<span class="comment">// The lexer is supplied with a pANTLR3_INPUT_STREAM from whence it consumes its</span>
<span class="comment">// input and generates a token stream as output. This is the ctx (CTX macro) pointer</span>
<span class="comment">// for your lexer.</span>
<span class="comment">//</span>
pLangLexer lxr;
<span class="comment">// The token stream is produced by the ANTLR3 generated lexer. Again it is a structure based</span>
<span class="comment">// API/Object, which you can customise and override methods of as you wish. a Token stream is</span>
<span class="comment">// supplied to the generated parser, and you can write your own token stream and pass this in</span>
<span class="comment">// if you wish.</span>
<span class="comment">//</span>
<a class="code" href="struct_a_n_t_l_r3___c_o_m_m_o_n___t_o_k_e_n___s_t_r_e_a_m__struct.html" title="Common token stream is an implementation of ANTLR_TOKEN_STREAM for the default parsers and recognizer...">pANTLR3_COMMON_TOKEN_STREAM</a> tstream;
<span class="comment">// The Lang parser is also generated by ANTLR and accepts a token stream as explained</span>
<span class="comment">// above. The token stream can be any source in fact, so long as it implements the </span>
<span class="comment">// ANTLR3_TOKEN_SOURCE interface. In this case the parser does not return anything</span>
<span class="comment">// but it can of course specify any kind of return type from the rule you invoke</span>
<span class="comment">// when calling it. This is the ctx (CTX macro) pointer for your parser.</span>
<span class="comment">//</span>
pLangParser psr;
<span class="comment">// The parser produces an AST, which is returned as a member of the return type of</span>
<span class="comment">// the starting rule (any rule can start first of course). This is a generated type</span>
<span class="comment">// based upon the rule we start with.</span>
<span class="comment">//</span>
LangParser_decl_return langAST;
<span class="comment">// The tree nodes are managed by a tree adaptor, which doles</span>
<span class="comment">// out the nodes upon request. You can make your own tree types and adaptors</span>
<span class="comment">// and override the built in versions. See runtime source for details and</span>
<span class="comment">// eventually the wiki entry for the C target.</span>
<span class="comment">//</span>
<a class="code" href="struct_a_n_t_l_r3___c_o_m_m_o_n___t_r_e_e___n_o_d_e___s_t_r_e_a_m__struct.html">pANTLR3_COMMON_TREE_NODE_STREAM</a> nodes;
<span class="comment">// Finally, when the parser runs, it will produce an AST that can be traversed by the </span>
<span class="comment">// the tree parser: c.f. LangDumpDecl.g3t This is the ctx (CTX macro) pointer for your</span>
<span class="comment">// tree parser.</span>
<span class="comment">//</span>
pLangDumpDecl treePsr;
<span class="comment">// Create the input stream based upon the argument supplied to us on the command line</span>
<span class="comment">// for this example, the input will always default to ./input if there is no explicit</span>
<span class="comment">// argument.</span>
<span class="comment">//</span>
<span class="keywordflow">if</span> (argc < 2 || argv[1] == NULL)
{
fName =(<a class="code" href="antlr3defs_8h.html#a95c800abcac5d607fd9e3e775ace78c5">pANTLR3_UINT8</a>)<span class="stringliteral">"./input"</span>; <span class="comment">// Note in VS2005 debug, working directory must be configured</span>
}
<span class="keywordflow">else</span>
{
fName = (<a class="code" href="antlr3defs_8h.html#a95c800abcac5d607fd9e3e775ace78c5">pANTLR3_UINT8</a>)argv[1];
}
<span class="comment">// Create the input stream using the supplied file name</span>
<span class="comment">// (Use antlr3AsciiFileStreamNew for UCS2/16bit input).</span>
<span class="comment">//</span>
input = <a class="code" href="antlr3filestream_8c.html#a449abcf6642288f35bacc3aae39c0ff6" title="Use the contents of an operating system file as the input for an input stream.">antlr3AsciiFileStreamNew</a>(fName);
<span class="comment">// The input will be created successfully, providing that there is enough</span>
<span class="comment">// memory and the file exists etc</span>
<span class="comment">//</span>
<span class="keywordflow">if</span> ( input == NULL )
{
<a class="code" href="antlr3defs_8h.html#a27cc6fe6e2b9ed95c34ccbcf85149361" title="Default definition of fprintf, set this to something other than fprintf before including antlr3...">ANTLR3_FPRINTF</a>(stderr, <span class="stringliteral">"Unable to open file %s due to malloc() failure1\n"</span>, (<span class="keywordtype">char</span> *)fName);
}
<span class="comment">// Our input stream is now open and all set to go, so we can create a new instance of our</span>
<span class="comment">// lexer and set the lexer input to our input stream:</span>
<span class="comment">// (file | memory | ?) --> inputstream -> lexer --> tokenstream --> parser ( --> treeparser )?</span>
<span class="comment">//</span>
lxr = LangLexerNew(input); <span class="comment">// CLexerNew is generated by ANTLR</span>
<span class="comment">// Need to check for errors</span>
<span class="comment">//</span>
<span class="keywordflow">if</span> ( lxr == NULL )
{
<a class="code" href="antlr3defs_8h.html#a27cc6fe6e2b9ed95c34ccbcf85149361" title="Default definition of fprintf, set this to something other than fprintf before including antlr3...">ANTLR3_FPRINTF</a>(stderr, <span class="stringliteral">"Unable to create the lexer due to malloc() failure1\n"</span>);
exit(<a class="code" href="antlr3errors_8h.html#abbdcaff3e5d4da9691443e7ecdb671bf">ANTLR3_ERR_NOMEM</a>);
}
<span class="comment">// Our lexer is in place, so we can create the token stream from it</span>
<span class="comment">// NB: Nothing happens yet other than the file has been read. We are just </span>
<span class="comment">// connecting all these things together and they will be invoked when we</span>
<span class="comment">// call the parser rule. ANTLR3_SIZE_HINT can be left at the default usually</span>
<span class="comment">// unless you have a very large token stream/input. Each generated lexer</span>
<span class="comment">// provides a token source interface, which is the second argument to the</span>
<span class="comment">// token stream creator.</span>
<span class="comment">// Note tha even if you implement your own token structure, it will always</span>
<span class="comment">// contain a standard common token within it and this is the pointer that</span>
<span class="comment">// you pass around to everything else. A common token as a pointer within</span>
<span class="comment">// it that should point to your own outer token structure.</span>
<span class="comment">//</span>
tstream = <a class="code" href="antlr3tokenstream_8c.html#ad4ef5baa73e1fdd0f0c2fc4cce4277cb">antlr3CommonTokenStreamSourceNew</a>(<a class="code" href="antlr3defs_8h.html#a0f089eaab6993865d3d5daab26f8db98">ANTLR3_SIZE_HINT</a>, lxr->pLexer->tokSource);
<span class="keywordflow">if</span> (tstream == NULL)
{
<a class="code" href="antlr3defs_8h.html#a27cc6fe6e2b9ed95c34ccbcf85149361" title="Default definition of fprintf, set this to something other than fprintf before including antlr3...">ANTLR3_FPRINTF</a>(stderr, <span class="stringliteral">"Out of memory trying to allocate token stream\n"</span>);
exit(<a class="code" href="antlr3errors_8h.html#abbdcaff3e5d4da9691443e7ecdb671bf">ANTLR3_ERR_NOMEM</a>);
}
<span class="comment">// Finally, now that we have our lexer constructed, we can create the parser</span>
<span class="comment">//</span>
psr = LangParserNew(tstream); <span class="comment">// CParserNew is generated by ANTLR3</span>
<span class="keywordflow">if</span> (psr == NULL)
{
<a class="code" href="antlr3defs_8h.html#a27cc6fe6e2b9ed95c34ccbcf85149361" title="Default definition of fprintf, set this to something other than fprintf before including antlr3...">ANTLR3_FPRINTF</a>(stderr, <span class="stringliteral">"Out of memory trying to allocate parser\n"</span>);
exit(<a class="code" href="antlr3errors_8h.html#abbdcaff3e5d4da9691443e7ecdb671bf">ANTLR3_ERR_NOMEM</a>);
}
<span class="comment">// We are all ready to go. Though that looked complicated at first glance,</span>
<span class="comment">// I am sure, you will see that in fact most of the code above is dealing</span>
<span class="comment">// with errors and there isn;t really that much to do (isn;t this always the</span>
<span class="comment">// case in C? ;-).</span>
<span class="comment">//</span>
<span class="comment">// So, we now invoke the parser. All elements of ANTLR3 generated C components</span>
<span class="comment">// as well as the ANTLR C runtime library itself are pseudo objects. This means</span>
<span class="comment">// that they are represented as pointers to structures, which contain any</span>
<span class="comment">// instance data they need, and a set of pointers to other interfaces or</span>
<span class="comment">// 'methods'. Note that in general, these few pointers we have created here are</span>
<span class="comment">// the only things you will ever explicitly free() as everything else is created</span>
<span class="comment">// via factories, that allocate memory efficiently and free() everything they use</span>
<span class="comment">// automatically when you close the parser/lexer/etc.</span>
<span class="comment">//</span>
<span class="comment">// Note that this means only that the methods are always called via the object</span>
<span class="comment">// pointer and the first argument to any method, is a pointer to the structure itself.</span>
<span class="comment">// It also has the side advantage, if you are using an IDE such as VS2005 that can do it</span>
<span class="comment">// that when you type ->, you will see a list of all the methods the object supports.</span>
<span class="comment">//</span>
langAST = psr->decl(psr);
<span class="comment">// If the parser ran correctly, we will have a tree to parse. In general I recommend</span>
<span class="comment">// keeping your own flags as part of the error trapping, but here is how you can</span>
<span class="comment">// work out if there were errors if you are using the generic error messages</span>
<span class="comment">//</span>
<span class="keywordflow">if</span> (psr->pParser->rec->errorCount > 0)
{
<a class="code" href="antlr3defs_8h.html#a27cc6fe6e2b9ed95c34ccbcf85149361" title="Default definition of fprintf, set this to something other than fprintf before including antlr3...">ANTLR3_FPRINTF</a>(stderr, <span class="stringliteral">"The parser returned %d errors, tree walking aborted.\n"</span>, psr->pParser->rec->errorCount);
}
<span class="keywordflow">else</span>
{
nodes = <a class="code" href="antlr3commontreenodestream_8c.html#a80515ce12fe3b7e18473029d07dceaa7">antlr3CommonTreeNodeStreamNewTree</a>(langAST.tree, <a class="code" href="antlr3defs_8h.html#a0f089eaab6993865d3d5daab26f8db98">ANTLR3_SIZE_HINT</a>); <span class="comment">// sIZE HINT WILL SOON BE DEPRECATED!!</span>
<span class="comment">// Tree parsers are given a common tree node stream (or your override)</span>
<span class="comment">//</span>
treePsr = LangDumpDeclNew(nodes);
treePsr->decl(treePsr);
nodes -><a class="code" href="struct_a_n_t_l_r3___c_o_m_m_o_n___t_r_e_e___n_o_d_e___s_t_r_e_a_m__struct.html#aebf4caa6b0e7bbb320948665c72aa328">free</a> (nodes); nodes = NULL;
treePsr -><a class="code" href="struct_a_n_t_l_r3___c_o_m_m_o_n___t_r_e_e___n_o_d_e___s_t_r_e_a_m__struct.html#aebf4caa6b0e7bbb320948665c72aa328">free</a> (treePsr); treePsr = NULL;
}
<span class="comment">// We did not return anything from this parser rule, so we can finish. It only remains</span>
<span class="comment">// to close down our open objects, in the reverse order we created them</span>
<span class="comment">//</span>
psr ->free (psr); psr = NULL;
tstream -><a class="code" href="struct_a_n_t_l_r3___c_o_m_m_o_n___t_o_k_e_n___s_t_r_e_a_m__struct.html#a062b7949ea434d5a82cf1a07a3f8c7ff" title="Function that knows how to free an ANTLR3_COMMON_TOKEN_STREAM.">free</a> (tstream); tstream = NULL;
lxr -><a class="code" href="struct_a_n_t_l_r3___c_o_m_m_o_n___t_o_k_e_n___s_t_r_e_a_m__struct.html#a062b7949ea434d5a82cf1a07a3f8c7ff" title="Function that knows how to free an ANTLR3_COMMON_TOKEN_STREAM.">free</a> (lxr); lxr = NULL;
input -><a class="code" href="struct_a_n_t_l_r3___i_n_p_u_t___s_t_r_e_a_m__struct.html#a1174c85bc9399c19072476c3187eec25" title="Pointer to function that closes the input stream.">close</a> (input); input = NULL;
<span class="keywordflow">return</span> 0;
}
</pre></div> </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>
