autodoc.git/ traditional_manual/ chapter_9.html

Branch: Tag:

2002-06-11

2002-06-11 15:18:33 by Johan Sundström <oyasumi@gmail.com>

Added a DeltatextIterator to get more fine-grained control over how much deltatext info gets parsed, instead of always doing it in one big gob.

Rev: lib/modules/Parser.pmod/RCS.pike:1.21

2030:    RCS file stored them - ie descending, most recent first, I'd assume    (rcsfile(5), of course, fails to state such irrelevant information).</p>   </dd></dl> - <dl><dt><h2 class='header'>Class <b class='ms datatype'>Parser.RCS.Revision</b></h2> + <dl><dt><h2 class='header'>Class <b class='ms datatype'>Parser.RCS.DeltatextIterator</b></h2>   </dt><dd><dl class='group--doc'>   <dt class='head--doc'>Description</dt> -  + <dd class='body--doc'><p>Iterator for the deltatext sections of the RCS file. Typical usage:</p> + </dd> + <dt class='head--doc'>Example</dt> + <dd class='example'><pre><p>string raw = Stdio.read_file(my_rcs_filename); +  Parser.RCS rcs = Parser.RCS(my_rcs_filename, 0); +  raw = rcs-&gt;parse_delta_sections(rcs-&gt;parse_admin_section(raw)); +  foreach(rcs-&gt;DeltatextIterator(raw); int n; Parser.RCS.Revision rev) +  do_something(rev);</p> + </pre></dd></dl> +  + <hr /> + <dl class='group--doc'> + <dt class='head--type'><span class='homogen--type'>Method</span> + <span class='homogen--name'><b>`!</b></span> + </dt> + <dd><p><code><code class='datatype'>bool</code> res = !<code class='class'>Parser.RCS.DeltatextIterator()</code></code></p></dd> +  + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'><p>1 if the iterator has processed all deltatext entries, 0 otherwise.</p> + </dd></dl> +  +  + <hr /> + <dl class='group--doc'> + <dt class='head--type'><span class='homogen--type'>Method</span> + <span class='homogen--name'><b>create</b></span> + </dt> + <dd><p><code><span class='object'>Parser.RCS.DeltatextIterator</span> <span class='class'>Parser.RCS.DeltatextIterator</span><b>(</b><code class='datatype'>string</code> <code class='argument'>deltatext_section</code>, <code class='datatype'>void</code>|<code class='datatype'>function</code>(<code class='datatype'>string</code>, <code class='datatype'>mixed</code> ... :<code class='datatype'>void</code>) <code class='argument'>progress_callback</code>, <code class='datatype'>void</code>|<code class='datatype'>array</code>(<code class='datatype'>mixed</code>) <code class='argument'>progress_callback_args</code><b>)</b></code></p></dd> +  + <dt class='head--doc'><span id='p-deltatext_section'></span>Parameter <code class='parameter'>deltatext_section</code></dt> + <dd></dd><dd class='body--doc'><p>the deltatext section of the RCS file in its entirety</p> + </dd> + <dt class='head--doc'><span id='p-progress_callback'></span>Parameter <code class='parameter'>progress_callback</code></dt> + <dd></dd><dd class='body--doc'><p>This optional callback is invoked with the revision of the +  deltatext about to be parsed (useful for progress indicators).</p> + </dd> + <dt class='head--doc'><span id='p-progress_callback_args'></span>Parameter <code class='parameter'>progress_callback_args</code></dt> + <dd></dd><dd class='body--doc'><p>Optional extra trailing arguments to be sent to <code>progress_callback</code></p> + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><p>the <tt>rcsfile(5)</tt> manpage outlines the sections of an RCS file</p> + </dd></dl> +  +  + <hr /> + <dl class='group--doc'> + <dt class='head--type'><span class='homogen--type'>Method</span> + <span class='homogen--name'><b>first</b></span> + </dt> + <dd><p><code><code class='datatype'>bool</code> <b><span class='method'>first</span>(</b><b>)</b></code></p></dd> +  + <dt class='head--doc'>Description</dt> + <dd class='body--doc'><p>Restart not implemented; always returns 0 (==failed)</p> + </dd></dl> +  +  + <hr /> + <dl class='group--doc'> + <dt class='head--type'><span class='homogen--type'>Method</span> + <span class='homogen--name'><b>index</b></span> + </dt> + <dd><p><code><code class='datatype'>int</code> <b><span class='method'>index</span>(</b><b>)</b></code></p></dd> +  + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'><p>the number of deltatext entries processed so far (0..N-1, N +  being the total number of revisions in the rcs file)</p> + </dd></dl> +  +  + <hr /> + <dl class='group--doc'> + <dt class='head--type'><span class='homogen--type'>Method</span> + <span class='homogen--name'><b>next</b></span> + </dt> + <dd><p><code><code class='datatype'>bool</code> <b><span class='method'>next</span>(</b><b>)</b></code></p></dd> +  + <dt class='head--doc'>Description</dt> + <dd class='body--doc'><p>like <code class='expr'><code>`+=</code>(1)</code>, but returns 0 if the iterator is finished</p> + </dd></dl> +  +  + <hr /> + <dl class='group--doc'> + <dt class='head--type'><span class='homogen--type'>Method</span> + <span class='homogen--name'><b>parse_deltatext_section</b></span> + </dt> + <dd><p><code><code class='modifier'>protected</code> <code class='datatype'>string</code> <b><span class='method'>parse_deltatext_section</span>(</b><code class='datatype'>string</code> <code class='argument'>raw</code><b>)</b></code></p></dd> +  + <dt class='head--doc'>Description</dt> + <dd class='body--doc'><p>Chops off the first deltatext section from the string <code>raw</code> and +  returns the rest of the string, or the value <code class='expr'>0</code> (zero) if +  we had already visited the final deltatext entry. The deltatext's +  data is stored destructively in the appropriate entry of the +  <code>revisions</code> array.</p> + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'><p><code>raw</code> must start with a deltatext entry for this method to work</p> + </dd><dt class='head--fixme'>FIXME</dt> + <dd class='body--fixme'><p>does not handle rcsfile(5) newphrase skipping</p> + </dd><dt class='head--fixme'>FIXME</dt> + <dd class='body--fixme'><p>if the rcs file is truncated, this method writes a descriptive +  error to stderr and then returns 0 - some nicer error handling +  wouldn't hurt</p> + </dd></dl> +  +  + <hr /> + <dl class='group--doc'> + <dt class='head--type'><span class='homogen--type'>Method</span> + <span class='homogen--name'><b>read_next</b></span> + </dt> + <dd><p><code><code class='modifier'>protected</code> <code class='datatype'>bool</code> <b><span class='method'>read_next</span>(</b><b>)</b></code></p></dd> +  + <dt class='head--doc'>Description</dt> + <dd class='body--doc'><p>drops the leading whitespace before next revision's deltatext +  entry and sets this_rev to the revision number we're about to read.</p> + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'><p>this method requires that <code>raw</code> starts with a valid deltatext entry</p> + </dd></dl> +  +  + <hr /> + <dl class='group--doc'> + <dt class='head--type'><span class='homogen--type'>Method</span> + <span class='homogen--name'><b>value</b></span> + </dt> + <dd><p><code><code class='object unresolved'>Revision</code> <b><span class='method'>value</span>(</b><b>)</b></code></p></dd> +  + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'><p>the <code>Revision</code> at whose deltatext data we are, updated with its info</p> + </dd></dl> + </dd></dl><dl><dt><h2 class='header'>Class <b class='ms datatype'>Parser.RCS.Revision</b></h2> + </dt><dd><dl class='group--doc'> + <dt class='head--doc'>Description</dt>   <dd class='body--doc'><p>All data tied to a particular revision of the file.</p>   </dd></dl>