mucgly 0.0.1

data/lib/easyfile.rb

@@ -0,0 +1,720 @@
+# EasyFile module provides simplified file access management. The user
+# can refer all files by name, also the standard streams (STDIN,
+# STDOUT, STDERR). File names are unique since they are stored as
+# absolute path names. Also short names (relative/original) can be
+# used.
+#
+# The files are divided to Read and Write files. This simplifies the file
+# handling. Both files maintain the current line number.
+#
+# Read files has put-back feature. Arbitrary number of chars can be put
+# back to stream. This is helpful for parsers that has to perform
+# look-ahead.
+#
+# Write file have redirection support. Write file can be split into two
+# physical files if output requires copying to two or more files. Two
+# (or more ) Write files can also be joined, i.e. all writes are
+# directed to the joined file. Stream output can be suppressed.
+#
+# Examples:
+#   f = EasyFile::Read.open( 'myfile' )
+#   c = f.getc
+#   if c == "#"
+#      puts "Error in #{f.absname} on line #{f.line+1}: can't have '#' as first char..."
+#   end
+#
+#   f = EasyFile::Write.open( 'myfile' )
+#   f.branch( 'myfile2' )
+#   f.puts "foo\nbar\ndii"
+#   puts "Number of lines output to 'myfile' and 'myfile2': #{f.line}..."
+#
+
+module EasyFile
+
+
+    # Base class for Read and Write files.
+    class InOut
+
+        require 'stringio'
+
+        # Map symbolic file direction to mode character.
+        FILEMODEMAP = {
+            :read  => 'r',
+            :write => 'w', 
+        }
+
+        # Get absolute path for name.
+        #
+        # @param name [String] Relative file name.
+        # @return [String] Absolute path name for the file.
+        def InOut.abspath( name, mode )
+            if InOut.standard?( name )
+                name
+            elsif mode == :string
+                name
+            else
+                File.absolute_path( name )
+            end                
+        end
+
+        # Is name for standard IO?
+        #
+        # @param name [String] Relative file name.
+        def InOut.standard?( name )
+            case name
+            when "<STDIN>";  true
+            when "<STDOUT>"; true
+            when "<STDERR>"; true
+            else false
+            end
+        end
+
+
+        # Create EasyFile object and, open file with given name and
+        # mode.
+        #
+        # @param name [String] Relative path name for file.
+        # @param mode [Symbol] Access direction (:read/:write).
+        # @return [Read,Write] EasyFile handle.
+        def InOut.open( name, mode = :read )
+            file = InOut.create( name, mode )
+            file.open
+            file
+        end
+
+
+        # Create EasyFile object, no open. Open is performed
+        # separately.
+        #
+        # @param name [String] Relative path name for file.
+        # @param mode [Symbol] Access direction (:read/:write).
+        # @return [Read,Write] EasyFile handle to non-opened file (use
+        #                  "open").
+        def InOut.create( name, mode = :read )
+
+            absname = InOut.abspath( name, mode )
+
+            # Check if file exists already.
+            file = InOut.getByAbsname( absname )
+
+            if file
+                
+                file
+                
+            else
+
+                if mode == :read
+                    # file = Read.new( name, absname )
+                    file = Read.new( name, absname )
+                elsif mode == :write
+                    file = Write.new( name, absname )
+                elsif mode == :string
+                    file = String.new( name, absname )
+                else
+                    raise RuntimeError, "Unknown file mode \"#{mode.to_s}\"..."
+                end
+
+                InOut.add( file )
+
+            end
+
+            file
+
+        end
+
+
+        # Add InOut to filelist.
+        #
+        # @param io [InOut] Item to list.
+        # @return [InOut] Added item.
+        def InOut.add( io )
+            @@file_io[ io.absname ] = io
+        end
+
+
+        # Delete InOut from filelist.
+        #
+        # @param io [InOut] Item to list.
+        # @return [InOut] Added item.
+        def InOut.delete( io )
+            @@file_io.delete( io.absname )
+        end
+
+
+        # Get InOut from filelist by InOut handle.
+        #
+        # @param io [InOut] Item handle.
+        # @return [InOut] Added item.
+        def InOut.get( io )
+            @@file_io.getByAbsname( io.absname )
+        end
+
+
+        # Get InOut from filelist by absname.
+        #
+        # @param absname [InOut] Item absname.
+        # @return [InOut] Added item.
+        def InOut.getByAbsname( absname )
+            @@file_io[ absname ]
+        end
+
+
+        # Get EasyFile list.
+        #
+        # @return [Array<InOut>] List of all files.
+        def InOut.getList
+            @@file_io.values
+        end
+
+
+
+        # Relative path name for file.
+        attr_reader :filename
+
+        # Absolute path name for file.
+        attr_reader :absname
+        alias :id :absname
+
+        # File mode.
+        attr_reader :mode
+
+        # IO stream handle.
+        attr_accessor :io
+
+        # Parent EasyFile (push/pop).
+        attr_accessor :parent
+
+        # List of peer files (braches).
+        attr_accessor :peers
+
+        # Current line number (0,1,2...)
+        attr_accessor :line
+
+
+        # Create InOut object.
+        #
+        # @param mode [Symbol] File operation mode (:read, :write, :string).
+        # @param filename [String] Relative path file name.
+        # @param absname [String] Absolute path file name (generated
+        #                         if not given).
+        # @param io [IO] IO handle.
+        def initialize( mode, filename, absname = nil, io = nil )
+
+            @mode = mode
+
+            unless absname
+                absname = InOut.abspath( filename, mode )
+            end
+
+            # Set Primary IO.
+            @io = io
+
+            @filename = filename
+            @absname = absname
+
+            @peers = []
+            
+            @line = 0
+        end
+
+
+        # Open the stream.
+        def open
+
+            # Ensure single open.
+            return if self.io
+
+            if mode == :string
+                handle = StringIO.new
+            else
+                handle = File.open( @absname, FILEMODEMAP[ mode ] )
+            end
+
+            self.io = handle
+
+            self
+        end
+
+
+        # Close primary stream and peer streams.
+        def close
+
+            begin
+                unless InOut.standard?( @filename )
+                    @io.close if @io
+                    InOut.delete( self )
+                end
+            rescue IOError
+            end
+
+            @peers.each do |i|
+                i.close
+            end
+        end
+
+
+        private
+    
+        # Update line number status according to encountered newline
+        # chars.
+        #
+        # @param blk [String] Transfer chars.
+        # @param offset [Integer] Line number value Change step.
+        def updateLineNumber( blk, offset = 1 )
+            return nil unless blk
+            cnt = 0
+            blk.each_char do |c|
+                cnt += offset if c == "\n"
+            end
+            @line += cnt
+            blk
+        end
+
+    end
+
+
+
+    # Read file.
+    #
+    # Features:
+    # * Line counting.
+    # * Put-back char support.
+    class Read < InOut
+        
+
+        # Create EasyFile::Read object and, open file with given name.
+        #
+        # @param name [String] Relative path name for file.
+        # @return [Read] EasyFile handle.
+        def Read.open( name )
+            InOut.open( name, :read )
+        end
+
+
+        # Create Read object.
+        #
+        # @param filename [String] Relative path file name.
+        # @param absname [String] Absolute path file name (generated
+        #                         if not given).
+        # @param io [IO] IO handle.
+        def initialize( filename, absname = nil, io = nil )
+            super( :read, filename, absname, io )
+
+            @charbuffer = ""
+        end
+
+
+        # Get line.
+        def gets
+            begin
+                readline
+            rescue EOFError
+                nil
+            end
+        end
+
+
+        # Get line without newline.
+        def getschomp
+            line = gets
+            if line
+                line.chomp
+            else
+                line
+            end
+        end
+
+
+        # Get char (from IO or put-back buffer).
+        def getc
+            begin
+                getchar
+            rescue EOFError
+                nil
+            end
+        end
+        
+
+        # Get char (from IO or put-back buffer).
+        def getchar
+            updateLineNumber( getn( 1 ) )
+        end
+        
+
+        # Put-back char(s) (to put-back buffer).
+        def putback( c )
+            @charbuffer = c + @charbuffer
+            updateLineNumber( c, -1 )
+        end
+
+
+        # Read from IO.
+        def read( length = 1024 )
+            begin
+                readchars( length )
+            rescue EOFError
+                nil
+            end
+        end
+
+
+        # Read from IO with exception.
+        def readchars( length = 1024 )
+            updateLineNumber( getn( length ) )
+        end
+
+
+        def eof?
+            @charbuffer.empty? && @io.eof?
+        end
+
+        alias eof eof?
+
+
+        # Return Array of lines.
+        def readlines( chomp = false )
+            lines = []
+            if chomp
+                loop do
+                    line = getschomp
+                    break unless line
+                    lines.push line
+                end
+            else
+                loop do
+                    line = gets
+                    break unless line
+                    lines.push line
+                end
+            end
+            lines
+        end
+
+        # Iterate over lines.
+        #
+        # @yield Each line.
+        def each_line( &blk )
+            while ( line = gets )
+                yield line
+            end
+        end
+
+
+        # Iterate over lines with newline removed.
+        #
+        # @yield Each line.
+        def each_chomp( &blk )
+            while ( line = getschomp )
+                yield line
+            end
+        end
+
+
+        # Readline from file.
+        def readline
+            updateLineNumber( getline )
+        end
+
+
+
+        private
+
+        # Get n characters from stream.
+        def getn( n = 1 )
+
+            while n > @charbuffer.length
+                # Fill char buffer first.
+                break if @io.eof?
+                @charbuffer += @io.readline
+            end
+
+            ret = @charbuffer[ 0..(n-1) ]
+
+            raise EOFError if ret == ""
+
+            @charbuffer = @charbuffer[ n..-1 ]
+
+            unless @charbuffer
+                @charbuffer = ""
+            end
+
+            ret
+        end
+
+
+        # Get chars until newline.
+        def getline
+
+            if @charbuffer.empty?
+                @io.readline
+            else
+                ret = ""
+                nl = nil
+
+                # Check if newline in @charbuffer.
+                if ( nl = @charbuffer.index( "\n" ) )
+                    ret = @charbuffer[ 0..nl ]
+                    @charbuffer = @charbuffer[ nl+1..-1 ]
+                    ret
+                else
+                    if @io.eof?
+                        ret = @charbuffer
+                    else
+                        ret = @charbuffer + @io.readline
+                    end
+                    @charbuffer = ""
+                    ret
+                end
+            end
+        end
+
+    end
+
+
+
+    # Write file.
+    #
+    # Features:
+    # * Line counting.
+    # * Branching and joining.
+    # * Stream output suppression.
+    class Write < InOut
+
+        
+        # Create EasyFile::Write object and, open file with given name.
+        #
+        # @param name [String] Relative path name for file.
+        # @return [Write] EasyFile handle.
+        def Write.open( name )
+            InOut.open( name, :write )
+        end
+        
+
+        # Output is enabled.
+        attr_accessor :enabled
+
+        # Flush after each write.
+        attr_accessor :flush
+
+
+        # Create Write object.
+        #
+        # @param filename [String] Relative path file name.
+        # @param absname [String] Absolute path file name (generated
+        #                         if not given).
+        # @param io [IO] IO handle.
+        def initialize( filename, absname = nil, io = nil )
+            super( :write, filename, absname, io )
+            @enabled = true
+            @flush = false
+        end
+
+
+        # Write to all IOs.
+        def write( str )
+            if @enabled
+                updateLineNumber( str )
+                if @io
+                    @io.write( str )
+                    @io.flush if @flush
+                else
+                    # No output with nil stream.
+                end
+
+                @peers.each do |p|
+                    p.write( str )
+                end
+            end
+        end
+
+
+        # Write with automatic newline.
+        def puts( str )
+            nl = str[-1] == "\n" ? '' : "\n"
+            write( str + nl )
+        end
+
+
+        # Attach a file to existing Write stream i.e. writes to Write
+        # will be directed to attached file as well.
+        #
+        # @param fileid [String,Write] Filename or Write to add branching.
+        # @return [Write] Added peer.
+        def branch( fileid )
+
+            if fileid.class == String
+
+
+                # Get new IO.
+                fileio = Write.open( fileid )
+
+            else
+                
+                fileio = fileid
+
+            end
+
+            # Add if not already included.
+            @peers.push fileio unless @peers.index( fileio )
+
+            fileio
+        end
+
+        
+        # Join the given filestream to this stream. After joining the
+        # joined stream is output to same file as this stream.
+        #
+        # @param fileid [String,Write] Filename or Write to join.
+        # @return [Write] Joined peer.
+        def join( fileid )
+
+            if fileid.class == String
+                fileio = Write.create( fileid, nil )
+            else
+                fileio = fileid
+                fileio.close
+            end
+
+            fileio.io = @io
+            fileio
+        end
+
+        
+        # Suppress stream output.
+        #
+        # @param disable [Boolean] Disable or enable suppression.
+        def suppress( disable = true )
+            @enabled = !disable
+        end
+
+    end
+
+
+    # String buffer file.
+    #
+    # Features:
+    # * Putback.
+    class String < InOut
+
+        def method_missing( name, *args, &block )
+            @io.send( name, *args, &block )
+        end
+
+
+        # Create EasyFile::String object and, open file with given name.
+        #
+        # @param name [String] Name for file.
+        # @return [String] EasyFile handle.
+        def String.open( name )
+            InOut.open( name, :string )
+        end
+
+        # Create String object.
+        #
+        # @param filename [String] Name.
+        # @param absname [String] Absolute path file name (generated
+        #                         if not given).
+        # @param io [IO] IO handle.
+        def initialize( filename, absname = nil, io = nil )
+            super( :string, filename, absname, io )
+        end
+
+
+        # Put-back char(s) (to put-back buffer).
+        # @param c [String] Chars to put back to buffer.
+        def putback( c )
+            @io.string = c + @io.string[ @io.pos..-1 ]
+        end
+
+
+    end
+
+
+    class InOut
+
+        # Declare standards IOs.
+        @@file_io = {
+            "<STDIN>"  => Read.new(  '<STDIN>',  nil, STDIN ),
+            "<STDOUT>" => Write.new( '<STDOUT>', nil, STDOUT ),
+            "<STDERR>" => Write.new( '<STDERR>', nil, STDERR ),
+            # filename (absname) => InOut object
+        }        
+
+    end
+
+
+    # Stack of files.
+    module Stacked
+        attr_accessor :stack
+
+        instance_methods.each { |m| undef_method m unless m =~ /(^__|^send$|^object_id$)/ }
+
+        def setup( first = nil )
+            if first
+                @stack = [ first ]
+            else
+                @stack = []
+            end
+        end
+
+        def pop
+            if @stack.length > 1
+                @stack[-1].close
+                @stack.pop
+            end
+        end
+
+        def method_missing( name, *args, &block )
+            if [ :getc, :gets, :gets! ].index( name )
+                if @stack[-1].eof? && @automode
+                    pop
+                end
+            end
+            @stack[-1].send( name, *args, &block )
+        end
+
+        alias close pop
+    end
+
+
+    # Stack of Read files.
+    class ReadStack
+        include Stacked
+
+        # Automatically revert to lower file at EOF.
+        attr_accessor :automode
+
+        def initialize( name )
+            io = InOut.open( name, :read )
+            setup( io )
+            @automode = true
+        end
+
+        def push( name )
+            io = InOut.open( name, :read )
+            @stack.push io
+        end
+
+        def eof?
+            @stack.length == 1 && @stack[-1].eof?
+        end
+    end      
+
+
+    # Stack of Write files.
+    class WriteStack
+        include Stacked
+
+        def initialize( name )
+            io = InOut.open( name, :write )
+            setup( io )
+        end
+
+        def push( name )
+            io = InOut.open( name, :write )
+            @stack.push io
+        end
+
+    end      
+
+end