rupat 0.0.1

data/lib/rupat.rb

@@ -0,0 +1,912 @@
+# {RupatMod} contains the core functionality of {Rupat}.
+module RupatMod
+
+
+    # {Rupat} exception base class.
+    class RupatError < RuntimeError; end
+
+    # {Rupat} type error.
+    class RupatTypeError < RupatError; end
+
+    # {Rupat} searching error (for find functions).
+    class RupatSearchError < RupatError; end
+
+    # {Rupat} invalid line number error (for goto functions).
+    class RupatInvalidLineError < RupatError; end
+
+    # {Rupat} paste error.
+    class RupatPasteError < RupatError; end
+
+
+    # Array of lines including current content.
+    attr_reader :lines
+
+    # Copy buffer.
+    attr_reader :copybuf
+
+    # Original file reference.
+    attr_accessor :orgFile
+
+    # Created file reference.
+    attr_accessor :newFile
+
+
+    # Create new file based on given name (or IO stream).
+    #
+    # @param orgFile [String,File] Source file.
+    # @param newFile [String] Destination file.
+    def create( orgFile, newFile = nil )
+
+        @orgFile = orgFile
+        @newFile = newFile
+
+        if @orgFile.class == String
+            @lines = cleanlines( File.open( @orgFile ) )
+        else
+            @lines = cleanlines( @orgFile )
+        end
+
+        @curline = 0
+    end
+
+
+    # Create new file based on old. Original file is backupped.
+    #
+    # @param file [String,File] Source file.
+    # @param backup [Boolean] Create backup from the source (original)
+    #   file.
+    def edit( file, backup = true )
+        @backup = backup
+        create( file, file )
+    end
+
+
+    # Open a file in source mode (read only).
+    #
+    # @param file [String,File] Source file.
+    def open( file )
+        create( file, nil )
+    end
+
+
+    # Use set of lines for editing.
+    #
+    # @param lines [Array<String>] Lines to use.
+    def use( lines )
+        @lines = lines
+        @curline = 0
+    end
+
+
+    # Update the content using proc block.
+    #
+    # @yield blk Proc to execute on file content.
+    def update( &blk )
+        instance_eval &blk
+    end
+
+
+    # Perform operations in block, but revert back to original
+    # position after block completion.
+    #
+    # @yield blk Proc to execute on file content.
+    # @return [Object] Value of the block.
+    def excursion( &blk )
+        startline = @curline
+        ret = instance_eval( &blk )
+        @curline = startline
+        ret
+    end
+
+
+    # Goto line.
+    #
+    # @param line [Integer] Line to access.
+    # @return [Object] Self.
+    def goto( line = 0 )
+        @curline = line
+        normalizeCurline
+        self
+    end
+
+
+    # Goto (text editor) line.
+    #
+    # @param line [Integer] Line to access (updated to <line>-1).
+    # @return [Object] Self.
+    def goto1( line = 1 )
+        @curline = line-1
+        normalizeCurline
+        self
+    end
+
+
+    # Goto line without checking for line number validity.
+    #
+    # NOTE: User has to be aware of out-of-bound indexing issues.
+    #
+    # @param line [Integer] Line to access.
+    # @return [Object] Self.
+    def gotoForce( line = 0 )
+        @curline = line
+        self
+    end
+
+
+    # Goto first line.
+    #
+    # @return [Object] Self.
+    def gotoFirst
+        goto
+    end
+
+
+    # Goto last line.
+    #
+    # @return [Object] Self.
+    def gotoLast
+        @curline = @lines.length-1
+        self
+    end
+
+
+    # Goto line after last line. User can append content starting with
+    # this line.
+    #
+    # @return [Object] Self.
+    def gotoEnd
+        @curline = @lines.length
+        self
+    end
+
+
+    alias jump goto
+    alias jumpFirst gotoFirst
+    alias jumpLast gotoLast
+    alias jumpEnd gotoEnd
+
+
+    # Forward line (or more).
+    #
+    # @param count [Integer] Number of lines to step forwards.
+    # @return [Object] Self.
+    def forward( count = 1 )
+        @curline += count
+        normalizeCurline
+        self
+    end
+
+
+    # Backwards line (or more).
+    #
+    # @param count [Integer] Number of lines to step backwards.
+    # @return [Object] Self.
+    def backward( count = 1 )
+        @curline -= count
+        normalizeCurline
+        self
+    end
+
+
+    # Goto next line.
+    alias step forward
+    alias down forward
+    alias inc  forward
+
+
+    # Goto previous line.
+    alias up   backward
+    alias back backward
+    alias dec  backward
+
+
+    # Return next line number from current. Current line is not
+    # changed.
+    def next
+        @curline+1
+    end
+
+
+    # Return prev line number from current. Current line is not
+    # changed.
+    def prev
+        @curline-1
+    end
+
+
+    # Return current line number. First line is 0.
+    def line
+        @curline
+    end
+
+
+    # Return current line number + one, i.e. matches what for example an text
+    # editor would show. First line is 1.
+    def line1
+        @curline + 1
+    end
+
+
+    # Return last line number.
+    def last
+        length-1
+    end
+
+
+    # Find regexp forwards. Exception is generated, if pattern is not
+    # found.
+    #
+    # @param re [Regexp] Search pattern regexp.
+    # @return Self if found.
+    def findForward( re )
+        findCommon( re, true )
+    end
+
+
+    # Find regexp forward.
+    #
+    # @param re [Regexp] Search pattern regexp.
+    # @return Self if pattern found, nil otherwise.
+    def findForward?( re )
+        findCommon( re, true, false )
+    end
+
+
+    alias find findForward
+    alias find? findForward?
+
+    alias ffind findForward
+    alias ffind? findForward?
+
+
+    # Find regexp backwards. Exception is generated, if pattern is not
+    # found.
+    #
+    # @param re [Regexp] Search pattern regexp.
+    # @return Self if found.
+    def findBackward( re )
+        findCommon( re, false )
+    end
+
+
+    # Find regexp backward.
+    #
+    # @param re [Regexp] Search pattern regexp.
+    # @return Self if pattern found, nil otherwise.
+    def findBackward?( re )
+        findCommon( re, false, false )
+    end
+
+
+    alias bfind findBackward
+    alias bfind? findBackward?
+
+
+    # Return pair of line numbers that match the start/end
+    # regexps.
+    #
+    # @param re1 [Regexp] Range start marking Regexp.
+    # @param re2 [Regexp] Range end marking Regexp.
+    # @return [Integer,Integer] Range start/end tuplet.
+    def findBlock( re1, re2 )
+        findCommon( re1, true )
+        l1 = line
+        findCommon( re2, true )
+        l2 = line
+        [ l1, l2 ]
+    end
+
+
+    # Return lines content.
+    def []( range )
+        @lines[ range ]
+    end
+
+
+    # Return line content.
+    #
+    # @param line [Integer,NilClass] Indexed or current line.
+    # @return [String] Line content.
+    def get( line = nil )
+        @lines[ lineRef( line ) ]
+    end
+
+
+    # Return content of lines bounded by start/end markers
+    # (inclusive).
+    #
+    # @param l1 [Integer] Line marker 1 (See: {#linePairRef}).
+    # @param l2 [Integer] Line marker 2 (See: {#linePairRef}).
+    # @return [Array<String>] Line(s) content.
+    def getMany( l1 = nil, l2 = nil )
+        l1, l2 = linePairRef( l1, l2 )
+        @lines[ lineRef( l1 )..lineRef( l2 ) ]
+    end
+
+
+    # Store content of lines bounded by start/end markers
+    # (inclusive) to copy-buffer.
+    #
+    # @param l1 [Integer] Line marker 1 (See: {#linePairRef}).
+    # @param l2 [Integer] Line marker 2 (See: {#linePairRef}).
+    # @return [Array<String>] Line(s) content.
+    def copy( l1 = nil, l2 = nil )
+        l1, l2 = linePairRef( l1, l2 )
+        @copybuf = @lines[ lineRef( l1 )..lineRef( l2 ) ]
+        self
+    end
+
+
+    # Insert content from {#copybuf} (i.e. from {#copy}) to current
+    # position.
+    #
+    # @param err [Boolean] Generated exception for empty copybuf if
+    #   true.
+    def paste( err = true )
+        if err
+            unless @copybuf
+                raise RupatPasteError, "Copy buffer was empty!"
+            end
+        end
+        insertMany( @copybuf ) if @copybuf
+        self
+    end
+
+
+    # Set line content.
+    #
+    # @param str [String] New content for line.
+    # @param line [Integer] Index to modified line.
+    # @return [Object] Self.
+    def set( str, line = nil )
+        @lines[ lineRef( line ) ] = str
+        self
+    end
+
+
+    # Replace the current line content (i.e. get&set).
+    #
+    # @example
+    #   r.replace do |c|
+    #      c.gsub( /foo/, 'bar'
+    #   end
+    #
+    # @yield [get] Actions to perform for the content. Current content
+    #   is given as argument for the block.
+    # @return [Object] Self.
+    def replace( &action )
+        set( yield( get ) )
+        self
+    end
+
+
+    alias subs replace
+
+
+    # Insert a line at current position.
+    #
+    # @param str [String] Content for the inserted line.
+    # @return [Object] Self.
+    def insert( str = "" )
+        @lines.insert( @curline, str )
+        self
+    end
+
+
+    # Insert multiple lines at current position.
+    #
+    # @param content [Object] Content (See: {#manyLineContent}).
+    # @return [Object] Self.
+    def insertMany( content )
+        lines = manyLineContent( content )
+        excursion do
+            insert( lines[0] )
+            lines[1..-1].each do |s|
+                append( s )
+            end
+        end
+        self
+    end
+
+
+    # Append line to current position.
+    #
+    # @param str [String] Content for the appended line.
+    # @return [Object] Self.
+    def append( str = "" )
+        forward
+        @lines.insert( @curline, str )
+        self
+    end
+
+
+    # Append lines to current position.
+    #
+    # @param content [Object] Content (See: {#manyLineContent}).
+    # @return [Object] Self.
+    def appendMany( content )
+        lines = manyLineContent( content )
+        lines.each do |s|
+            append( s )
+        end
+        self
+    end
+
+
+    # Delete current line.
+    #
+    # @return [Object] Self.
+    def delete
+        @lines.delete_at( @curline )
+        self
+    end
+
+
+    # Delete current line N times.
+    #
+    # @param cnt [Integer] Number of lines to delete.
+    # @return [Object] Self.
+    def deleteMany( cnt = length )
+        cnt.times do
+            @lines.delete_at( @curline )
+        end
+        self
+    end
+
+
+    # Delete specified lines (inclusive). Save content to copy-buffer.
+    #
+    # @param l1 [Integer] Line marker 1 (See: {#linePairRef}).
+    # @param l2 [Integer] Line marker 2 (See: {#linePairRef}).
+    # @return [Object] Self.
+    def cut( l1 = nil, l2 = nil )
+        l1, l2 = linePairRef( l1, l2 )
+        @copybuf = []
+        cnt = l2-l1+1
+        cnt.times do
+            @copybuf.push @lines.delete_at( l1 )
+        end
+        self
+    end
+
+
+    # Insert file content to current position.
+    #
+    # @param file [String] Name of file to insert.
+    # @return [Object] Self.
+    def insertFile( file )
+        excursion do
+            lines = cleanlines( File.open( file ) )
+            insertMany( lines )
+        end
+        self
+    end
+
+
+    # Replace all occurance of re with str.
+    #
+    # @param re [Regexp] Regexp to match replace lines to.
+    # @param str [String] New content.
+    # @return [Object] Self.
+    def replaceAll( re, str )
+        @lines.each_index do |idx|
+            @lines[idx].gsub!( re, str )
+        end
+        self
+    end
+
+
+    # Replace all occurance of re with str within given range.
+    #
+    # @param re [Regexp] Regexp to match replace lines to.
+    # @param str [String] New content.
+    # @param l1 [Integer] Line marker 1 (See: {#linePairRef}).
+    # @param l2 [Integer] Line marker 2 (See: {#linePairRef}).
+    # @return [Object] Self.
+    def replaceWithin( re, str, l1 = nil, l2 = nil )
+        l1, l2 = linePairRef( l1, l2 )
+        @lines[l1..l2].each_index do |idx|
+            @lines[idx].gsub!( re, str )
+        end
+        self
+    end
+
+
+    # Return lines length.
+    def length
+        @lines.length
+    end
+
+
+    # Save edits and close file.
+    #
+    # @param file [String] File to save edits to.
+    # @return [String,NilClass] Backup file name if backup made,
+    #   otherwise nil.
+    def close( file = @newFile )
+
+        # Backup original file:
+        if @backup
+            time = Time.now.strftime( "%y%m%d_%H%M_%S" )
+
+            p = @orgFile.split( '/' )
+            backupFile = "#{p[0..-2].join('/')}/rupat_#{time}_#{p[-1]}"
+
+            File.rename( @orgFile, backupFile )
+            @orgFile = backupFile
+        end
+
+        save( file )
+
+        file.close if file.class == File
+
+        if @backup
+            backupFile
+        else
+            nil
+        end
+    end
+
+
+    # Save edits. File handle is not closed. Use {#close} for complete
+    # file closing.
+    #
+    # @param file [String,File] File to save edits to. If type is
+    #   File, stream is not closed.
+    def save( file = @newFile )
+
+        raise RupatTypeError, "Can't use \"nil\" for file save!" unless file
+
+        close = true
+
+        case file
+        when String
+            if @orgFile.class == String
+                # Open with original file permissions.
+                fh = File.open( file, "w", File.stat( @orgFile ).mode )
+            else
+                # Open with default file permissions.
+                fh = File.open( file, "w" )
+            end
+        when File
+            fh = file
+            close = false
+        else
+            raise RupatTypeError, "Can't use \"#{file.class}\" type for file save!"
+        end
+
+        @lines.each do |l|
+            fh.syswrite( l + "\n" )
+        end
+
+        fh.close if close
+    end
+
+
+    # Print file content.
+    #
+    # @param fh [IO] IO stream for printout.
+    def print( fh = STDOUT )
+        @lines.each do |l|
+            fh.puts l
+        end
+        self
+    end
+
+
+
+    private
+
+    # RupatMod Internal methods:
+
+    # Return non-newline lines from IO.
+    def cleanlines( io ) # :nodoc
+        lines = []
+        io.each_line do |line|
+            lines.push line.chomp
+        end
+        lines
+    end
+
+
+    # Find regular expression to selected direction.
+    def findCommon( re, forward = true, err = true ) # :nodoc:
+
+        tline = @curline
+        len = @lines.length
+
+        while forward ? tline < len : tline >= 0
+
+            if re =~ @lines[ tline ]
+                @curline = tline
+                return self
+            end
+
+            forward ? tline += 1 : tline -= 1
+        end
+
+        raise RupatSearchError, "#{@file}: Didn't find \"#{re}\"..." if err
+
+        nil
+    end
+
+
+    # Transform line reference.
+    #
+    # @param line [Integer] Line reference.
+    # @return [Integer] Current line if line is nil, otherwise line.
+    def lineRef( line )
+        if !line
+            @curline
+        else
+            line
+        end
+    end
+
+
+    # Fix a pair of line markers according to rules:
+    # * If both are nil, then pair is <current,current>.
+    # * If line2 is nil and line1 is positive, then pair is
+    #   <current,current+line1>, i.e. line1 is offset from current
+    #   line.
+    # * If line2 is nil and line1 is negative, then pair is
+    #   <current-line1,current>, i.e. line1 is offset from current
+    #   line for first marker.
+    # * If line1 and line2 are valid, then pair is <line1,line2>.
+    #
+    # @param line1 [Integer] First line reference.
+    # @param line2 [Integer] Second line reference.
+    # @return [Array<Integer>] Pair of valid line references.
+    def linePairRef( line1, line2 )
+        if !line1 && !line2
+            [ @curline, @curline ]
+        elsif line1 && !line2
+            if line1 >= 0
+                [ @curline, @curline+line1 ]
+            else
+                [ @curline+line1, @curline ]
+            end
+        else
+            [ line1, line2 ]
+        end
+    end
+
+
+    # Fix "many" content, i.e. if String, split it with "\n". If
+    # Array, pass it as it is (except chomp).
+    def manyLineContent( content )
+        case content
+        when String; content.split("\n")
+        when Array; content.collect{|i| i.chomp}
+        else raise RupatTypeError, "Unknown \"many\" line content!"
+        end
+    end
+
+
+    # Normalize curline. Raise exception if needed.
+    def normalizeCurline( err = true )
+        if @curline < 0
+            @curline = 0
+            raise RupatInvalidLineError, "Current line underflow..." if err
+        elsif @curline > @lines.length
+            @curline = @lines.length
+            raise RupatInvalidLineError, "Current line overflow..." if err
+        end
+    end
+
+end
+
+
+# Set of aliases to enable a very compact {Rupat} program.
+#
+# Aliases:
+# * l -> {RupatMod#line}
+# * n -> {RupatMod#forward}
+# * p -> {RupatMod#backward}
+# * j -> {RupatMod#goto}
+# * j1 -> {RupatMod#goto1}
+# * jl -> {RupatMod#gotoLast}
+# * je -> {RupatMod#gotoEnd}
+# * f -> {RupatMod#find?}
+# * ff -> {RupatMod#findForward?}
+# * fb -> {RupatMod#findBackward?}
+# * s -> {RupatMod#set}
+# * g -> {RupatMod#get}
+# * gm -> {RupatMod#getMany}
+# * cp -> {RupatMod#copy}
+# * pt -> {RupatMod#paste}
+# * r -> {RupatMod#replace}
+# * i -> {RupatMod#insert}
+# * im -> {RupatMod#insertMany}
+# * a -> {RupatMod#append}
+# * am -> {RupatMod#appendMany}
+# * d -> {RupatMod#delete}
+# * dm -> {RupatMod#deleteMany}
+# * ct -> {RupatMod#cut}
+# * ifi -> {RupatMod#insertFile}
+# * cl -> {RupatMod#close}
+# * sv -> {RupatMod#save}
+module RupatAlias
+
+    include RupatMod
+
+    alias l line
+    alias n forward
+    alias p backward
+    alias j goto
+    alias j1 goto1
+    alias jl gotoLast
+    alias je gotoEnd
+    alias f find?
+    alias ff findForward?
+    alias fb findBackward?
+    alias s set
+    alias g get
+    alias gm getMany
+    alias cp copy
+    alias pt paste
+    alias r replace
+    alias i insert
+    alias im insertMany
+    alias a append
+    alias am appendMany
+    alias d delete
+    alias dm deleteMany
+    alias ct cut
+    alias ifi insertFile
+    alias cl close
+    alias sv save
+end
+
+
+
+# = Rupat
+#
+# == Introduction
+#
+# {Rupat} is a Ruby Patching utility. It can be used to patch files or
+# for extracting information from files.
+#
+# {Rupat} includes:
+# [{RupatMod}] File content manipulation methods.
+# [{Rupat}] Class methods for Rupat script creation.
+# [Rupat command] Shell command for creating Rupat patch files.
+#
+# Typical {Rupat} script opens a file for editing, uses Regexp
+# searches to find the file position(s) to change, and adds/replaces
+# the content. File positions can be referred also line numbers.
+#
+# Rupat command can be used to create a patch script from diff
+# output. The generated script includes {RupatMod} commands which
+# implement the transformation.
+#
+# {Rupat} includes lines of the file in a line Array. {Rupat} keeps
+# track of the current line. Many editing commands use the current
+# line to specify the context for editing.
+#
+# {Rupat} has two parts: {Rupat} class and {RupatMod}. {Rupat} class
+# is a front end class to create {Rupat} instance for editing. {Rupat}
+# includes {RupatMod}. {RupatMod} can be used for other user classes
+# that benefit from lines editing.
+#
+# The basic flow is:
+# [open file] Source file can be opened in multiple editing modes.
+# [line manipulation] Search/jump to lines, extract and edit content
+#   (See: {RupatMod} for all access/editing methods).
+# [save file] Save the editing results to the source file or to a
+#             newly created file.
+#
+#
+# == Rupat class
+#
+# {Rupat} is a class that provides the default entry point to the
+# {RupatMod} module.
+#
+# The user can modify, duplicate, or just read file(s).
+# [update] Perform content update for a file, but without any backups.
+# [edit] Inplace editing with possibility to backup the original.
+# [open] Open file in read-only mode. Possibility to save the changes
+#        later exist.
+# [create] A named file is to be created from source file.
+#
+#
+# === Example usage:
+#
+#  # Open file for reading.
+#  r = Rupat.update( "report.txt" )
+#
+#  # Find line.
+#  r.find /cpp/
+#
+#  # Collect some lines.
+#  line = r.line
+#  data = 4.times.collect do |i|
+#      r.get( line + i )
+#  end
+#
+#  # Duplicate the lines collected.
+#  insertMany( data )
+#
+#  # Save changes.
+#  r.close
+#
+#
+# == Rupat command
+#
+# Rupat command is a simple shell command using {Rupat}. Main purpose
+# is to execute Rupat programs. It can also be used to generate a
+# {Rupat} patch from files with different content. When applied, the
+# patch transforms file1 to file2.
+class Rupat
+
+    include RupatMod
+
+
+    # Edit existing file inplace without backups.
+    #
+    # @param file [String,File] Source file.
+    def Rupat.update( file )
+        Rupat.edit( file, false )
+    end
+
+
+    # Open existing file for reading.
+    #
+    # @param file [String,File] Source file.
+    def Rupat.open( file )
+        r = Rupat.new
+        r.open( file )
+        r
+    end
+
+
+    # Open existing file for reading.
+    #
+    # @param file [String,File] Source file.
+    def Rupat.readonly( file )
+        Rupat.open( file )
+    end
+
+
+    # Edit existing file and by default make backup.
+    #
+    # @param file [String,File] Source file.
+    # @param backup [Boolean] Create backup from the source (original)
+    #   file.
+    def Rupat.edit( file, backup = true )
+        r = Rupat.new
+        r.edit( file, backup )
+        r
+    end
+
+
+    # Create new file based on old file.
+    #
+    # @param orgFile [String,File] Source file.
+    # @param newFile [String] Destination file.
+    def Rupat.create( orgFile, newFile )
+        r = Rupat.new
+        r.create( orgFile, newFile )
+        r
+    end
+
+
+    # Use set of lines for editing.
+    #
+    # @param lines [Array<String>] Lines to edit.
+    def Rupat.lines( lines )
+        r = Rupat.new
+        r.use( lines )
+        r
+    end
+
+
+    # Use short aliases from {RupatAlias} module.
+    def useAlias
+        Rupat.send( :include, RupatAlias )
+        self
+    end
+
+end
+
+require_relative 'version'