index.html in patman-0.0.3

- old
+ new
@@ -62,24 +62,125 @@
     <iframe id="search_frame"></iframe>
 
     <div id="content"><div id='filecontents'>
 <h1 id="label-Patman">Patman</h1>
 
-<h2 id="label-Description">Description</h2>
+<p><span class='object_link'><a href="Patman.html" title="Patman (class)">Patman</a></span> (Patch Manipulator) is a library for text file patching. It can
+also be used to extract information from files.</p>
 
-<p><span class='object_link'><a href="Patman.html" title="Patman (class)">Patman</a></span> is library for text file patching. It can also be used to just
-extract information from files.</p>
-
 <h2 id="label-Documentation">Documentation</h2>
 
-<p>Main documentation is generated from source (See: <span class='object_link'><a href="Patman.html" title="Patman (class)">Patman</a></span>).</p>
-
-<p>Test files in “test” directory includes multiple ways of how to use
+<p>Here is a brief overview of <span class='object_link'><a href="Patman.html" title="Patman (class)">Patman</a></span>. Please refer to API documentation for
+complete view. Also refer to tests for multiple ways of how to use
 <span class='object_link'><a href="Patman.html" title="Patman (class)">Patman</a></span>.</p>
+
+<p>Typical <span class='object_link'><a href="Patman.html" title="Patman (class)">Patman</a></span> script opens files for editing. File is read into the
+library as content line by line. User finds the place for editing either
+with Regexp searches or with direct line numbers. The file content is
+edited by adding, removing, or replacing lines. When all edits are done,
+the updated file content is written to disk.</p>
+
+<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_r'>r</span> <span class='op'>=</span> <span class='const'>Patman</span><span class='period'>.</span><span class='id identifier rubyid_read'>read</span><span class='lparen'>(</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>edit_me.txt</span><span class='tstring_end'>&quot;</span></span> <span class='rparen'>)</span>  
+<span class='id identifier rubyid_r'>r</span><span class='period'>.</span><span class='id identifier rubyid_line'>line</span> <span class='int'>10</span>
+<span class='id identifier rubyid_r'>r</span><span class='period'>.</span><span class='id identifier rubyid_delete'>delete</span>
+<span class='id identifier rubyid_r'>r</span><span class='period'>.</span><span class='id identifier rubyid_write'>write</span>
+</code></pre>
+
+<p>All editing commands refer to the “current position”. Current position is
+returned by “line” method. Positions refer to lines that have content. Line
+numbers start from 1. If user wants append to the end of file, then user
+should jump to last line, with “lastline” method, and then issue “append”.
+It is also possible to jump to arbitrary lines, <span class='object_link'><a href="Patman.html" title="Patman (class)">Patman</a></span> does not prevent
+this. The line positions are just used as an index to Array. For example
+negative line number will refer from end towards beginning in content.</p>
+
+<p>Position can be explicitly changed with “line”, “step”, “firstline”, or
+“lastline” methods (commands). “find” changes position if the pattern is
+found in selected direction. “append” changes position implicitly with
+every call.</p>
+
+<pre class="code ruby"><code class="ruby">curline = r.line
+if curline &gt; 5
+    r.step -2
+else
+    r.line 10</code></pre>
+
+<p>Current line content is returned by “get” and it can be set with “set”
+method. Current line content can be replaced with “sub”.</p>
+
+<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_r'>r</span><span class='period'>.</span><span class='id identifier rubyid_set'>set</span><span class='lparen'>(</span> <span class='id identifier rubyid_r'>r</span><span class='period'>.</span><span class='id identifier rubyid_get'>get</span> <span class='op'>+</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>...</span><span class='tstring_end'>&quot;</span></span> <span class='rparen'>)</span>
+</code></pre>
+
+<p><span class='object_link'><a href="Patman.html" title="Patman (class)">Patman</a></span> includes many query commands: line, lines, [], get, find,
+get_range, get_for. They all return the queried item. All other methods
+return <span class='object_link'><a href="Patman.html" title="Patman (class)">Patman</a></span> object itself, hence many <span class='object_link'><a href="Patman.html" title="Patman (class)">Patman</a></span> methods can be
+“chained”.</p>
+
+<pre class="code ruby"><code class="ruby"><span class='const'>Patman</span><span class='period'>.</span><span class='id identifier rubyid_read'>read</span><span class='lparen'>(</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>edit_me.txt</span><span class='tstring_end'>&quot;</span></span> <span class='rparen'>)</span><span class='period'>.</span><span class='id identifier rubyid_line'>line</span><span class='lparen'>(</span> <span class='int'>2</span> <span class='rparen'>)</span><span class='period'>.</span><span class='id identifier rubyid_delete'>delete</span><span class='period'>.</span><span class='id identifier rubyid_write'>write</span>
+</code></pre>
+
+<p>Block commands perform commands over a range of lines. Block commands are:
+do_all, do_range, and do_for. These retain the original position, but the
+final position is stored (actually one after) and it can be activated by
+calling “blockline” method, i.e. <span class='object_link'><a href="Patman.html" title="Patman (class)">Patman</a></span> jumps to that line.</p>
+
+<p>Block commands take a pre-defined number of lines to process. Note that, if
+user deletes lines in block action, the outcome is most likely not what the
+user expects.</p>
+
+<p>Mark feature can be used if user wants to return back to original position
+after changes. Mark features includes a “default mark” and “named marks”.</p>
+
+<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_r'>r</span><span class='period'>.</span><span class='id identifier rubyid_mark'>mark</span> <span class='symbol'>:origin</span>
+<span class='id identifier rubyid_r'>r</span><span class='period'>.</span><span class='id identifier rubyid_step'>step</span> <span class='int'>10</span>
+<span class='id identifier rubyid_r'>r</span><span class='period'>.</span><span class='id identifier rubyid_delete'>delete</span>
+<span class='id identifier rubyid_r'>r</span><span class='period'>.</span><span class='id identifier rubyid_unmark'>unmark</span> <span class='symbol'>:origin</span>
+</code></pre>
+
+<p>For debugging purposes it is good to see line content. “view” and “view_ln”
+can be used to view line content either without or with line numbers
+respectively.</p>
+
+<p>No changes are stored to disk unless “write” is called. If user want to
+create a “backup” of the edited file, the “copy” method can be used before
+any editing commands have been applied.</p>
+
+<h2 id="label-Example+session">Example session</h2>
+
+<pre class="code ruby"><code class="ruby"><span class='comment'># Open file for reading.
+</span><span class='id identifier rubyid_r'>r</span> <span class='op'>=</span> <span class='const'>Patman</span><span class='period'>.</span><span class='id identifier rubyid_read'>read</span><span class='lparen'>(</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>report.txt</span><span class='tstring_end'>&quot;</span></span> <span class='rparen'>)</span>
+
+<span class='comment'># Backup file and find next line with &quot;error&quot;, i.e. method chaining.
+</span><span class='id identifier rubyid_r'>r</span><span class='period'>.</span><span class='id identifier rubyid_copy'>copy</span><span class='lparen'>(</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>report.txt.org</span><span class='tstring_end'>&quot;</span></span> <span class='rparen'>)</span><span class='period'>.</span><span class='id identifier rubyid_find'>find</span><span class='lparen'>(</span> <span class='tstring'><span class='regexp_beg'>/</span><span class='tstring_content'>error</span><span class='regexp_end'>/</span></span> <span class='rparen'>)</span>
+
+<span class='comment'># Collect some lines.
+</span><span class='id identifier rubyid_data'>data</span> <span class='op'>=</span> <span class='int'>4</span><span class='period'>.</span><span class='id identifier rubyid_times'>times</span><span class='period'>.</span><span class='id identifier rubyid_collect'>collect</span> <span class='kw'>do</span> <span class='op'>|</span><span class='id identifier rubyid_i'>i</span><span class='op'>|</span>
+    <span class='id identifier rubyid_r'>r</span><span class='period'>.</span><span class='id identifier rubyid_ref'>ref</span><span class='lparen'>(</span> <span class='id identifier rubyid_r'>r</span><span class='period'>.</span><span class='id identifier rubyid_line'>line</span> <span class='op'>+</span> <span class='id identifier rubyid_i'>i</span> <span class='rparen'>)</span>
+<span class='kw'>end</span>
+
+<span class='comment'># Duplicate the lines collected.
+</span><span class='id identifier rubyid_r'>r</span><span class='period'>.</span><span class='id identifier rubyid_insert'>insert</span><span class='lparen'>(</span> <span class='id identifier rubyid_data'>data</span> <span class='rparen'>)</span>
+
+<span class='comment'># Move to line 9.
+</span><span class='id identifier rubyid_r'>r</span><span class='period'>.</span><span class='id identifier rubyid_line'>line</span> <span class='int'>9</span>
+
+<span class='comment'># Append &quot; Hello&quot; to the end of current line.
+</span><span class='id identifier rubyid_r'>r</span><span class='period'>.</span><span class='id identifier rubyid_set'>set</span><span class='lparen'>(</span> <span class='id identifier rubyid_r'>r</span><span class='period'>.</span><span class='id identifier rubyid_get'>get</span> <span class='op'>+</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'> Hello</span><span class='tstring_end'>&quot;</span></span> <span class='rparen'>)</span>
+
+<span class='comment'># Save changes.
+</span><span class='id identifier rubyid_r'>r</span><span class='period'>.</span><span class='id identifier rubyid_write'>write</span>
+</code></pre>
+
+<h2 id="label-Testing+">Testing </h2>
+
+<p>Tests are executed with:</p>
+
+<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_rake'>rake</span> <span class='id identifier rubyid_test'>test</span>
+</code></pre>
 </div></div>
 
     <div id="footer">
-  Generated on Sat Dec 23 16:47:41 2017 by
+  Generated on Tue Mar 20 20:43:44 2018 by
   <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.8.7.6 (ruby-2.3.3).
 </div>
 
   </body>
\ No newline at end of file