ceph/src/boost/libs/spirit/classic/doc/position_iterator.html

   1 <html>
   2 <head>
   3 <title>Position Iterator</title>
   4 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
   5 <link rel="stylesheet" href="theme/style.css" type="text/css">
   6 </head>
   7
   8 <body>
   9 <table width="100%" border="0" background="theme/bkd2.gif" cellspacing="2">
  10   <tr>
  11     <td width="10">
  12     </td>
  13     <td width="85%"> <font size="6" face="Verdana, Arial, Helvetica, sans-serif"><b>Position
  14       Iterator</b></font> </td>
  15     <td width="112"><a href="http://spirit.sf.net"><img src="theme/spirit.gif" width="112" height="48" align="right" border="0"></a></td>
  16   </tr>
  17 </table>
  18 <br>
  19 <table border="0">
  20   <tr>
  21     <td width="10"></td>
  22     <td width="30"><a href="../index.html"><img src="theme/u_arr.gif" border="0"></a></td>
  23     <td width="30"><a href="file_iterator.html"><img src="theme/l_arr.gif" border="0"></a></td>
  24     <td width="30"><a href="debugging.html"><img src="theme/r_arr.gif" border="0"></a></td>
  25   </tr>
  26 </table>
  27 <p>Often, when writing a parser that is able to detect errors in the format of
  28   the input stream, we want it to communicate to the user where the error happened
  29   within that input. The classic example is when writing a compiler or interpreter
  30   that detects syntactical errors in the parsed program, indicating the line number
  31   and maybe even the position within the line where the error was found.</p>
  32 <p> The class position_iterator is a tool provided within Spirit that allows parser
  33   writers to easily implement this functionality. The concept is quite simple:
  34   this class is an iterator wrapper that keeps track of the current position within
  35   the file, including current file, line and column. It requires a single template
  36   parameter, which should be the type of the iterator that is to be wrapped.</p>
  37 <p> To use it, you'll need to add the following include:</p>
  38 <pre>
  39     <code><span class=preprocessor>#include </span><span class=special>&lt;</span><span class=identifier>boost</span><span class=special>/</span><span class=identifier>spirit</span><span class=special>/</span><span class=identifier>iterator</span><span class=special>/</span><span class=identifier>position_iterator</span><span class=special>.</span><span class=identifier>hpp</span><span class=special>&gt;</span></code></pre>
  40 <p> Or include all the iterators in Spirit:</p>
  41 <pre>
  42     <code><span class=preprocessor>#include </span><span class=special>&lt;</span><span class=identifier>boost</span><span class=special>/</span><span class=identifier>spirit</span><span class=special>/</span><span class=identifier>iterator</span><span class=special>.</span><span class=identifier>hpp</span><span class=special>&gt;</span></code></pre>
  43 <p> To construct the wrapper, it needs both the begin and end iterators of the
  44   input sequence, and the file name of the input sequence. Optionally, you can
  45   also specify the starting line and column numbers, which default to 1. Default
  46   construction, with no parameters, creates a generic end-of-sequence iterator,
  47   in a similar manner as it's done in the stream operators of the standard C++
  48   library.</p>
  49 <p> The wrapped iterator must belong to the input or forward iterator category,
  50   and the position_iterator just inherits that category.</p>
  51 <p> For example, to create begin and end positional iterators from an input C-
  52   string, you'd use:</p>
  53 <pre>
  54     <code><span class=keyword>char </span><span class=keyword>const</span><span class=special>* </span><span class=identifier>inputstring </span><span class=special>= </span><span class=string>&quot;...&quot;</span><span class=special>;
  55     </span><span class=keyword>typedef </span><span class=identifier>position_iterator</span><span class=special>&lt;</span><span class=keyword>char </span><span class=keyword>const</span><span class=special>*&gt; </span><span class=identifier>iterator_t</span><span class=special>;
  56
  57     </span><span class=identifier>iterator_t </span><span class=identifier>begin</span><span class=special>(</span><span class=identifier>inputstring</span><span class=special>, </span><span class=identifier>inputstring</span><span class=special>+</span><span class=identifier>strlen</span><span class=special>(</span><span class=identifier>inputstring</span><span class=special>));
  58     </span><span class=identifier>iterator_t </span><span class=identifier>end</span><span class=special>;</span></code></pre>
  59 <a name="operations"></a>
  60 <h2>Operations</h2>
  61 <pre>
  62     <code><span class=keyword>void </span><span class=identifier>set_position</span><span class=special>(</span><span class=identifier>file_position </span><span class=keyword>const</span><span class=special>&amp;);</span></code></pre>
  63 <p> Call this function when you need to change the current position stored in
  64   the iterator. For example, if parsing C-style #include directives, the included
  65   file's input must be marked by restarting the file and column to 1 and 1 and
  66   the name to the new file's name.<br>
  67 </p>
  68 <pre>
  69     <code><span class=identifier>file_position </span><span class=keyword>const</span><span class=special>&amp; </span><span class=identifier>get_position</span><span class=special>() </span><span class=keyword>const</span><span class=special>;</span></code></pre>
  70 <p> Call this function to retrieve the current position.</p>
  71 <pre>
  72     <code><span class=keyword>void </span><span class=identifier>set_tabchars</span><span class=special>(</span><span class=keyword>int</span><span class=special>);</span></code></pre>
  73 <p> Call this to set the number of tabs per character. This value is necessary
  74   to correctly track the column number.<br>
  75 </p>
  76 <p> <a name="file_position"></a> </p>
  77 <h2>file_position</h2>
  78 <p> file_position is a structure that holds the position within a file. Its fields
  79   are:</p>
  80 <table width="90%" border="0" align="center">
  81   <tr>
  82     <td class="table_title" colspan="2">file_position fields</td>
  83   </tr>
  84   <tr>
  85     <td class="table_cells" width="26%"><code><span class=identifier>std</span><span class=special>::</span><span class=identifier>string
  86       </span><span class=identifier>file</span><span class=special>;</span></code></td>
  87     <td class="table_cells" width="74%">Name of the file. Hopefully a full pathname</td>
  88   </tr>
  89   <tr>
  90     <td class="table_cells" width="26%"><code><span class=keyword>int</span><span class=identifier>
  91       line</span><span class=special>;</span></code></td>
  92     <td class="table_cells" width="74%">Line number within the file. By default,
  93       the first line is number 1</td>
  94   </tr>
  95   <tr>
  96     <td class="table_cells" width="26%"><code><span class=keyword>int </span><span class=identifier>column</span><span class=special>;</span></code></td>
  97     <td class="table_cells" width="74%">Column position within the file. The first
  98       column is 1</td>
  99   </tr>
 100 </table>
 101 <p><img src="theme/lens.gif" width="15" height="16"> See <a href="../example/fundamental/position_iterator/position_iterator.cpp">position_iterator.cpp</a> for a compilable example. This is part of the Spirit distribution.</p>
 102 <table border="0">
 103   <tr>
 104     <td width="10"></td>
 105     <td width="30"><a href="../index.html"><img src="theme/u_arr.gif" border="0"></a></td>
 106     <td width="30"><a href="file_iterator.html"><img src="theme/l_arr.gif" border="0"></a></td>
 107     <td width="30"><a href="debugging.html"><img src="theme/r_arr.gif" border="0"></a></td>
 108   </tr>
 109 </table>
 110 <hr size="1">
 111 <p class="copyright">Copyright &copy; 2002 Juan Carlos Arevalo-Baeza<br>
 112   <br>
 113   <font size="2">Use, modification and distribution is subject to the Boost Software
 114     License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
 115     http://www.boost.org/LICENSE_1_0.txt) </font> </p>
 116 <p class="copyright">&nbsp; </p>
 117 <p>&nbsp;</p>
 118 </body>
 119 </html>