rubyexcel 0.0.5 → 0.0.6

data/lib/rubyexcel/excel_tools.rb

@@ -1,10 +1,21 @@
 require 'win32ole' #Interface with Excel
 require 'win32/registry' #Find Documents / My Documents for default directory
 
+# Holder for WIN32OLE Excel Constants
 module ExcelConstants; end
 
 module RubyExcel
 
+  #
+  # Add borders to an Excel Range
+  #
+  # @param [WIN32OLE::Range] range the Excel Range to add borders to
+  # @param [Fixnum] weight the weight of the borders
+  # @param [Boolean] inner add inner borders
+  # @raise [ArgumentError] 'First Argument must be WIN32OLE Range'
+  # @return [WIN32OLE::Range] the range initially given
+  #
+
   def self.borders( range, weight=1, inner=false )
     range.ole_respond_to?( :borders ) or fail ArgumentError, 'First Argument must be WIN32OLE Range'
     [0,1,2,3].include?( weight ) or fail ArgumentError, "Invalid line weight #{ weight }. Must be from 0 to 3"
@@ -18,12 +29,27 @@ module RubyExcel
 
   class Workbook
   
+    #
+    # Drop a multidimensional Array into an Excel Sheet
+    #
+    # @param [Array<Array>] data the data to place in the Sheet
+    # @param [WIN32OLE::Worksheet, nil] sheet optional WIN32OLE Worksheet to use
+    # @return [WIN32OLE::Worksheet] the Worksheet containing the data
+    #
+  
     def dump_to_sheet( data, sheet=nil )
       data.is_a?( Array ) or fail ArgumentError, "Invalid data type: #{ data.class }"
       sheet ||= get_workbook.sheets(1)
       sheet.range( sheet.cells( 1, 1 ), sheet.cells( data.length, data[0].length ) ).value = data
       sheet
     end
+    
+    #
+    # Open or connect to an Excel instance
+    #
+    # @param [Boolean] invisible leave Excel invisible if creating a new instance
+    # @return [WIN32OLE::Excel] the first available Excel application
+    #
 
     def get_excel( invisible = false )
       excel = WIN32OLE::connect( 'excel.application' ) rescue WIN32OLE::new( 'excel.application' )
@@ -31,6 +57,14 @@ module RubyExcel
       excel
     end
     
+    #
+    # Create a new Excel Workbook
+    #
+    # @param [WIN32OLE::Excel, nil] excel an Excel object to use
+    # @param [Boolean] invisible leave Excel invisible if creating a new instance
+    # @return [WIN32OLE::Workbook] the new Excel Workbook
+    #
+    
     def get_workbook( excel=nil, invisible = false )
       excel ||= get_excel( invisible )
       wb = excel.workbooks.add
@@ -38,15 +72,32 @@ module RubyExcel
       wb
     end
 
+    #
+    # Take an Excel Sheet and standardise some of the formatting
+    #
+    # @param [WIN32OLE::Worksheet] sheet the Sheet to add formatting to
+    # @return [WIN32OLE::Worksheet] the sheet with formatting added
+    #
+    
     def make_sheet_pretty( sheet )
       c = sheet.cells
       c.rowheight = 15
       c.entireColumn.autoFit
       c.horizontalAlignment = -4108
       c.verticalAlignment = -4108
+      sheet.UsedRange.Columns.each { |col| col.ColumnWidth = 30 if col.ColumnWidth > 50 }
+      RubyExcel.borders( sheet.usedrange, 1, true )
       sheet
     end
     
+    #
+    # Save the RubyExcel::Workbook as an Excel Workbook
+    #
+    # @param [String] filename the filename to save as
+    # @param [Boolean] invisible leave Excel invisible if creating a new instance
+    # @return [WIN32OLE::Workbook] the Workbook, saved as filename.
+    #
+    
     def save_excel( filename = 'Output', invisible = false )
       filename = filename.gsub('/','\\')
       unless filename.include?('\\')
@@ -59,9 +110,16 @@ module RubyExcel
       wb
     end
     
+    #
+    # Output the RubyExcel::Workbook to Excel
+    #
+    # @param [Boolean] invisible leave Excel invisible if creating a new instance
+    # @return [WIN32OLE::Workbook] the Workbook in Excel
+    #
+    
     def to_excel( invisible = false )
       self.sheets.count == self.sheets.map(&:name).uniq.length or fail NoMethodError, 'Duplicate sheet name'
-      wb = get_workbook( nil, invisible )
+      wb = get_workbook( nil, true )
       wb.parent.displayAlerts = false
       first_time = true
       self.each do |s|
@@ -70,9 +128,10 @@ module RubyExcel
         make_sheet_pretty( dump_to_sheet( s.data.all, sht ) )
       end
       wb.sheets(1).select
+      wb.application.visible = true unless invisible
       wb
     end
     
-  end
+  end # Workbook
   
-end
+end # RubyExcel

data/lib/rubyexcel/rubyexcel_components.rb

@@ -5,6 +5,10 @@ require_relative 'section.rb'
 
 module RubyExcel
 
+  #
+  # Example data to use in tests / demos
+  #
+  
   def self.sample_data
     [
       [ 'Part',  'Ref1', 'Ref2', 'Qty', 'Cost' ],
@@ -18,6 +22,10 @@ module RubyExcel
     ]
   end
   
+  #
+  # Shortcut to create a Sheet with example data
+  #
+  
   def self.sample_sheet
     Workbook.new.load RubyExcel.sample_data
   end

data/lib/rubyexcel/section.rb

@@ -1,91 +1,177 @@
 module RubyExcel
 
+  #
+  # Superclass for Row and Column
+  #
+
   class Section
-  
     include Address
+    include Enumerable
 
-    attr_reader :sheet, :idx, :data
+    # The Sheet parent of the Section
+    attr_reader :sheet
     alias parent sheet
 
+    # The Data underlying the Sheet
+    attr_reader :data
+    
+    #
+    # Creates a RubyExcel::Section instance
+    #
+    # @param [RubyExcel::Sheet] sheet the parent Sheet
+    #
+    
     def initialize( sheet )
       @sheet = sheet
       @data = sheet.data
     end
+    
+    #
+    # Append a value to the Section. 
+    #   This only adds an extra cell if it is the first Row / Column.
+    #   This prevents a loop through Rows or Columns from extending diagonally away from the main data.
+    #
+    # @param [Object] value the object to append
+    #
   
     def <<( value )
-      if self.is_a? Row
-        lastone = ( col_index( idx ) == 1 ? data.cols + 1 : data.cols )
-      else
-        lastone = ( col_index( idx ) == 1 ? data.rows + 1 : data.rows )
+      case self
+      when Row ; lastone = ( col_index( idx ) == 1 ? data.cols + 1 : data.cols )
+      else     ; lastone = ( col_index( idx ) == 1 ? data.rows + 1 : data.rows )
       end
       data[ translate_address( lastone ) ] = value
     end
     
+    #
+    # Access a cell by its index within the Section
+    #
+    
     def cell( ref )
       Element.new( sheet, translate_address( ref ) )
     end
   
+    #
+    # Delete the data referenced by self
+    #
+  
     def delete
       data.delete( self )
     end
   
+    #
+    # Check whether the data in self is empty
+    #
+  
     def empty?
       all? { |val| val.to_s.empty? }
     end
+    
+    #
+    # Return the address of a given value
+    #
+    # @yield [Object] yields each cell value to the block
+    # @return [String, nil] the address of the value or nil
+    #
   
     def find
+      return to_enum( :find ) unless block_given?
       each_cell { |ce| return ce.address if yield ce.value }; nil
     end
   
+    #
+    # View the object for debugging
+    #
+  
     def inspect
       "#{ self.class }:0x#{ '%x' % (object_id << 1) }: #{ idx }"
     end
   
+    #
+    # Read a value by address
+    #
+    # @param [String, Fixnum] id the index or reference of the required value
+    #
+  
     def read( id )
       data[ translate_address( id ) ]
     end
     alias [] read
     
+    #
+    # Summarise the values of a Section into a Hash
+    #
+    # @return [Hash]
+    #
+    
     def summarise
       each_wh.inject( Hash.new(0) ) { |h, v| h[v]+=1; h }
     end
     alias summarize summarise
     
+    #
+    # The Section as a seperated value String
+    #
+    
     def to_s
       to_a.join ( self.is_a?( Row ) ? "\t" : "\n" )
     end
 
+    #
+    # Write a value by address
+    #
+    # @param [String, Fixnum] id the index or reference to write to
+    # @param [Object] val the object to place at the address
+    #
+    
     def write( id, val )
       data[ translate_address( id ) ] = val
     end
     alias []= write
 
-    include Enumerable
+    #
+    # Yields each value
+    #
 
     def each
       return to_enum(:each) unless block_given?
       each_address { |addr| yield data[ addr ] }
     end
     
+    #
+    # Yields each value, skipping headers
+    #
+    
     def each_without_headers
-      return to_enum(:each_without_headers) unless block_given?
+      return to_enum( :each_without_headers ) unless block_given?
       each_address_without_headers { |addr| yield data[ addr ] }
     end
     alias each_wh each_without_headers
     
+    #
+    # Yields each cell
+    #
+    
     def each_cell
-      return to_enum(:each_cell) unless block_given?
+      return to_enum( :each_cell ) unless block_given?
       each_address { |addr| yield Element.new( sheet, addr ) }
     end
     
+    #
+    # Yields each cell, skipping headers
+    #
+    
     def each_cell_without_headers
-      return to_enum(:each_cell) unless block_given?
+      return to_enum( :each_cell_without_headers ) unless block_given?
       each_address { |addr| yield Element.new( sheet, addr ) }
     end
     alias each_cell_wh each_cell_without_headers
     
+    #
+    # Replaces each value with the result of the block
+    #
+    
     def map!
-      return to_enum(:map!) unless block_given?
+      return to_enum( :map! ) unless block_given?
       each_address { |addr| data[addr] = ( yield data[addr] ) }
     end
 
@@ -93,7 +179,8 @@ module RubyExcel
     
     def translate_address( addr )
       case self
-      when Row ; col_letter( addr ) + idx.to_s
+      when Row
+        col_letter( addr ) + idx.to_s
       when Column
         addr = addr.to_s unless addr.is_a?( String )
         fail ArgumentError, "Invalid address : #{ addr }" if addr =~ /[^\d]/
@@ -103,24 +190,61 @@ module RubyExcel
 
   end
 
+  #
+  # A Row in the Sheet
+  #
+  
   class Row < Section
   
+    # The Row index
     attr_reader :idx
+    
+    #
+    # Creates a RubyExcel::Row instance
+    #
+    # @param [RubyExcel::Sheet] sheet the Sheet which holds this Row
+    # @param [Fixnum] idx the index of this Row
+    #
 
     def initialize( sheet, idx )
       @idx = idx.to_i
       super( sheet )
     end
+    
+    #
+    # Access a cell by its header
+    #
+    # @param [String] header the header to search for
+    # @return [RubyExcel::Element] the cell
+    #
   
     def cell_by_header( header )
       cell( getref( header ) )
     end
     alias cell_h cell_by_header
   
+    #
+    # Find the Address of a header
+    #
+    # @param [String] header the header to search for
+    # @return [String] the address of the header
+    #
+  
     def getref( header )
-      column_id( sheet.row(1).find &/#{header}/ )
+      sheet.header_rows.times do |t|
+        res = sheet.row( t + 1 ).find &/^#{header}$/
+        return column_id( res ) if res
+      end
+      fail ArgumentError, 'Invalid header: ' + header.to_s
     end
     
+    #
+    # Find a value in this Row by its header
+    #
+    # @param [String]header the header to search for
+    # @return [Object] the value at the address
+    #
+    
     def value_by_header( header )
       self[ getref( header ) ]
     end
@@ -133,15 +257,27 @@ module RubyExcel
     end
     
     def each_address_without_headers
-      ( col_letter( sheet.header_cols+1 )..col_letter( data.cols ) ).each { |col_id| yield "#{col_id}#{idx}" }
+      ( 'A'..col_letter( data.cols ) ).each { |col_id| yield "#{col_id}#{idx}" }
     end
 
   end
 
+  #
+  # A Column in the Sheet
+  #
+  
   class Column < Section
   
+    # The Row index
     attr_reader :idx
     
+    #
+    # Creates a RubyExcel::Column instance
+    #
+    # @param [RubyExcel::Sheet] sheet the Sheet which holds this Column
+    # @param [String, Fixnum] idx the index of this Column
+    #
+    
     def initialize( sheet, idx )
       @idx = idx
       super( sheet )