workbook 0.1.6.2 → 0.2.0

data/Gemfile.lock

@@ -1,18 +1,20 @@
 PATH
   remote: .
   specs:
-    workbook (0.1.0)
+    workbook (0.2.0)
       fastercsv
       rchardet (~> 1.3)
-      spreadsheet (>= 0.6.8)
+      rubyXL
+      spreadsheet (>= 0.7.5)
 
 GEM
   remote: http://rubygems.org/
   specs:
-    fastercsv (1.5.4)
-    rchardet (1.3)
-    ruby-ole (1.2.11.3)
-    spreadsheet (0.6.8)
+    fastercsv (1.5.5)
+    rchardet (1.3.1)
+    ruby-ole (1.2.11.6)
+    rubyXL (1.2.10)
+    spreadsheet (0.7.5)
       ruby-ole (>= 1.0)
 
 PLATFORMS

data/lib/workbook/book.rb

@@ -6,6 +6,9 @@ require 'workbook/readers/txt_reader'
 require 'rchardet'
 
 module Workbook
+  # The Book class is the container of sheets. It can be inialized by either the standard initalizer or the open method. The 
+  # Book class can also keep a reference to a template class, storing shared formatting options.
+  # 
   class Book < Array
     include Workbook::Writers::XlsWriter
     include Workbook::Readers::XlsReader
@@ -15,7 +18,6 @@ module Workbook
     
     attr_accessor :title
     attr_accessor :template
-    attr_accessor :default_rewrite_header
     
     # @param [Workbook::Sheet, Array] Create a new workbook based on an existing sheet, or initialize a sheet based on the array
     # @return [Workbook::Book]  
@@ -53,13 +55,16 @@ module Workbook
       first
     end
     
+    # @return [Boolean] returns true if the first sheet has contents
     def has_contents?
       sheet.has_contents?
     end
     
     # Loads an external file into an existing worbook
+    #
     # @param [String] a string with a reference to the file to be opened
     # @param [String] an optional string enforcing a certain parser (based on the file extension, e.g. 'txt', 'csv' or 'xls')
+    # @return [Workbook::Book] A new instance, based on the filename
     def open filename, ext=nil
       ext = file_extension(filename) unless ext
       if ['txt','csv','xml'].include?(ext)
@@ -70,8 +75,10 @@ module Workbook
     end
     
     # Open the file in binary, read-only mode, do not read it, but pas it throug to the extension determined loaded
+    #
     # @param [String] a string with a reference to the file to be opened
     # @param [String] an optional string enforcing a certain parser (based on the file extension, e.g. 'txt', 'csv' or 'xls')
+    # @return [Workbook::Book] A new instance, based on the filename
     def open_binary filename, ext=nil
       ext = file_extension(filename) unless ext
       f = File.open(filename,'rb')
@@ -79,6 +86,7 @@ module Workbook
     end
     
     # Open the file in non-binary, read-only mode, read it and parse it to UTF-8
+    #
     # @param [String] a string with a reference to the file to be opened
     # @param [String] an optional string enforcing a certain parser (based on the file extension, e.g. 'txt', 'csv' or 'xls')
     def open_text filename, ext=nil
@@ -91,12 +99,16 @@ module Workbook
     end
     
     # @param [String] The full filename, or path
+    #
     # @return [String] The file extension
     def file_extension(filename)
       File.extname(filename).gsub('.','').downcase if filename
     end
     
     # Create an instance from a file, using open.
+    #
+    # @param [String] the filename of the document
+    # @param [String] (not required) enforce a certain extension, the parser is based on the extension of the file
     # @return [Workbook::Book] A new instance, based on the filename
     def self.open filename, ext=nil
       wb = self.new
@@ -114,11 +126,7 @@ module Workbook
     def sort
       raise Exception("Books can't be sorted")
     end
-    
-    def default_rewrite_header?
-      return true if default_rewrite_header.nil?
-      default_rewrite_header
-    end
+
     
   end
 end

data/lib/workbook/readers/xlsx_reader.rb

@@ -62,6 +62,7 @@ module RubyXL
   end
 end
 # end monkey patch submitted
+
 module RubyXL
   class Workbook
     def num_fmts_by_id
@@ -106,6 +107,7 @@ module RubyXL
     end
   end
 end
+
 # other monkey patch
 module RubyXL
   class Cell

data/lib/workbook/row.rb

@@ -2,11 +2,14 @@ module Workbook
   class Row < Array
     alias_method :compare_without_header, :<=>
     
-    #used in compares
+    # 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 :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)
     def initialize cells=[], table=nil, options={}
       options=options ? {:parse_cells_on_batch_creation=>false,:cell_parse_options=>{}}.merge(options) : {} 
       cells = [] if cells==nil
@@ -30,7 +33,9 @@ module Workbook
       @table
     end
     
-    # @param [Workbook::Table] Reference to the table this row belongs to (and adds the row to this table)
+    # Set reference to the table this row belongs to (and adds the row to this table)
+    #
+    # @param [Workbook::Table] 
     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
@@ -39,6 +44,14 @@ module Workbook
       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]
+    # @return [Workbook::Cell, nil]
     def [](index_or_hash)
       if index_or_hash.is_a? Fixnum
         return to_a[index_or_hash]
@@ -52,7 +65,11 @@ module Workbook
       end
     end
     
-    # find_cells_by_color returns an array of cells allows you to find cells by a given color, normally a string containing a hex
+    # 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
+    # @return [Array<Symbol>, Workbook::Row<Workbook::Cell>]
     def find_cells_by_background_color color=:any, options={}
       options = {:hash_keys=>true}.merge(options)
       cells = self.collect {|c| c if c.format.has_background_color?(color) }.compact
@@ -60,14 +77,19 @@ module Workbook
       options[:hash_keys] ? r.to_symbols : r
     end
     
+    # Returns true when the row belongs to a table and it is the header row (typically the first row) 
+    #
+    # @return [Boolean]
     def header?
       table != nil and self.object_id == table.header.object_id
     end
     
+    # @return [Array<Symbol>] returns row as an array of symbols
     def to_symbols
       collect{|c| c.to_sym}
     end
     
+    # @return [Array<Workbook::Cell>] returns row as an array of symbols
     def to_a
       self.collect{|c| c}
     end

data/lib/workbook/table.rb

@@ -21,9 +21,12 @@ module Workbook
       end
       self.sheet = sheet
       # Column data is considered as a 'row' with 'cells' that contain 'formatting'
-
     end
     
+    # Returns the header of this table (typically the first row, but can be a different row). 
+    # The header row is also used for finding values in a aribrary row.
+    #
+    # @return [Workbook::Row] The header
     def header
       if @header == false
         false
@@ -34,9 +37,9 @@ module Workbook
       end
     end
     
-    # factory pattern...?
-    def new_row cel_values=[]
-      r = Workbook::Row.new(cel_values,self)
+    # Generates a new row, with optionally predefined cell-values, that is already connected to this table.
+    def new_row cell_values=[]
+      r = Workbook::Row.new(cell_values,self)
       return r
     end
     

data/lib/workbook/writers/xls_writer.rb

@@ -70,34 +70,28 @@ module Workbook
                     :cyan=>'#00FFFF',
                     :border=>'#FFFFFF',
                     :text=>'#000000',
-                    :lime=>'#00f94c'}
+                    :lime=>'#00f94c'
+      }
       
+      # Generates an Spreadsheet (from the spreadsheet gem) in order to build an XlS
+      # 
+      # @params [Hash] A hash with options (unused so far)
+      # @return [Spreadsheet] A Spreadsheet object, ready for writing or more lower level operations
       def to_xls options={}
-        options = {:rewrite_header=>default_rewrite_header?}.merge options
         book = init_spreadsheet_template
         self.each_with_index do |s,si|
           xls_sheet = book.worksheet si
           xls_sheet = book.create_worksheet if xls_sheet == nil
           s.table.each_with_index do |r, ri|
-            write_row = false
-            if r.header?
-              if options[:rewrite_header] == true
-                write_row = true
-              end
-            else
-              write_row = true
-            end
-            if write_row
-              xls_sheet.row(ri).height= r.format[:height] if r.format
-              r.each_with_index do |c, ci|
-                if c
-                  if r.header?
-                    xls_sheet.columns[ci] ||= Spreadsheet::Column.new(ci,nil)
-                    xls_sheet.columns[ci].width= c.format[:width]
-                  end
-                  xls_sheet.row(ri)[ci] = c.value
-                  xls_sheet.row(ri).set_format(ci, format_to_xls_format(c.format))
+            xls_sheet.row(ri).height= r.format[:height] if r.format
+            r.each_with_index do |c, ci|
+              if c
+                if r.header?
+                  xls_sheet.columns[ci] ||= Spreadsheet::Column.new(ci,nil)
+                  xls_sheet.columns[ci].width= c.format[:width]
                 end
+                xls_sheet.row(ri)[ci] = c.value
+                xls_sheet.row(ri).set_format(ci, format_to_xls_format(c.format))
               end
             end
           end
@@ -138,8 +132,12 @@ module Workbook
         numberformat.gsub('%Y','yyyy').gsub('%A','dddd').gsub('%B','mmmm').gsub('%a','ddd').gsub('%b','mmm').gsub('%y','yy').gsub('%d','dd').gsub('%m','mm').gsub('%y','y').gsub('%y','%%y').gsub('%e','d')
       end
       
-      def write_to_xls options={}
-        filename = options[:filename] ? options[:filename] : "#{title}.xls"
+      # Write the current workbook to Microsoft Excel format (using the spreadsheet gem)
+      #
+      # @param [String] the filename
+      # @param [Hash] options, see #to_xls 
+      
+      def write_to_xls filename="#{title}.xls", options={}
         if to_xls(options).write(filename)
           return filename
         end

data/readme.markdown

@@ -96,4 +96,12 @@ The [ruby toolbox lists plenty of alternatives](https://www.ruby-toolbox.com/sea
 
 ## License
 
-MIT... (c) murb / Maarten Brouwers, 2011-2012
+This code MIT (but see below) (c) murb / Maarten Brouwers, 2011-2013
+
+Workbook uses the following gems:
+
+* [Spreadsheet](https://github.com/zdavatz/spreadsheet) (Copyright (c) 2010 ywesee GmbH (mhatakeyama@ywesee.com, zdavatz@ywesee.com); GPL3 (License required for closed implementations))
+* [FasterCSV](http://fastercsv.rubyforge.org/) (Copyright (c) James Edward Gray II; GPL2 & Ruby License)
+* [rchardet](http://rubyforge.org/projects/rchardet) (Copyright (c) JMHodges; LGPL)
+* [ruby-ole](http://code.google.com/p/ruby-ole/) (Copyright (c) 2007-2010 Charles Lowe; MIT)
+* [RubyXL](https://github.com/gilt/rubyXL) (Copyright (c) 2011 Vivek Bhagwat; MIT-Licensed)

data/test/test_modules_table_diff_sort.rb

@@ -99,7 +99,7 @@ module Modules
       diff_result = tself.diff tother
       assert_equal('a',diff_result.sheet.table.header[0].value)
       assert_equal("a,b,c,d\n1,2,3,4\n3,2,3,4\n3,3 (was: 2),3,4\n4,2,3,4\n(was: 5),(was: 2),(was: 3),(was: 4)\n",diff_result.sheet.table.to_csv)
-      diff_result.write_to_xls({:rewrite_header=>true})
+      diff_result.write_to_xls
     end
   end
 end

data/test/test_readers_csv_reader.rb

@@ -31,7 +31,7 @@ module Readers
       assert_equal(Date.new(2001,1,1),w.sheet.table[1][:a].value)
       assert_equal(DateTime.new(2011,2,12,12,23),w.sheet.table[4][:c].value)
       assert_equal("6/12 ovk getekend terugontv.+>acq ter tekening. 13/12 ovk getekend terugontv.+>Fred ter tekening.", w.sheet.table[5][:b].value)
-      assert_equal(Date.new(2012,6,12),w.sheet.table[5][:c].value)
+      assert_equal(DateTime.new(Time.now.year,6,12),w.sheet.table[5][:c].value)
     end
     def test_excel_standardized_open
       w = Workbook::Book.new

data/test/test_readers_xls_reader.rb

@@ -44,7 +44,7 @@ module Readers
       w = Workbook::Book.new
       w.open("test/artifacts/txt_in_xls.xls")
       assert_equal([:naam,:nummer,:ilt,:corporate_key,:naam_medewerker, nil, nil, :telefoon, :openingsdatum],w.sheet.table.header.to_symbols)
-      assert_equal(["dddd",2222,"i9000","asd","Anita",nil,"Betera",DateTime.new(2012,1,12),Date.new(2011,10,5)],w.sheet.table[1].collect{|a| a.value})
+      assert_equal(["dddd",2222,"i9000","asd","Anita",nil,"Betera","012-3456789",Date.new(2011,10,5)],w.sheet.table[1].collect{|a| a.value})
     end
     def test_zip_in_xls_open
       w = Workbook::Book.new

data/test/test_writers_xls_writer.rb

@@ -20,6 +20,16 @@ module Writers
       b = Workbook::Book.open filename
       assert_equal(3.85546875,b.sheet.table.first[:a].format[:width])
     end
+    def test_cloning_roundtrip
+      b = Workbook::Book.open('test/artifacts/book_with_tabs_and_colours.xls')
+      b.sheet.table << b.sheet.table[2]
+      assert_equal(90588,b.sheet.table[5][:b].value)
+      assert_equal("#FFFF00",b.sheet.table[5][:c].format[:background_color])
+      filename = b.write_to_xls
+      b = Workbook::Book.open filename
+      assert_equal(90588,b.sheet.table[5][:b].value)
+      assert_equal("#FFFF00",b.sheet.table[5][:c].format[:background_color])
+    end
     
     def test_init_spreadsheet_template
       b = Workbook::Book.new

data/workbook.gemspec

@@ -5,12 +5,12 @@ require "workbook"
 Gem::Specification.new do |s|
   s.name        = 'workbook'
   s.rubyforge_project = 'workbook'
-  s.version     = '0.1.6.2'
-  s.date        = '2012-12-11'
+  s.version     = '0.2.0'
+  s.date        = '2013-01-10'
   s.summary     = "Workbook is a datastructure to contain books of tables (an anlogy used in e.g. Excel)"
   s.description = "Workbook contains workbooks, as in a table, contains rows, contains cells, reads/writes excels and csv's and tab separated, and offers basic diffing and sorting capabilities."
   s.authors     = ["Maarten Brouwers"]
-  s.add_dependency('spreadsheet', '>= 0.6.8')
+  s.add_dependency('spreadsheet', '>= 0.7.5')
   s.add_dependency('fastercsv')
   s.add_dependency("rchardet", "~> 1.3")
   s.add_dependency('rubyXL')

metadata

@@ -4,10 +4,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 0
-  - 1
-  - 6
   - 2
-  version: 0.1.6.2
+  - 0
+  version: 0.2.0
 platform: ruby
 authors: 
 - Maarten Brouwers
@@ -15,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2012-12-11 00:00:00 +01:00
+date: 2013-01-10 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -27,9 +26,9 @@ dependencies:
       - !ruby/object:Gem::Version 
         segments: 
         - 0
-        - 6
-        - 8
-        version: 0.6.8
+        - 7
+        - 5
+        version: 0.7.5
   type: :runtime
   version_requirements: *id001
 - !ruby/object:Gem::Dependency