oxcelix 0.3.0 → 0.3.1

data/CHANGES

@@ -1,21 +1,12 @@
-* Further code cleanup in numformats.rb Tue Dec 3 19:49:03 2013 +0100
-* Renamed add to add_custom_formats Tue Dec 3 19:46:15 2013 +0100
-* Path cleanup Tue Dec 3 19:07:47 2013 +0100
-* Added documentation to Formatarray. Fixed bug which prevented cells containing e.g. String values AND datetime/numeric formatting code to be properly returned when to_ru or to_fmt was invoked. Code cleanup. Tue Dec 3 19:06:39 2013 +0100
-* Numberhelper included in Cell class. Various typos corrected. Cell#to_ru and Cell#to_fmt now reflect the inclusion of the Numberformats module. Mon Dec 2 23:27:52 2013 +0100
-* to_ru and to_fmt methods are now encapsulated in the Numhelper method. This is not only cleaner, ensures them to be included in Cell and only there. Mon Dec 2 23:04:13 2013 +0100
-* Cleared @numformats from Workbook. Formatarray is now a Numformats module constant available to any class including it. Mon Dec 2 22:47:40 2013 +0100
-* Numformat is now included in Workbook. Dtmap became a constant. New method Numformats::add converts the temparray to a series of numformat hashes and adds it to the main numformat array. to_ru, to_fmt, datetime, numeric are now Workbook methods. Slight code cleanup. Sun Dec 1 19:28:41 2013 +0100
-* Numformats.rb cleanup. Documented new modules/methods. Restructured to_ru and to_fmt. Fri Nov 29 09:23:41 2013 +0100
-* Code cleanup. TODO: split format string (;)? cellhelper.rb to be cleaned up Mon Nov 25 00:06:38 2013 +0100
-* finalized numeric method with a regex composed by 6 members: prefix, decimals, separator, floats, expo, postfix. This obsoletes the vgrp method as well as the other ones (still in the numformats.rb file.) TODO: delete all unnecessary code and provide a meaningful return value. Mon Nov 25 00:00:52 2013 +0100
-* Added Numformats Sat Nov 23 09:48:50 2013 +0100
-* Merge branch '0.3.0' of https://github.com/gbiczo/oxcelix into 0.3.0 Sat Nov 23 09:43:59 2013 +0100
-* Added numformats.rb. Cleaned styles.rb from unnecessary comments. Sat Nov 23 09:41:10 2013 +0100
-* Added badge Fri Nov 22 12:20:48 2013 +0100
-* Some speed optimizations. matrixto does not accept fmt parameter any more. fixed typos Wed Nov 13 00:03:44 2013 +0100
-* Cell now has a numformat attribute. A new module called Numformats will contain methods related to numeric formatting. to_r and to_d are now obsolete. Xlsheet init parameter (styles). Stylefile is opened in the workbook. Matrixto gets a :values option (this will be obsoleted shortly). Slight Gemspec and .md description change Mon Nov 4 17:47:17 2013 +0100
-* Initial version of Sheet::to_m method Sat Oct 19 11:06:42 2013 +0200
-* Format array is now a constant (FARY) Fri Oct 18 21:58:39 2013 +0200
-* Fixed typo in README Fri Oct 18 21:51:09 2013 +0200
-* Started working on cell value formats Fri Oct 18 21:50:24 2013 +0200
+0.3.1
+* Sheet now has its very own to_ru and to_fmt methods. Also a to_m method has been added, which returns a Matrix of raw data.
+* Documentation changes.
+0.3.0
+* Number formats edition that includes:
+  Cell#to_ru and Cell#to_fmt.
+  Numberformats module
+  Numberhelper module
+0.2.4
+* Bugfix release
+0.2.2
+* Sheet < Matrix

data/README.md

@@ -1,5 +1,6 @@
 Oxcelix
 =======
+<a href="http://badge.fury.io/rb/oxcelix"><img src="https://badge.fury.io/rb/oxcelix@2x.png" alt="Gem Version" height="18"></a>
 
 Oxcelix - A fast and simple .xlsx file parser
 
@@ -16,20 +17,59 @@ Oxcelix uses the great Ox gem (http://rubygems.org/gems/ox) for fast SAX-parsing
 Synopsis
 --------
 
-To process an xlsx file:
+  To process an xlsx file:
 
-`require 'oxcelix'`
+    `require 'oxcelix'`
+    `w = Oxcelix::Workbook.new('whatever.xlsx')`
 
-`w = Oxcelix::Workbook.new('whatever.xlsx')`
+  To omit certain sheets:
 
-To omit certain sheets:
+    `w = Oxcelix::Workbook.new('whatever.xlsx', :exclude => ['sheet1', 'sheet2'])`
 
-`w = Oxcelix::Workbook.new('whatever.xlsx', :exclude => ['sheet1', 'sheet2'])`
+  Include only some of the sheets:
 
-To include only some of the sheets:
+    `w = Oxcelix::Workbook.new('whatever.xlsx', :include => ['sheet1', 'sheet2', 'sheet3'])`
 
-`w = Oxcelix::Workbook.new('whatever.xlsx', :include => ['sheet1', 'sheet2', 'sheet3'])`
+  To have the values of the merged cells copied over the mergegroup:
 
-To have the values of the merged cells copied over the mergegroup:
+    `w = Oxcelix::Workbook.new('whatever.xlsx', :copymerge => true)`
+  
+  Convert a Sheet object into a collection of ruby values or formatted ruby strings:
+    `require 'oxcelix'`
+    `w = Oxcelix::Workbook.new('whatever.xlsx', :copymerge => true)`
+    `w.sheets[0].to_ru # returns a Matrix of DateTime, Integer, etc objects`
+    `w.sheets[0].to_fmt # returns a Matrix of formatted Strings based on the above.`
 
-`w = Oxcelix::Workbook.new('whatever.xlsx', :mergecells => true)`
+Installation
+------------
+
+  `gem install oxcelix`
+
+
+Advantages over other Excel parsers
+-----------------------------------
+
+Excel file processing involves XML document parsing. Usually, this is achieved by some XML library such as Nokogiri[http://nokogiri.org].
+
+
+The main drawbacks of this approach are memory usage and speed. The resulting object tree will be roughly as big
+as the original file, and during the parsing, they will both be stored in the memory, which can
+cause quite some complications when processing huge files. Also, interpreting every bit of an excel spreadsheet
+will slow down unnecessarily the process, if we only need the data stored in that file.
+
+
+The solution for the memory-consumption problem is SAX stream parsing.
+
+
+Oxcelix uses the SAX parser offered by Peter Ohler's Ox gem. Ox is fast and powerful enough to solve the speed issue.
+
+
+For a comparison of XML parsers, please consult the Ox homepage[http://www.ohler.com/dev/xml_with_ruby/xml_with_ruby.html].
+
+TODO
+----
+  * Implement RawWorkbook, ValueWorkbook, FormattedWorkbook
+  * include/exclude mechanism should extend to cell areas inside Sheet objects
+  * Possible speedups
+  * Further improvement to the formatting algorithms. Theoretically, to_fmt should be able to
+    split conditional-formatting strings and to display e.g. thousands separated number strings

data/README.rdoc

@@ -23,10 +23,45 @@ To omit certain sheets to be processed:
 
   w = Oxcelix::Workbook.new('whatever.xlsx', :exclude => ['sheet1', 'sheet2'])
 
-To include only some of the sheets:
+Include only some of the sheets:
 
   w = Oxcelix::Workbook.new('whatever.xlsx', :include => ['sheet1', 'sheet2', 'sheet3'])
 
 To have the values of the merged cells copied over the mergegroup:
 
   w = Oxcelix::Workbook.new('whatever.xlsx', :copymerge => true)
+
+Convert a Sheet object into a collection of ruby values or formatted ruby strings:
+  require 'oxcelix'
+  w = Oxcelix::Workbook.new('whatever.xlsx', :copymerge => true)
+  w.sheets[0].to_ru # returns a Matrix of DateTime, Integer, etc objects
+  w.sheets[0].to_fmt # returns a Matrix of formatted Strings based on the above.
+
+== Installation
+
+  gem install oxcelix
+
+== Advantages over other Excel parsers
+Excel file processing involves XML document parsing. Usually, this is achieved by some XML library such as Nokogiri[http://nokogiri.org].
+
+
+The main drawbacks of this approach are memory usage and speed. The resulting object tree will be roughly as big
+as the original file, and during the parsing, they will both be stored in the memory, which can
+cause quite some complications when processing huge files. Also, interpreting every bit of an excel spreadsheet
+will slow down unnecessarily the process, if we only need the data stored in that file.
+
+
+The solution for the memory-consumption problem is SAX stream parsing.
+
+
+Oxcelix uses the SAX parser offered by Peter Ohler's Ox gem. Ox is fast and powerful enough to solve the speed issue.
+
+
+For a comparison of XML parsers, please consult the Ox homepage[http://www.ohler.com/dev/xml_with_ruby/xml_with_ruby.html].
+
+== TODO
+  * Implement RawWorkbook, ValueWorkbook, FormattedWorkbook
+  * include/exclude mechanism should extend to cell areas inside Sheet objects
+  * Possible speedups
+  * Further improvement to the formatting algorithms. Theoretically, to_fmt should be able to
+    split conditional-formatting strings and to display e.g. thousands separated number strings

data/lib/oxcelix/numformats.rb

@@ -76,30 +76,39 @@ module Oxcelix
     module Numberhelper
       include Numformats
       # Get the cell's value and excel format string and return a string, a ruby Numeric or a DateTime object accordingly
+      # @return [Object] A ruby object that holds and represents the value stored in the cell. Conversion is based on cell formatting.
+      # @example Get the value of a cell:
+      #   c = w.sheets[0]["B3"] # => <Oxcelix::Cell:0x00000002a5b368 @xlcoords="A3", @style="84", @type="n", @value="41155", @numformat=14>
+      #   c.to_ru # => <DateTime: 2012-09-03T00:00:00+00:00 ((2456174j,0s,0n),+0s,2299161j)>
+      #
       def to_ru
         if !@value.numeric? || Numformats::Formatarray[@numformat.to_i][:xl] == nil || Numformats::Formatarray[@numformat.to_i][:xl].downcase == "general"
           return @value
         end
-        if Numformats::Formatarray[@numformat.to_i][:cls] == 'numeric' || Numformats::Formatarray[@numformat.to_i][:cls] == 'rational'
-          return eval @value
-        elsif Numformats::Formatarray[@numformat.to_i][:cls] == 'date'
+        if Numformats::Formatarray[@numformat.to_i][:cls] == 'date'
           return DateTime.new(1899, 12, 30) + (eval @value)
-        else
-          eval @value rescue @value
+        else Numformats::Formatarray[@numformat.to_i][:cls] == 'numeric' || Numformats::Formatarray[@numformat.to_i][:cls] == 'rational'
+            return eval @value rescue @value
         end
       end
 
       # Get the cell's value, convert it with to_ru and finally, format it based on the value's type.
+      # @return [String] Value gets formatted depending on its class. If it is a DateTime, the #DateTime.strftime method is used,
+      # if it holds a number, the #Kernel::sprintf is run.
+      # @example Get the formatted value of a cell:
+      #   c = w.sheets[0]["B3"] # => <Oxcelix::Cell:0x00000002a5b368 @xlcoords="A3", @style="84", @type="n", @value="41155", @numformat=14>
+      #   c.to_fmt # => "3/9/2012"
+      #
       def to_fmt
         begin
           if Numformats::Formatarray[@numformat][:cls] == 'date'
-            self.to_ru.strftime(datetime(Numformats::Formatarray[@numformat][:xl])) rescue @value
+              self.to_ru.strftime(Numformats::Formatarray[@numformat][:ostring]) rescue @value
           elsif Numformats::Formatarray[@numformat.to_i][:cls] == 'numeric' || Numformats::Formatarray[@numformat.to_i][:cls] == 'rational'
-            sprintf(numeric(Numformats::Formatarray[@numformat][:xl]), self.to_ru) rescue @value
+              sprintf(Numformats::Formatarray[@numformat][:ostring], self.to_ru) rescue @value
           else
             return @value
           end
         end
       end
     end
-  end
+  end

data/lib/oxcelix/sheet.rb

@@ -3,6 +3,7 @@ module Oxcelix
   # The Sheet class represents an excel sheet.
   class Sheet < Matrix
     include Cellhelper
+    include Numberhelper
   # @!attribute [rw] name
   #   @return [String] Sheet name
   # @!attribute [rw] sheetId
@@ -25,15 +26,50 @@ module Oxcelix
         super(i,j[0])
       end
     end
-
+    
+    #The to_m method returns a simple Matrix object filled with the raw values of the original Sheet object.
+    # @return [Matrix] a collection of string values (the former #Cell::value)
     def to_m(*attrs)
-      m=Matrix.build(self.col(0).length, self.row(0).length){nil}
-      self.each do |x, row, col|
+      m=Matrix.build(self.row_size, self.column_size){nil}
+      self.each_with_index do |x, row, col|
         if attrs.size == 0 || attrs.nil?
-          m[row, col]=x.value
+          m[row, col] = x.value
+        end
+      end
+      return m
+    end
+    
+    # The to_ru method returns a Matrix of "rubified" values. It basically builds a new Matrix
+    # and puts the result of the #Cell::to_ru method of every cell of the original sheet in
+    # the corresponding Matrix cell.
+    # @return [Matrix] a collection of ruby objects (#Integers, #Floats, #DateTimes, #Rationals, #Strings)
+    def to_ru
+      m=Matrix.build(self.row_size, self.column_size){nil}
+      self.each_with_index do |x, row, col|
+        if x.nil? || x.value.nil?
+          m[row, col] = nil
+        else
+          m[row, col] = x.to_ru
         end
       end
       return m
     end
-  end
+    
+    # The to_fmt method returns a Matrix of "formatted" values. It basically builds a new Matrix
+    # and puts the result of the #Cell::to_fmt method of every cell of the original sheet in
+    # the corresponding Matrix cell. The #Cell::to_fmt will pass the original values to to_ru, and then
+    # depending on the value, will run strftime on DateTime objects and sprintf on numeric types.
+    # @return [Matrix] a collection of Strings
+    def to_fmt
+      m=Matrix.build(self.row_size, self.column_size){nil}
+      self.each_with_index do |x, row, col|
+        if x.nil? || x.value.nil?
+          m[row, col] = nil
+        else
+          m[row, col] = x.to_fmt
+        end
+     end
+     return m
+   end
+ end
 end

data/oxcelix.gemspec

@@ -3,8 +3,8 @@
 require 'rake'
 Gem::Specification.new do |s|
   s.name	= 'oxcelix'
-  s.version	= '0.3.0'
-  s.date	= '2013-11-12'
+  s.version	= '0.3.1'
+  s.date	= '2013-12-07'
   s.summary	= 'A fast Excel 2007/2010 file parser'
   s.description	= 'A fast Excel 2007/2010 (.xlsx) file parser that returns a collection of Matrix objects'
   s.authors	= 'Giovanni Biczo'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: oxcelix
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-11-12 00:00:00.000000000 Z
+date: 2013-12-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ox