rubyexcel 0.0.5 → 0.0.6

data/lib/rubyexcel/address.rb

@@ -1,15 +1,40 @@
 module RubyExcel
 
+  #
+  #Provides address translation methods to RubyExcel's classes
+  #
+  
   module Address
   
+    #
+    # Translates an address to a column index
+    #
+    # @param [String] address the address to translate
+    # @return [Fixnum] the column index
+    #
+    
     def address_to_col_index( address )
       col_index( column_id( address ) )
     end
     
+    #
+    # Translates an address to indices
+    #
+    # @param [String] address the address to translate
+    # @return [Array<Fixnum>] row index, column index
+    #
+    
     def address_to_indices( address )
       [ row_id( address ), address_to_col_index( address ) ]
     end
     
+    #
+    # Translates a column id to an index
+    #
+    # @param [String] letter the column id to translate
+    # @return [Fixnum] the corresponding index
+    #
+    
     def col_index( letter )
       return letter if letter.is_a? Fixnum
       letter !~ /[^A-Z]/ && [1,2,3].include?( letter.length ) or fail ArgumentError, "Invalid column reference: #{ letter }"
@@ -17,16 +42,37 @@ module RubyExcel
       loop { return idx if a == letter; idx+=1; a.next! }
     end
   
+    #
+    # Translates an index to a column letter
+    #
+    # @param [Fixnum] index the index to translate
+    # @return [String] the column letter
+    #
+  
     def col_letter( index )
       return index if index.is_a? String
       index > 0 or fail ArgumentError, 'Indexing is 1-based'
       a = 'A'; ( index - 1 ).times { a.next! }; a
     end
   
+    #
+    # Translates an address to a column id
+    #
+    # @param [String] address the address to translate
+    # @return [String] the column id
+    #
+  
     def column_id( address )
       address[/[A-Z]+/]
     end
     
+    #
+    # Expands an address to all contained addresses
+    #
+    # @param [String] address the address to translate
+    # @return [Array<String>] all addresses included within the given address
+    #
+
     def expand( address )
       return [[address]] unless address.include? ':'
       address.upcase.match( /([A-Z]+)(\d+):([A-Z]+)(\d+)/i )
@@ -34,27 +80,64 @@ module RubyExcel
       ( start_row..end_row ).map { |r| ( start_col..end_col ).map { |c| c + r.to_s } } 
     end
     
+    #
+    # Translates indices to an address
+    #
+    # @param [Fixnum] row_idx the row index
+    # @param [Fixnum] column_idx the column index
+    # @return [String] the corresponding address
+    #
+    
     def indices_to_address( row_idx, column_idx )
       [ row_idx, column_idx ].all? { |a| a.is_a?( Fixnum ) } or fail ArgumentError, 'Input must be Fixnum'
       col_letter( column_idx ) + row_idx.to_s
     end
     
+    #
+    # Checks whether an object is a multidimensional Array
+    #
+    # @param [Object] obj the object to test
+    # @return [Boolean] whether the object is a multidimensional Array
+    #
+    
     def multi_array?( obj )
       obj.all? { |el| el.is_a?( Array ) } && obj.is_a?( Array ) rescue false
     end
     
+    #
+    # Offsets an address by row and column
+    #
+    # @param [String] address the address to offset
+    # @param [Fixnum] row the number of rows to offset by
+    # @param [Fixnum] col the number of columns to offset by
+    # @return [String] the new address
+    #
+    
     def offset(address, row, col)
       ( col_letter( address_to_col_index( address ) + col ) ) + ( row_id( address ) + row ).to_s
     end
     
+    #
+    # Translates two objects to a range address
+    #
+    # @param [String, RubyExcel::Element] obj1 the first address element
+    # @param [String, RubyExcel::Element] obj2 the second address element
+    # @return [String] the new address
+    #
+    
     def to_range_address( obj1, obj2 )
-      if obj2
-        obj2.is_a?( String ) ? ( obj1 + ':' + obj2 ) : "#{ obj1.address }:#{ obj2.address }"
-      else
-        obj1.is_a?( String ) ? obj1 : obj1.address
-      end
+      addr = obj1.respond_to?( :address ) ? obj1.address : obj1.to_s
+      addr << ':' + ( obj2.respond_to?( :address ) ? obj2.address : obj2.to_s ) if obj2
+      addr
     end
     
+    #
+    # Translates an address to a row id
+    #
+    # @param [String] address the address to translate
+    # @return [Fixnum] the row id
+    #
+    
     def row_id( address )
       address[/\d+/].to_i
     end

data/lib/rubyexcel/data.rb

@@ -2,12 +2,30 @@ module RubyExcel
 
 require_relative 'address.rb'
 
+  #
+  # The class which holds a Sheet's data
+  #
+
   class Data
-    attr_reader :rows, :cols
+    include Address
+    include Enumerable
+  
+    #The number of rows in the data
+    attr_reader :rows
+    
+    #The number of columns in the data
+    attr_reader :cols
+    
+    #The parent Sheet
     attr_accessor :sheet
     alias parent sheet
     
-    include Address
+    #
+    # Creates a RubyExcel::Data instance
+    #
+    # @param [RubyExcel::Sheet] sheet the parent Sheet
+    # @param [Array<Array>] input_data the multidimensional Array which holds the data
+    #
     
     def initialize( sheet, input_data )
       ( input_data.kind_of?( Array ) &&  input_data.all? { |el| el.kind_of?( Array ) } ) or fail ArgumentError, 'Input must be Array of Arrays'
@@ -16,37 +34,76 @@ require_relative 'address.rb'
       calc_dimensions
     end
     
+    #
+    # Returns a copy of the data
+    #
+    
     def all
       @data.dup
     end
     
+    #
+    # Appends a multidimensional Array to the end of the data
+    #
+    # @param [Array<Array>] multi_array the multidimensional Array to add to the data
+    #
+    
     def append( multi_array )
       @data << multi_array
       calc_dimensions
     end
     
+    #
+    # Finds a Column reference bu a header
+    #
+    # @param [String] header the header to search for
+    # @return [String] the Column reference
+    # @raise [NoMethodError] 'No header rows present'
+    # @raise [IndexError] header.to_s + ' is not a valid header'
+    #
+    
     def colref_by_header( header )
+      return header.idx if header.is_a?( Column )
       sheet.header_rows > 0 or fail NoMethodError, 'No header rows present'
       @data[ 0..sheet.header_rows-1 ].each { |r| idx = r.index( header ); return col_letter( idx+1 ) if idx }
-      fail IndexError, "#{ header } is not a valid header"
+      fail IndexError, header.to_s + ' is not a valid header'
     end
     
+    #
+    # Removes empty rows and columns from the data
+    #
+    
     def compact!
       compact_columns!
       compact_rows!
     end
     
+    #
+    # Removes empty columns from the data
+    #
+    
     def compact_columns!
       ensure_shape
       @data = @data.transpose.delete_if { |ar| ar.all? { |el| el.to_s.empty? } || ar.empty? }.transpose
       calc_dimensions
     end
     
+    #
+    # Removes empty rows from the data
+    #
+    
     def compact_rows!
       @data.delete_if { |ar| ar.all? { |el| el.to_s.empty? } || ar.empty? }
       calc_dimensions
     end
     
+    #
+    # Deletes the data referenced by an object
+    #
+    # @param [RubyExcel::Column, RubyExcel::Element, RubyExcel::Row] object the object to delete
+    # @raise [NoMethodError] object.class.to_s + ' is not supported"
+    #
+    
     def delete( object )
       case object
       when Row
@@ -60,41 +117,89 @@ require_relative 'address.rb'
         @data[ indices[0]..indices[2] ].each { |r| r.slice!( indices[1], indices[3] - indices[1] + 1 ) }
         @data.delete_if.with_index { |r,i| r.empty? && i.between?( indices[0], indices[2] ) }
       else
-        fail NoMethodError, "#{ object.class } is not supported"
+        fail NoMethodError, object.class.to_s + ' is not supported'
       end
       calc_dimensions
     end
     
+    #
+    # Deletes the data referenced by a column id
+    #
+    
     def delete_column( ref )
       delete( Column.new( sheet, ref ) )
       calc_dimensions
     end
   
+    #
+    # Deletes the data referenced by a row id
+    #
+  
     def delete_row( ref )
       delete( Row.new( sheet, ref ) )
       calc_dimensions
     end
     
+    #
+    # Deletes the data referenced by an address
+    #
+    
     def delete_range( ref )
       delete( Element.new( sheet, ref ) )
       calc_dimensions
     end
     
+    #
+    # Return a copy of self
+    #
+    # @return [RubyExcel::Data]
+    #
+    
     def dup
       Data.new( sheet, @data.map(&:dup) )
     end
     
+    #
+    # Check whether the data is empty
+    #
+    # @return [Boolean]
+    #
+    
     def empty?
       no_headers.empty?
     end
 
+    #
+    # Yields each "Row" as an Array
+    #
+    
+    def each
+      @data.each { |ar| yield ar }
+    end
+
+    #
+    # Removes all Rows (omitting headers) where the block is false
+    #
+    # @param [String] header the header of the Column to pass to the block
+    # @yield [Object] the value at the intersection of Column and Row
+    # @return [self]
+    #
+
     def filter!( header )
       hrows = sheet.header_rows
-      idx = col_index( hrows > 0 ? colref_by_header( header ) : header )
+      idx = index_by_header( header )
       @data = @data.select.with_index { |row, i| hrows > i || yield( row[ idx -1 ] ) }
       calc_dimensions
+      self
     end
   
+    #
+    # Select and re-order Columns by a list of headers
+    #
+    # @param [Array<String>] headers the ordered list of headers to keep
+    # @note Invalid headers will be skipped
+    #
+  
     def get_columns!( *headers )
       headers = headers.flatten
       hrow = sheet.header_rows - 1
@@ -104,6 +209,32 @@ require_relative 'address.rb'
       calc_dimensions
     end
     
+    #
+    # Return the header section of the data
+    #
+    
+    def headers
+      sheet.header_rows > 0 ? @data[ 0..sheet.header_rows-1 ] : nil
+    end
+    
+    #
+    # Find a Column index by header
+    #
+    # @param [String] header the Column header to search for
+    # @return [Fixnum] the index of the given header
+    #
+    
+    def index_by_header( header )
+      col_index( sheet.header_rows > 0 ? colref_by_header( header ) : header )
+    end
+    
+    #
+    # Insert blank Columns into the data
+    #
+    # @param [String, Fixnum] before the Column reference to insert before.
+    # @param [Fixnum] number the number of new Columns to insert
+    #
+    
     def insert_columns( before, number=1 )
       a = Array.new( number, nil )
       before = col_index( before ) - 1
@@ -111,45 +242,117 @@ require_relative 'address.rb'
       calc_dimensions
     end
     
+    #
+    # Insert blank Rows into the data
+    #
+    # @param [Fixnum] before the Row index to insert before.
+    # @param [Fixnum] number the number of new Rows to insert
+    #
+    
     def insert_rows( before, number=1 )
       @data = @data.insert( ( col_index( before ) - 1 ), *Array.new( number, [nil] ) )
       calc_dimensions
     end
     
+    #
+    # Return the data without headers
+    #
+    
     def no_headers
       @data[ sheet.header_rows..-1 ]
     end
     
+    #
+    # Split the data into two sections by evaluating each value in a column
+    #
+    # @param [String] header the header of the Column which contains the yield value
+    # @yield [value] yields the value of each row under the given header
+    #
+    
+    def partition( header, &block )
+      idx = index_by_header( header )
+      d1, d2 = no_headers.partition { |row| yield row[ idx -1 ] }
+      [ headers + d1, headers + d2 ] if headers
+    end
+    
+    #
+    # Read a value by address
+    #
+    
     def read( addr )
       row_idx, col_idx = address_to_indices( addr )
       @data[ row_idx-1 ][ col_idx-1 ]
     end
     alias [] read
     
+    #
+    # Reverse the data Columns
+    #
+    
     def reverse_columns!
       ensure_shape
       @data = @data.transpose.reverse.transpose
     end
+
+    #
+    # Reverse the data Rows (without affecting the headers)
+    #
     
     def reverse_rows!
       @data = skip_headers &:reverse
     end
+    
+    #
+    # Perform an operation on the data without affecting the headers
+    #
+    # @yield [data] yield the data without the headers
+    # @return [Array<Array>] returns the data with the block operation performed on it, and the headers back in place
+    #
 
+    def skip_headers
+      return to_enum(:skip_headers) unless block_given?
+      hr = sheet.header_rows
+      if hr > 0
+        @data[ 0..hr - 1 ] + yield( @data[ hr..-1 ] )
+      else
+        yield( @data )
+      end 
+    end
+    
+    #
+    # Sort the data according to the block
+    #
+    
     def sort!( &block )
       @data = skip_headers { |d| d.sort( &block ) }; self
     end
     
+    #
+    # Sort the data according to the block value
+    #
+    
     def sort_by!( &block )
       @data = skip_headers { |d| d.sort_by( &block ) }
     end
     
+    #
+    # Unique the rows according to the values within a Column, selected by header
+    #
+    
     def uniq!( header )
       column = col_index( colref_by_header( header ) )
-      @data = @data.uniq { |row| row[ column - 1 ] }
+      @data = skip_headers { |d| d.uniq { |row| row[ column - 1 ] } }
       calc_dimensions
     end
     alias unique! uniq!
     
+    #
+    # Write a value into the data
+    #
+    # @param [String] addr the address to write the value to
+    # @param val the value to write to the address
+    #
+    
     def write( addr, val )
       row_idx, col_idx = address_to_indices( addr )
       ( row_idx - rows ).times { @data << [] }
@@ -157,12 +360,6 @@ require_relative 'address.rb'
       calc_dimensions
     end
     alias []= write
-
-    include Enumerable
-    
-    def each
-      @data.each { |ar| yield ar }
-    end
     
     private
     
@@ -175,15 +372,6 @@ require_relative 'address.rb'
       @data = @data.map { |ar| ar.length == cols ? ar : ar + Array.new( cols - ar.length, nil) }
     end
     
-    def skip_headers
-      hr = sheet.header_rows
-      if hr > 0
-        block_given? ? @data[ 0..hr - 1 ] + yield( @data[ hr..-1 ] ) : @data[ hr..-1 ]
-      else
-        block_given? ? yield( @data ) : @data 
-      end 
-    end
-  
   end
 
 end

data/lib/rubyexcel/element.rb

@@ -1,10 +1,32 @@
 module RubyExcel
 
   class Element
+    include Address
+    include Enumerable
 
-    attr_reader :sheet, :address, :data, :column, :row
+    #The parent Sheet
+    attr_reader :sheet
     alias parent sheet
-
+    
+    #The address
+    attr_reader :address
+    
+    #The Data underlying the Sheet
+    attr_reader :data
+    
+    #The first Column id in the address
+    attr_reader :column
+    
+    #The first Row id in the address
+    attr_reader :row
+    
+    #
+    # Creates a RubyExcel::Element instance
+    #
+    # @param [RubyExcel::Sheet] sheet the parent Sheet
+    # @param [String] addr the address to reference
+    #
+    
     def initialize( sheet, addr )
       fail ArgumentError, "Invalid range: #{ addr }" unless addr =~ /\A[A-Z]+\d+:[A-Z]+\d+\z|\A[A-Z]+\d+\z/
       @sheet = sheet
@@ -13,17 +35,31 @@ module RubyExcel
       @column = column_id( addr )
       @row = row_id( addr )
     end
+    
+    #
+    # Delete the data referenced by self.address
+    #
   
     def delete
       data.delete( self )
     end
-  
-    include Address
+    
+    #
+    # Return the value at this Element's address
+    #
+    # @return [Object, Array<Object>] the Object or Array of Objects within the data, referenced by the address
+    #
   
     def value
       address.include?( ':' ) ? expand( address ).map { |ar| ar.map { |addr| data[ addr ] } } : data[ address ]
     end
   
+    #
+    # Set the value at this Element's address
+    #
+    # @param [Object, Array<Object>] val the Object or Array of Objects to write into the data
+    #
+  
     def value=( val )
       if address.include? ':'
         if multi_array?( val )
@@ -36,30 +72,55 @@ module RubyExcel
       end
       self
     end
+    
+    #
+    # The data at address as a TSV String
+    #
   
     def to_s
       value.is_a?( Array ) ? value.map { |ar| ar.join "\t" }.join($/) : value.to_s
     end
     
+    #
+    # View the object for debugging
+    #
+    
     def inspect
-      "#{ self.class }:0x#{ '%x' % (object_id << 1) }: #{ address }"
+      "#{ self.class }:0x#{ '%x' % ( object_id << 1 ) }: #{ address }"
     end
   
-    include Enumerable
+    #
+    # Yields each value in the data referenced by the address
+    #
     
     def each
+      return to_enum( :each ) unless block_given?
       expand( address ).flatten.each { |addr| yield data[ addr ] }
     end
     
+    #
+    # Yields each Element referenced by the address
+    #
+    
     def each_cell
+      return to_enum( :each_cell ) unless block_given?
       expand( address ).flatten.each { |addr| yield Element.new( sheet, addr ) }
     end
     
+    #
+    # Checks whether the data referenced by the address is empty
+    #
+    
     def empty?
       all? { |v| v.to_s.empty? }
     end
   
+    #
+    # Replaces each value with the result of the block
+    #
+  
     def map!
+      return to_enum( :map! ) unless block_given?
       expand( address ).flatten.each { |addr| data[ addr ] = yield data[ addr ] }
     end