mirror of
https://github.com/boostorg/wave.git
synced 2026-01-26 07:02:23 +00:00
93 lines
8.6 KiB
HTML
93 lines
8.6 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html>
|
|
<head>
|
|
<title>Introduction</title>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
|
<link rel="stylesheet" href="theme/style.css" type="text/css">
|
|
</head>
|
|
|
|
<body text="#000000" background="theme/bkd.gif">
|
|
<table width="100%" border="0" cellspacing="2" background="theme/bkd2.gif">
|
|
<tr>
|
|
<td width="21">
|
|
<h1></h1></td>
|
|
<td width="885"> <font face="Verdana, Arial, Helvetica, sans-serif"><b><font size="6">Samples</font></b></font></td>
|
|
<td width="96"><a href="http://spirit.sf.net"><img src="theme/wave.gif" width="93" height="68" align="right" border="0"></a></td>
|
|
</tr>
|
|
</table>
|
|
<br>
|
|
<table border="0">
|
|
<tr>
|
|
<td width="10"></td>
|
|
<td width="30"><a href="index.html"><img src="theme/u_arr.gif" border="0"></a></td>
|
|
<td width="30"><a href="wave_driver.html"><img src="theme/l_arr.gif" width="20" height="19" border="0"></a></td>
|
|
<td width="30"><a href="references.html"><img src="theme/r_arr.gif" border="0"></a></td>
|
|
</tr>
|
|
</table>
|
|
<p dir="ltr">The <tt>Wave</tt> library contains several samples illustrating how to use the different features. This section describes these samples and its main characteristics. </p>
|
|
<h2>The <strong>cpp_tokens sample </strong></h2>
|
|
<p dir="ltr">The <tt>cpp_tokens</tt> sample dumps out the information contained within the tokens returned from the iterator supplied by the <tt>Wave</tt> library. It shows, how to use the <tt>Wave</tt> library in conjunction with custom lexer and custom token types. The lexer used within this sample is <tt>SLex</tt> <a href="references.html#slex">[5]</a> based, i.e. it <tt></tt> is feeded during runtime (at startup) with the token definitions (regular expressions) and generates a resulting DFA table. This table is used for token identification and is saved to disc afterwards to avoid the table generation process at the next program startup. The name of the file to which the DFA table is saved is <tt>wave_slex_lexer.dfa</tt>. </p>
|
|
<p dir="ltr">The main advantage of this <tt>SLex</tt> based lexer if compared to the default <tt>Re2C</tt> <a href="references.html#re2c">[3]</a> generated lexer is, that it provides not only the line information, where a particular token was recognized, but also the related column position. Otherwise the <tt>SLex</tt> based lexer is functionally fully compatible to the <tt>Re2C</tt> based one, i.e. you always may switch your application to use it, if you additionally need to get the column information back from the preprocessing. </p>
|
|
<p dir="ltr">Since no additional command line parameters are supported by this sample, it won't work well with include files, which aren't located in the same directory as the inspected input file. The command line syntax is straight forward:</p>
|
|
<pre> cpp_tokens input_file</pre>
|
|
<h2 dir="ltr">The list_includes sample </h2>
|
|
<p dir="ltr">The <tt>list_includes</tt> sample shows how the <tt>Wave</tt> library may be used to generate a include file dependency list for a particular input file. It completely depends on the default library configuration. The command line syntax for this sample is given below: </p>
|
|
<pre> Usage: list_includes [options] file ...:
|
|
-h [ --help ] : print out program usage (this message)
|
|
-v [ --version ] : print the version number
|
|
-I [ --path ] dir : specify additional include directory
|
|
-S [ --syspath ] dir : specify additional system include directory
|
|
</pre>
|
|
<p dir="ltr">Please note though, that this sample will output only those include file names, which are visible to the preprocessor, i.e. given the following code snippet, only one of the two include file directives is triggered during preprocess<!-- #BeginDate format:fcAm1m -->Saturday, January 24, 2004 19:15<!-- #EndDate -->ned</span><span class="special">(</span>INCLUDE_FILE_A<span class="special">)</span>
|
|
<span class="preprocessor"> #include</span> <span class="literal">"file_a.h"</span>
|
|
<span class="preprocessor"> #else</span>
|
|
<span class="preprocessor"> #include</span> <span class="literal">"file_b.h"</span>
|
|
<span class="preprocessor"> #endif</span>
|
|
</pre>
|
|
<p dir="ltr">Besides on the <tt>Wave</tt> library, this sample depends on the <tt>program_options</tt> library from <a href="mailto:ghost@cs.msu.su">Vladimir Prus</a>, recently adopted to Boost. Since this library isn't contained yet within Boost, you'll have to download it separately from <a href="http://boost-sandbox.sourceforge.net/program_options/">here</a>. It integrates well into the Boost build process, so no additional tools needed to use it with the Wave driver.</p>
|
|
<h2 dir="ltr">The wave sample</h2>
|
|
<p dir="ltr">Because of its general usefulness the <tt>wave</tt> sample isn't located in the sample directory of the library, but inside the tools directory of Boost. The wave sample is usable as a full fledged preprocessor executable
|
|
on top of any other C++ compiler. It outputs the textual representation of the
|
|
preprocessed tokens generated from a given input file. It is described in more details <a href="wave_driver.html">here</a>. </p>
|
|
<h2 dir="ltr">The waveidl sample </h2>
|
|
<p dir="ltr">The main point of the waveidl sample is to show, how a completely independent lexer type may be used in conjunction with the default token type of the <tt>Wave</tt> library. The lexer used in this sample is supposed to be used for an IDL language based preprocessor. It is based on the <tt>Re2C</tt> tool too, but recognizes a different set of tokens as the default C++ lexer contained within the <tt>Wave</tt> library. So this lexer does not recognize any keywords (except <tt>true</tt> and <tt>false</tt>, which are needed by the preprocessor itself). This is needed because there exist different IDL languages, where identifiers of one language may be keywords of others. Certainly this implies to postpone keyword identification after the preprocessing, but allows to use <tt>Wave</tt> for all of the IDL derivatives. </p>
|
|
<p dir="ltr">It is only possible to use the <tt>Wave</tt> library to write an IDL preprocessor, because the token sets for both languages are very similar. The tokens to be recognized by the <tt>waveidl</tt> IDL language preprocessor is nearly a complete subset of the full C++ token set. </p>
|
|
<p dir="ltr">The command line syntax usable for this sample is shown below:</p>
|
|
<pre> Usage: waveidl [options] [@config-file(s)] file:
|
|
|
|
|
|
Options allowed on the command line only:
|
|
-h [ --help ] : print out program usage (this message)
|
|
-v [ --version ] : print the version number
|
|
-c [ --copyright ] : print out the copyright statement
|
|
--config-file filepath : specify a config file (alternatively: @filepath)
|
|
|
|
|
|
Options allowed additionally in a config file:
|
|
-o [ --output ] path : specify a file to use for output instead of stdout
|
|
-I [ --include ] path : specify an additional include directory
|
|
-S [ --sysinclude ] syspath : specify an additional system include directory
|
|
-D [ --define ] macro[=[value]] : specify a macro to define
|
|
-P [ --predefine ] macro[=[value]] : specify a macro to predefine
|
|
-U [ --undefine ] macro : specify a macro to undefine
|
|
</pre>
|
|
<p dir="ltr">Besides on the <tt>Wave</tt> library, this sample depends on the <tt>program_options</tt> library from <a href="mailto:ghost@cs.msu.su">Vladimir Prus</a>, recently adopted to Boost. Since this library isn't contained yet within Boost, you'll have to download it separately from <a href="http://boost-sandbox.sourceforge.net/program_options/">here</a>. It integrates well into the Boost build process, so no additional tools needed to use it with the <tt>waveidl</tt> sample. </p>
|
|
<table border="0">
|
|
<tr>
|
|
<td width="10"></td>
|
|
<td width="30"><a href="index.html"><img src="theme/u_arr.gif" border="0"></a></td>
|
|
<td width="30"><a href="wave_driver.html"><img src="theme/l_arr.gif" width="20" height="19" border="0"></a></td>
|
|
<td width="30"><a href="references.html"><img src="theme/r_arr.gif" border="0"></a></td>
|
|
</tr>
|
|
</table>
|
|
<hr size="1">
|
|
<p class="copyright">Copyright © 2003-2004 Hartmut Kaiser<br>
|
|
<br>
|
|
<font size="2">Use, modification and distribution is subject to the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) </font> </p>
|
|
<span class="updated">Last updated:
|
|
<!-- #BeginDate format:fcAm1m -->Saturday, January 24, 2004 19:15<!-- #EndDate -->
|
|
</span>
|
|
<p> </p>
|
|
</body>
|
|
</html>
|
|
<!-- #BeginDate format:fcAm1m -->Saturday, January 24, 2004 19:15<!-- #EndDate --><!-- #BeginDate format:fcAm1m -->Saturday, January 24, 2004 19:15<!-- #EndDate --> |