Patman

Patman (Patch Manipulator) is a library for text file patching. It can also be used to 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.

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

Tests are executed with:

rake test