workbook 0.2.0 → 0.2.1

data/lib/workbook/modules/type_parser.rb

@@ -1,22 +1,35 @@
 module Workbook
   module Modules
+    # Adds type parsing capabilities to e.g. a Cell.
     module TypeParser
+      
+      # Cleans a text file from all kinds of different ways of representing new lines
+      # @param [String] csv_raw a raw csv string
       def strip_win_chars csv_raw
         csv_raw.gsub(/(\n\r|\r\n|\r)/,"\n")
       end
       
+      # Return the different active string parsers
+      # @return [Array<Symbol>] A list of parsers
       def string_parsers
         @string_parsers ||= [:string_cleaner,:string_nil_converter,:string_integer_converter,:string_boolean_converter]
       end
       
-      def string_parsers= arr
-        @string_parsers = arr
+      # Set the list of string parsers
+      # @param [Array<Symbol>] parsers A list of parsers
+      # @return [Array<Symbol>] A list of parsers
+      def string_parsers= parsers
+        @string_parsers = parsers
       end
-      
+
+      # Return the different active string parsers
+      # @return [Array<Proc>] A list of parsers as Procs   
       def string_parsers_as_procs
         string_parsers.collect{|c| c.is_a?(Proc) ? c : self.send(c)}
       end
       
+      # Returns the parsed value (retrieved by calling #value)
+      # @return [Object] The parsed object, ideally a date or integer when found to be a such...
       def parse options={}
         options = {:detect_date=>false}.merge(options)
         string_parsers.push :string_optimistic_date_converter if options[:detect_date]

data/lib/workbook/readers/xls_reader.rb

@@ -3,75 +3,6 @@ require 'spreadsheet'
 module Workbook
   module Readers
     module XlsReader
-      XLS_COLORS = {:xls_color_1=>'#000000',
-                    :xls_color_2=>'#FFFFFF',
-                    :xls_color_3=>'#FF0000',
-                    :xls_color_4=>'#00FF00',
-                    :xls_color_5=>'#0000FF',
-                    :xls_color_6=>'#FFFF00',
-                    :xls_color_7=>'#FF00FF',
-                    :xls_color_8=>'#00FFFF',
-                    :xls_color_9=>'#800000',
-                    :xls_color_10=>'#008000',
-                    :xls_color_11=>'#000080',
-                    :xls_color_12=>'#808000',
-                    :xls_color_13=>'#800080',
-                    :xls_color_14=>'#008080',
-                    :xls_color_15=>'#C0C0C0',
-                    :xls_color_16=>'#808080',
-                    :xls_color_17=>'#9999FF',
-                    :xls_color_18=>'#993366',
-                    :xls_color_19=>'#FFFFCC',
-                    :xls_color_20=>'#CCFFFF',
-                    :xls_color_21=>'#660066',
-                    :xls_color_22=>'#FF8080',
-                    :xls_color_23=>'#0066CC',
-                    :xls_color_24=>'#CCCCFF',
-                    :xls_color_25=>'#000080',
-                    :xls_color_26=>'#FF00FF',
-                    :xls_color_27=>'#FFFF00',
-                    :xls_color_28=>'#00FFFF',
-                    :xls_color_29=>'#800080',
-                    :xls_color_30=>'#800000',
-                    :xls_color_31=>'#008080',
-                    :xls_color_32=>'#0000FF',
-                    :xls_color_33=>'#00CCFF',
-                    :xls_color_34=>'#CCFFFF',
-                    :xls_color_35=>'#CCFFCC',
-                    :xls_color_36=>'#FFFF99',
-                    :xls_color_37=>'#99CCFF',
-                    :xls_color_38=>'#FF99CC',
-                    :xls_color_39=>'#CC99FF',
-                    :xls_color_40=>'#FFCC99',
-                    :xls_color_41=>'#3366FF',
-                    :xls_color_42=>'#33CCCC',
-                    :xls_color_43=>'#99CC00',
-                    :xls_color_44=>'#FFCC00',
-                    :xls_color_45=>'#FF9900',
-                    :xls_color_46=>'#FF6600',
-                    :xls_color_47=>'#666699',
-                    :xls_color_48=>'#969696',
-                    :xls_color_49=>'#003366',
-                    :xls_color_50=>'#339966',
-                    :xls_color_51=>'#003300',
-                    :xls_color_52=>'#333300',
-                    :xls_color_53=>'#993300',
-                    :xls_color_54=>'#993366',
-                    :xls_color_55=>'#333399',
-                    :xls_color_56=>'#333333',
-                    :black=>'#000000',
-                    :white=>'#FFFFFF',
-                    :red=>'#FF0000',
-                    :green=>'#00FF00',
-                    :blue=>'#0000FF',
-                    :yellow=>'#FFFF00',
-                    :magenta=>'#FF00FF',
-                    :cyan=>'#00FFFF',
-                    :border=>'#FFFFFF',
-                    :text=>'#000000',
-                    :lime=>'#00f94c'}
-
-        
 
       def load_xls file_obj
         begin
@@ -158,7 +89,7 @@ module Workbook
       
       private 
       def xls_color_to_html_hex color_sym
-        XLS_COLORS[color_sym] ? XLS_COLORS[color_sym] : "#000000"
+        Workbook::Book::XLS_COLORS[color_sym] ? Workbook::Book::XLS_COLORS[color_sym] : "#000000"
       end
       
       def ms_formatting_to_strftime ms_nr_format       

data/lib/workbook/readers/xls_shared.rb

@@ -0,0 +1,75 @@
+module Workbook
+  module Readers
+    module XlsShared
+      XLS_COLORS = {:xls_color_1=>'#000000',
+                    :xls_color_2=>'#FFFFFF',
+                    :xls_color_3=>'#FF0000',
+                    :xls_color_4=>'#00FF00',
+                    :xls_color_5=>'#0000FF',
+                    :xls_color_6=>'#FFFF00',
+                    :xls_color_7=>'#FF00FF',
+                    :xls_color_8=>'#00FFFF',
+                    :xls_color_9=>'#800000',
+                    :xls_color_10=>'#008000',
+                    :xls_color_11=>'#000080',
+                    :xls_color_12=>'#808000',
+                    :xls_color_13=>'#800080',
+                    :xls_color_14=>'#008080',
+                    :xls_color_15=>'#C0C0C0',
+                    :xls_color_16=>'#808080',
+                    :xls_color_17=>'#9999FF',
+                    :xls_color_18=>'#993366',
+                    :xls_color_19=>'#FFFFCC',
+                    :xls_color_20=>'#CCFFFF',
+                    :xls_color_21=>'#660066',
+                    :xls_color_22=>'#FF8080',
+                    :xls_color_23=>'#0066CC',
+                    :xls_color_24=>'#CCCCFF',
+                    :xls_color_25=>'#000080',
+                    :xls_color_26=>'#FF00FF',
+                    :xls_color_27=>'#FFFF00',
+                    :xls_color_28=>'#00FFFF',
+                    :xls_color_29=>'#800080',
+                    :xls_color_30=>'#800000',
+                    :xls_color_31=>'#008080',
+                    :xls_color_32=>'#0000FF',
+                    :xls_color_33=>'#00CCFF',
+                    :xls_color_34=>'#CCFFFF',
+                    :xls_color_35=>'#CCFFCC',
+                    :xls_color_36=>'#FFFF99',
+                    :xls_color_37=>'#99CCFF',
+                    :xls_color_38=>'#FF99CC',
+                    :xls_color_39=>'#CC99FF',
+                    :xls_color_40=>'#FFCC99',
+                    :xls_color_41=>'#3366FF',
+                    :xls_color_42=>'#33CCCC',
+                    :xls_color_43=>'#99CC00',
+                    :xls_color_44=>'#FFCC00',
+                    :xls_color_45=>'#FF9900',
+                    :xls_color_46=>'#FF6600',
+                    :xls_color_47=>'#666699',
+                    :xls_color_48=>'#969696',
+                    :xls_color_49=>'#003366',
+                    :xls_color_50=>'#339966',
+                    :xls_color_51=>'#003300',
+                    :xls_color_52=>'#333300',
+                    :xls_color_53=>'#993300',
+                    :xls_color_54=>'#993366',
+                    :xls_color_55=>'#333399',
+                    :xls_color_56=>'#333333',
+                    :black=>'#000000',
+                    :white=>'#FFFFFF',
+                    :red=>'#FF0000',
+                    :green=>'#00FF00',
+                    :blue=>'#0000FF',
+                    :yellow=>'#FFFF00',
+                    :magenta=>'#FF00FF',
+                    :cyan=>'#00FFFF',
+                    :border=>'#FFFFFF',
+                    :text=>'#000000',
+                    :lime=>'#00f94c'
+          }
+		end
+	end
+end
+		    

data/lib/workbook/row.rb

@@ -1,15 +1,14 @@
 module Workbook
   class Row < Array
     alias_method :compare_without_header, :<=>
-    
-    # The placeholder attribute is used in compares (corresponds to newly created or removed lines (depending which side you're on)
-    attr_accessor :placeholder
+    attr_accessor :placeholder     # The placeholder attribute is used in compares (corresponds to newly created or removed lines (depending which side you're on)
     attr_accessor :format
     
-    
-    # @param [Workbook::Row, Array<Workbook::Cell>, Array] list of cells to initialize the row with, default is empty
-    # @param [Workbook::Table] a row normally belongs to a table, reference it here
-    # @param [Hash], option hash. Supprted options: parse_cells_on_batch_creation (parse cell values during row-initalization, default: false), cell_parse_options (default {}, see Workbook::Modules::TypeParser)
+    # Initialize a new row
+    #
+    # @param [Workbook::Row, Array<Workbook::Cell>, Array] cells list of cells to initialize the row with, default is empty
+    # @param [Workbook::Table] table a row normally belongs to a table, reference it here
+    # @param [Hash] options  Supprted options: parse_cells_on_batch_creation (parse cell values during row-initalization, default: false), cell_parse_options (default {}, see Workbook::Modules::TypeParser)
     def initialize cells=[], table=nil, options={}
       options=options ? {:parse_cells_on_batch_creation=>false,:cell_parse_options=>{}}.merge(options) : {} 
       cells = [] if cells==nil
@@ -25,22 +24,35 @@ module Workbook
       end
     end
     
+    # An internal function used in diffs
+    # 
+    # @return [Boolean] returns true when this row is not an actual row, but a placeholder row to 'compare' against 
     def placeholder?
       placeholder ? true : false
     end
     
+    # Returns the table this row belongs to
+    #
+    # @return [Workbook::Table] the table this row belongs to
     def table
       @table
     end
     
-    # Set reference to the table this row belongs to (and adds the row to this table)
+    # Set reference to the table this row belongs to without adding the row to the table
+    #
+    # @param [Workbook::Table] t the table this row belongs to
+    def set_table(t)
+      @table = t
+    end
+    
+    # Set reference to the table this row belongs to and add the row to this table
     #
-    # @param [Workbook::Table] 
+    # @param [Workbook::Table] t the table this row belongs to
     def table= t
       raise ArgumentError, "table should be a Workbook::Table (you passed a #{t.class})" unless t.is_a?(Workbook::Table) or t == nil
       if t
         @table = t
-        table << self
+        table.push(self) #unless table.index(self) and self.placeholder?
       end
     end
     
@@ -50,25 +62,55 @@ module Workbook
     #   row[1] #=> <Cell value="a">
     #   row[:a] #=> <Cell value="a">
     #
-    # @param [Fixnum, Symbol]
+    # @param [Fixnum, Symbol] index_or_hash
     # @return [Workbook::Cell, nil]
     def [](index_or_hash)
-      if index_or_hash.is_a? Fixnum
-        return to_a[index_or_hash]
-      elsif index_or_hash.is_a? Symbol
+      if index_or_hash.is_a? Symbol
         rv = nil
         begin
           rv = to_hash[index_or_hash]
         rescue NoMethodError
         end
         return rv
+      else 
+        if index_or_hash
+          return to_a[index_or_hash]
+        end
       end
     end
+
+    # Overrides normal Array's []=-function with support for symbols that identify a column based on the header-values
+    #
+    # @example Lookup using fixnum or header value encoded as symbol
+    #   row[1] #=> <Cell value="a">
+    #   row[:a] #=> <Cell value="a">
+    #
+    # @param [Fixnum, Symbol] index_or_hash
+    # @param [String, Fixnum, NilClass, Date, DateTime, Time, Float] value 
+    # @return [Workbook::Cell, nil]
+    def []= (index_or_hash, value)
+      index = index_or_hash
+      if index_or_hash.is_a? Symbol
+        index = table_header_keys.index(index_or_hash)
+      end
     
+      value_celled = Workbook::Cell.new
+      if value.is_a? Workbook::Cell
+        value_celled = value
+      else
+        current_cell = self[index]
+        if current_cell.is_a? Workbook::Cell
+          value_celled = current_cell 
+        end
+        value_celled.value=(value)
+      end
+      super(index,value_celled)
+    end
+        
     # Returns an array of cells allows you to find cells by a given color, normally a string containing a hex
     #
-    # @param [String] default :any colour, can be a CSS-style hex-string
-    # @param [Hash] options. Option :hash_keys (default true) returns row as an array of symbols
+    # @param [String] color  a CSS-style hex-string
+    # @param [Hash] options Option :hash_keys (default true) returns row as an array of symbols
     # @return [Array<Symbol>, Workbook::Row<Workbook::Cell>]
     def find_cells_by_background_color color=:any, options={}
       options = {:hash_keys=>true}.merge(options)
@@ -84,25 +126,45 @@ module Workbook
       table != nil and self.object_id == table.header.object_id
     end
     
+    # Is this the first row in the table
+    # 
+    # @return [Boolean, NilClass] returns nil if it doesn't belong to a table, false when it isn't the first row of a table and true when it is.
+    def first?
+      table != nil and self.object_id == table.first.object_id
+    end
+    
+    # Converts a row to an array of symbol representations of the row content, see also: Workbook::Cell#to_sym
     # @return [Array<Symbol>] returns row as an array of symbols
     def to_symbols
       collect{|c| c.to_sym}
     end
     
+    # Converts the row to an array of Workbook::Cell's
     # @return [Array<Workbook::Cell>] returns row as an array of symbols
     def to_a
       self.collect{|c| c}
     end
     
+    def table_header_keys
+      table.header.to_symbols
+    end
+    
+    # Returns a hash representation of this row
+    #
+    # @return [Hash]
     def to_hash
       return @hash if @hash
-      keys = table.header.to_symbols
+      keys = table_header_keys
       values = self
       @hash = {}
       keys.each_with_index {|k,i| @hash[k]=values[i]}
       return @hash
     end
     
+    # Compares one row wiht another
+    #
+    # @param [Workbook::Row] other row to compare against
+    # @return [Workbook::Row] a row with the diff result. 
     def <=> other
       a = self.header? ? 0 : 1
       b = other.header? ? 0 : 1
@@ -110,6 +172,9 @@ module Workbook
       compare_without_header other
     end
     
+    # The first cell of the row is considered to be the key
+    #
+    # @return [Workbook::Cell] the key cell
     def key
       first
     end
@@ -119,5 +184,12 @@ module Workbook
       r = self.clone
       r = r.collect{|c| c unless c.nil?}.compact
     end
+    
+    # clone the row with together with the cells
+    #
+    # @return [Workbook::Row] a cloned copy of self with cells
+    def clone
+      Workbook::Row.new(to_a.collect{|c| c.clone})
+    end
   end
 end

data/lib/workbook/sheet.rb

@@ -1,7 +1,14 @@
 module Workbook
   class Sheet < Array
+    # A Sheet is a container of tables
     attr_accessor :book
     
+    # Initialize a new sheet
+    #
+    # @param [Workbook::Table, Array<Array>] table   The first table of this sheet
+    # @param [Workbook::Book] book                   The book this sheet belongs to
+    # @param [Hash] options                          are forwarded to Workbook::Table.new
+    # @return [Workbook::Sheet] (self)
     def initialize table=Workbook::Table.new([], self), book=nil, options={}
       if table.is_a? Workbook::Table
         push table
@@ -9,14 +16,33 @@ module Workbook
         push Workbook::Table.new(table, self, options)
       end
       self.book = book
+      return self
     end
     
+    # Returns true if the first table of this sheet contains anything
+    #
+    # @return [Boolean]
     def has_contents?
       table.has_contents?
     end
         
+    # Returns the first table of this sheet
+    #
+    # @return [Workbook::Table] the first table of this sheet
     def table
       first
     end
+    
+    # Returns the book this sheet belongs to
+    #
+    # @return [Workbook::Book] the book this sheet belongs to
+    def book
+      if @book
+        return @book
+      else
+        self.book = Workbook::Book.new(self)
+        return @book
+      end
+    end
   end
 end

data/lib/workbook/table.rb

@@ -3,6 +3,7 @@ require 'workbook/writers/csv_table_writer'
 
 
 module Workbook  
+  # A table is a container of rows and keeps track of the sheet it belongs to and which row is its header. Additionally suport for CSV writing and diffing with another table is included.
   class Table < Array
     include Workbook::Modules::TableDiffSort
     include Workbook::Writers::CsvTableWriter
@@ -10,7 +11,6 @@ module Workbook
     attr_accessor :header
     
     def initialize row_cel_values=[], sheet=nil, options={}
-      #@rows = []
       row_cel_values = [] if row_cel_values == nil
       row_cel_values.each do |r|
         if r.is_a? Workbook::Row
@@ -57,6 +57,16 @@ module Workbook
       self
     end
     
+    def push(row)
+      super(row)
+      row.set_table(self)
+    end
+    
+    def <<(row)
+      super(row)
+      row.set_table(self)
+    end
+    
     def has_contents?
       self.clone.remove_empty_lines!.count != 0
     end
@@ -66,5 +76,14 @@ module Workbook
       self.collect{|r| r.object_id}.include? row.object_id
     end
     
+    def sheet
+      if @sheet
+        return @sheet
+      else
+        self.sheet = Workbook::Sheet.new(self)
+        return @sheet
+      end
+    end
+    
   end
 end