bahuvrihi-external 0.3.1

data/lib/external/chunkable.rb

@@ -0,0 +1,131 @@
+module External
+  
+  # The Chunkable mixin provides methods for organizing a span or range
+  # into chunks no larger than a specified block size. For reference:
+  #
+  #   span    an array like: [start, length]
+  #   range   a Range like: start..end or start...(end - 1)
+  #
+  module Chunkable
+    
+    # The length of the chunkable object; 
+    # length must be set by the object.
+    attr_accessor :length
+    
+    # The default block size for chunking a chunkable
+    # object; default_blksize must be set by the object.
+    attr_accessor :default_blksize
+    
+    # Returns the default span: [0, length]
+    def default_span
+      [0, length]
+    end
+
+    # Breaks the input range or span into chunks of blksize or less.  
+    # The offset and length of each chunk will be provided to the 
+    # block, if given.
+    #
+    #   blksize           # => 100
+    #   chunk(0..250)     # => [[0,100],[100,100],[200,50]]
+    #
+    #   results = []
+    #   chunk([10,190]) {|offset, length| results << [offset, length]}
+    #   results           # => [[10,100],[110,90]]
+    #
+    def chunk(range_or_span=default_span, blksize=default_blksize)
+      return collect_results(:chunk, range_or_span) unless block_given?
+      
+      rbegin, rend = range_begin_and_end(range_or_span)
+      
+      # chunk the final range to make sure that no chunks  
+      # greater than blksize are returned
+      while rend - rbegin > blksize 
+        yield(rbegin, blksize)
+        rbegin += blksize
+      end
+      yield(rbegin, rend - rbegin) if rend - rbegin > 0
+    end
+    
+    # Breaks the input range or span into chunks of blksize or less,
+    # beginning from the end of the interval.  The offset and length 
+    # of each chunk will be provided to the block, if given.
+    #
+    #   blksize                   # => 100
+    #   reverse_chunk(0..250)     # => [[150,100],[50,100],[0,50]]
+    #
+    #   results = []
+    #   reverse_chunk([10,190]) {|offset, length| results << [offset, length]}
+    #   results                   # => [[100,100],[10,90]]
+    #
+    def reverse_chunk(range_or_span=default_span, blksize=default_blksize)
+      return collect_results(:reverse_chunk, range_or_span) unless block_given?
+    
+      rbegin, rend = range_begin_and_end(range_or_span)
+
+      # chunk the final range to make sure that no chunks  
+      # greater than blksize are returned
+      while rend - rbegin > blksize 
+        rend -= blksize
+        yield(rend, blksize)
+      end
+      yield(rbegin, rend - rbegin) if rend - rbegin > 0
+    end
+
+    module_function
+    
+    # Converts a range into an offset and length.  Negative values are
+    # counted back from self.length
+    #
+    #   length                # => 10
+    #   split_range(0..9)     # => [0,10]
+    #   split_range(0...9)    # => [0,9]
+    #
+    #   split_range(-1..9)    # => [9,1]
+    #   split_range(0..-1)    # => [0,10]
+    def split_range(range)
+      start, finish = range.begin, range.end
+      start += length if start < 0
+      finish += length if finish < 0
+      
+      [start, finish - start - (range.exclude_end? ? 1 : 0)]
+    end
+    
+    # The compliment to split_range; returns the span with a negative
+    # start index counted back from self.length.
+    #
+    #   length                # => 10
+    #   split_span([0, 10])   # => [0,10]
+    #   split_span([-1, 1])   # => [9,1]
+    #
+    def split_span(span)
+      span[0] += self.length if span[0] < 0
+      span
+    end
+    
+    # Returns the begining and end of a range or span.
+    # 
+    #   range_begin_and_end(0..10)    # => [0, 10]
+    #   range_begin_and_end(0...10)   # => [0, 9]
+    #   range_begin_and_end([0, 10])  # => [0, 10]
+    #
+    def range_begin_and_end(range_or_span)
+      rbegin, rend = range_or_span.kind_of?(Range) ? split_range(range_or_span) : split_span(range_or_span)
+      raise ArgumentError.new("negative offset specified: #{PP.singleline_pp(range_or_span,'')}") if rbegin < 0
+      rend += rbegin
+      
+      [rbegin, rend]
+    end
+
+    private
+    
+    # a utility method to collect the results of a method
+    # that requires a block.
+    def collect_results(method, args) # :nodoc:
+      results = []
+      send(method, args) do |*result|
+        results << result
+      end
+      results
+    end
+  end
+end

data/lib/external/enumerable.rb

@@ -0,0 +1,182 @@
+require 'enumerator'
+
+module External
+  
+  # An externalized implementation of Enumerable.  External::Enumerable
+  # requires several methods with the following functionality: 
+  # 
+  # each:: iterates over items in self
+  # another::  provide a another instance of self
+  # to_a:: converts self to an Array
+  #
+  module Enumerable
+    # Flag indicating whether to enumerate (ie collect,
+    # select, etc) into an array or into an instance
+    # of self.  In most cases enumerating to an array
+    # performs better, but enumerating to another
+    # instance of self may be desired for especially
+    # large collections.
+    attr_accessor :enumerate_to_a
+    
+    def all? # :yield: obj
+      # WARN -- no tests for this in test_array
+      each do |obj|
+        return false unless yield(obj)
+      end
+      true
+    end
+    
+    def any? # :yield: obj
+      # WARN -- no tests for this in test_array
+      each do |obj|
+        return true if yield(obj)
+      end
+      false
+    end
+    
+    def collect # :yield: item
+      if block_given?
+        another = enumerate_to_a ? [] : self.another
+        each do |item|
+          another << yield(item)
+        end
+        another
+      else
+        # Not sure if Enumerator works right for large externals...
+        Object::Enumerable::Enumerator.new(self)
+      end
+    end
+    
+    # def collect! # :yield: item
+    #   not_implemented
+    # end
+    
+    def detect(ifnone=nil) # :yield: obj
+      # WARN -- no tests for this in test_array
+      each do |obj|
+        return obj if yield(obj)
+      end
+      nil
+    end
+    
+    # def each_cons(n) # :yield:
+    #   not_implemented
+    # end
+    
+    # def each_slice(n) # :yield:
+    #   not_implemented
+    # end
+    
+    def each_with_index(&block)
+      chunk do |offset, length|
+        self[offset, length].each_with_index do |item, i|
+          yield(item, i + offset)
+        end
+      end
+    end
+    
+    def entries
+      to_a
+    end
+    
+    # def enum_cons(n)
+    #   not_implemented
+    # end
+    
+    # def enum_slice(n)
+    #   not_implemented
+    # end
+    
+    # def enum_with_index
+    #   not_implemented
+    # end
+    
+    def find(ifnone=nil, &block) # :yield: obj
+      # WARN -- no tests for this in test_array
+      detect(ifnone, &block)
+    end
+    
+    def find_all # :yield: obj
+      another = enumerate_to_a ? [] : self.another
+      each do |item|
+        another << item if yield(item)
+      end
+      another
+    end
+    
+    # def grep(pattern) # :yield: obj
+    #   not_implemented
+    # end
+    
+    def include?(obj)
+      each do |current|
+        return true if current == obj
+      end
+      false
+    end
+    
+    # def inject(init) # :yield: memo, obj
+    #   not_implemented
+    # end
+    
+    def map(&block) # :yield: item
+      collect(&block)
+    end
+    
+    # def map!(&block) # :yield: item
+    #   collect!(&block)
+    # end
+    
+    # def max # :yield: a,b
+    #   not_implemented
+    # end
+    
+    def member?(obj)
+      include?(obj)
+    end
+    
+    # def min # :yield: a,b
+    #   not_implemented
+    # end
+    
+    # def partition # :yield: obj
+    #   not_implemented
+    # end
+    
+    # def reject # :yield: item
+    #   not_implemented
+    # end
+    
+    # def reject! # :yield: item
+    #   not_implemented
+    # end
+    
+    def select(&block) # :yield: obj
+      find_all(&block)
+    end
+    
+    # def sort # :yield: a,b
+    #   not_implemented
+    # end
+    
+    # def sort! # :yield: a,b
+    #   not_implemented
+    # end
+    
+    # def sort_by # :yield: obj
+    #   not_implemented
+    # end
+    
+    # def to_a
+    #   not_implemented
+    # end
+    
+    # def to_set(klass=Set, *args, &block)
+    #   not_implemented
+    # end
+
+    # def zip(*arg) # :yield: arr
+    #   not_implemented
+    # end
+  end
+end

data/lib/external/io.rb

@@ -0,0 +1,163 @@
+require 'external/chunkable'
+require 'external/utils'
+
+autoload(:StringIO, 'stringio')
+autoload(:Tempfile, 'tempfile')
+autoload(:FileUtils, 'fileutils')
+
+module External
+  
+  # Adds functionality to an IO required by External. 
+  #
+  # IO adds/overrides the length accessor for getting the size of the IO contents.  
+  # Note that length is not automatically adjusted by write, for performance
+  # reasons.  length must be managed manually, or reset after writes using
+  # reset_length.
+  #
+  module Io
+    include Chunkable
+    
+    PATCHES = []
+    
+    # Add version-specific patches
+    case RUBY_VERSION
+    when /^1.8/ then require "external/patches/ruby_1_8_io"
+    end
+
+    # Add platform-specific patches
+    # case RUBY_PLATFORM
+    # when 'java' 
+    # end
+
+    def self.extended(base)
+      PATCHES.each {|patch| base.extend patch }
+      base.reset_length
+      base.default_blksize = 1024
+      base.binmode
+    end
+    
+    # Resets length to the length returned by Utils.length
+    def reset_length
+      self.length = Utils.length(self)
+    end
+
+    # Modified truncate that adjusts length
+    def truncate(n)
+      super
+      self.pos = n if self.pos > n
+      self.length = n
+    end
+    
+    #
+    def scan(range_or_span=default_span, blksize=default_blksize, carryover_limit=default_blksize)
+      carryover = 0
+      chunk(range_or_span, blksize) do |offset, length|
+        raise "carryover exceeds limit: #{carryover} (#{carryover_limit})" if carryover > carryover_limit
+        
+        scan_begin = offset - carryover
+        self.pos = scan_begin
+        string = self.read(length + carryover)
+        carryover = yield(scan_begin, string)
+      end
+      carryover
+    end
+    
+    # 
+    def insert(src, range=0..src.length, pos=nil)
+      self.pos = pos unless pos == nil
+      
+      start_pos = self.pos
+      length_written = 0
+
+      src.flush
+      src.pos = range.begin 
+      src.chunk(range) do |offset, length|
+        length_written += write(src.read(length))
+      end
+
+      end_pos = start_pos + length_written
+      self.length = end_pos if end_pos > self.length
+      length_written
+    end
+    
+    # 
+    def concat(src, range=0..src.length)
+      insert(src, range, length)
+    end
+    
+    #--
+    # it appears that as long as the io opening t.path closes,
+    # the tempfile will be deleted at the exit of the ruby 
+    # instance... otherwise it WILL NOT BE DELETED
+    # Make note of this in the documentation to be sure to close
+    # files if you start inserting because it may make tempfiles
+    #++
+    def copy(mode="r", range=0..length)
+      self.flush
+      
+      temp = Tempfile.new("copy")
+      temp.extend Io
+      temp.insert(self, range)
+      temp.close
+
+      cp = File.open(temp.path, mode)
+      cp.extend Io
+
+      if block_given?
+        begin
+          yield(cp)
+        ensure
+          cp.close unless cp.closed?
+          FileUtils.rm(cp.path) if File.exists?(cp.path)
+        end
+      else
+        cp
+      end
+    end
+    
+    # Quick comparision with another IO.  Returns true if
+    # another == self, or if both are file-type IOs and 
+    # their paths are equal.
+    def quick_compare(another)
+      self == another || (self.kind_of?(File) && another.kind_of?(File) && self.path == another.path)
+    end
+
+    # Sort compare (ie <=>) with another IO, behaving like 
+    # a comparison between the full string contents of self 
+    # and another.  This obviously can be a long operation
+    # if it requires the full read of two large IO objects.
+    def sort_compare(another, blksize=default_blksize)
+      # equal in comparison if the ios are equal
+      return 0 if quick_compare(another)
+      
+      self.flush
+      self.reset_length
+      
+      another.flush
+      another.reset_length
+      
+      if another.length > self.length
+        return -1
+      elsif self.length < another.length
+        return 1
+      else
+        self.pos = 0
+        another.pos = 0
+
+        sa = sb = nil
+        while sa == sb
+          sa = self.read(blksize)
+          sb = another.read(blksize)
+          break if sa.nil? || sb.nil?
+        end
+
+        sa.to_s <=> sb.to_s
+      end
+    end
+    
+    # Alias for sort_compare.
+    def <=>(another)
+      sort_compare(another)
+    end
+  end
+end