patman 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a462d68bd477c77e89a9e41ca37b8d2c06160be4
-  data.tar.gz: bda836ee168588b0ce7756c9da2ec2cfabf8758f
+  metadata.gz: b68fa454daf8ce04aeb42aabc60f2de3021db888
+  data.tar.gz: '068b4d5320b270d4bc82cd73a1e023adfde8b709'
 SHA512:
-  metadata.gz: 7ccc9b4edce5bc4b0dfa4194460e7e8631406c84d13aa3ecbefc0a69a273901ef144351dbcf5da1b0e1d4db5a0c91feef823867585bb96c69ec88b83092ec156
-  data.tar.gz: cd15a3a96b9b99142ad34c7b8416a9ade3cc1083f6850c67d1cf4b783b2fd5a9658642481e5ed6c2f7f51546f3c01ae3c6c447c4bfb8b46d64ee03e510d5dc20
+  metadata.gz: cc7654dc6ec333b5a95af55035c62318e0239068dcd67084e72545939fb858a78eccaa6e3e1d816e5a3122a13fda86e05055150f679169225fb2c350bf8663ca
+  data.tar.gz: 0d95179441b056dbe816802d44873cb56ad9c6cac734f391dd9cb14d059307beed47d86ff3d7ea355ebf764bcc12a68eef4e9e89a2325902a5396fb4da9c1fb8

data/CHANGELOG.rdoc

@@ -1,5 +1,7 @@
 = Version history
 
+[0.0.3] Documentation improvements.
+
 [0.0.2] Fix: view_ln did not tolerate "%" char in the line.
 
 [0.0.1] Initial version.

data/README.rdoc

@@ -1,14 +1,113 @@
 = Patman
 
-== Description
+{Patman} (Patch Manipulator) is a library for text file patching. It
+can also be used to extract information from files.
 
-{Patman} is library for text file patching. It can also be used to
-just extract information from files.
+== Documentation
 
+Here is a brief overview of {Patman}. Please refer to API
+documentation for complete view. Also refer to tests for multiple ways
+of how to use {Patman}.
 
-== Documentation
+Typical {Patman} 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.
+
+    r = Patman.read( "edit_me.txt" )  
+    r.line 10
+    r.delete
+    r.write
+
+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,
+{Patman} 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.
+
+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.
+
+    curline = r.line
+    if curline > 5
+        r.step -2
+    else
+        r.line 10
+
+Current line content is returned by "get" and it can be set with
+"set" method. Current line content can be replaced with "sub".
+
+    r.set( r.get + "..." )
+
+{Patman} includes many query commands: line, lines, [], get, find,
+get_range, get_for. They all return the queried item. All other
+methods return {Patman} object itself, hence many {Patman} methods
+can be "chained".
+
+    Patman.read( "edit_me.txt" ).line( 2 ).delete.write
+
+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. {Patman} jumps to that
+line.
+
+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.
+
+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".
+
+    r.mark :origin
+    r.step 10
+    r.delete
+    r.unmark :origin
+
+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.
+
+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.
+
+
+== Example session
+
+    # Open file for reading.
+    r = Patman.read( "report.txt" )
+
+    # Backup file and find next line with "error", i.e. method chaining.
+    r.copy( "report.txt.org" ).find( /error/ )
+
+    # Collect some lines.
+    data = 4.times.collect do |i|
+        r.ref( r.line + i )
+    end
+
+    # Duplicate the lines collected.
+    r.insert( data )
+
+    # Move to line 9.
+    r.line 9
+
+    # Append " Hello" to the end of current line.
+    r.set( r.get + " Hello" )
+
+    # Save changes.
+    r.write
+
+
+== Testing 
 
-Main documentation is generated from source (See: {Patman}).
+Tests are executed with:
 
-Test files in "test" directory includes multiple ways of how to use
-{Patman}.
+    rake test

data/doc/Patman/PatmanError.html

@@ -129,7 +129,7 @@
 </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>

data/doc/Patman/PatmanFileError.html

@@ -133,7 +133,7 @@
 </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>

data/doc/Patman/PatmanSearchError.html

@@ -133,7 +133,7 @@
 </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>