spreadbase 0.1.3 → 0.1.4

data/README.md

@@ -1,8 +1,17 @@
+[![Build Status][BS img]](https://travis-ci.org/saveriomiroddi/spreadbase)
+
 SpreadBase!!
 ============
 
 ... because Excel IS a database.
 
+Status
+------
+
+The library itself is stable, and can be regularly used.
+
+I plan to add features on request, but if nobody asks for them, I will update the project very infrequently.
+
 What is SpreadBase©?
 --------------------
 
@@ -132,12 +141,7 @@ Notes
 
   `SpreadBase::Document.new( "Random numbers für alle!.ods", :floats_as_bigdecimal => true )`
 
-- The archives are always encoded in UTF-8. In Ruby 1.8.7, input strings are assumed to be UTF-8; if not, it's possible to open a document as:
-
-  `SpreadBase::Document.new( "Today's menu.ods", :force_18_strings_encoding => '<encoding>' )`
-
-  in order to override the input encoding.
-- The gem has been tested on Ruby 1.8.7 and 1.9.3-p125, on Linux and Mac OS X.
+- The gem has been tested on Ruby 1.9.3-p125, on Linux and Mac OS X.
 - The column widths are retained (decoding/encoding), but at the current version, they're not [officially] accessible via any API.
 
 Currently unsupported features
@@ -146,18 +150,9 @@ Currently unsupported features
 - Styles; Date and and [Date]Times are formatted as, respectively, '%Y-%m-%d' and '%Y-%m-%d %H:%M:%S %z'
 - Percentage data type - they're handled using their float value (e.g. 50% = 0.5)
 
-Supporting SpreadBase
----------------------
-
-If you find SpreadBase useful for any reason, I invite you to join Kiva.org, using this invitation:
-
-http://www.kiva.org/invitedby/saveriomiroddi
-
-it will cost you **nothing** (zero/0 €/£/$), it will take three to five minutes of your time, and you will have actively done something for economically disadvantaged countries.
-
-If you want to do more, in addition to accepting the invitation, you can donate to my Paypal account (saverio.pub2 \<a-hat!\> gmail.com) - I will publish your donation and use the entire amount for making loans using the mentioned website.
-
 Roadmap/Todo
 ------------
 
 https://github.com/saveriomiroddi/spreadbase/wiki/Todo-%28roadmap%29
+
+[BS img]: https://travis-ci.org/saveriomiroddi/spreadbase.svg?branch=master

data/Rakefile

@@ -0,0 +1,5 @@
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/docs/STRUCTURE.md

@@ -0,0 +1,3 @@
+- the base directory contains the abstract concept classes (document, table, etc.)
+- `codecs` contains the codec classes, for encoding/decoding
+- `helpers` contains functionality of generic nature

data/docs/TESTING.md

@@ -0,0 +1,11 @@
+Files
+=====
+
+- the `elements` suites test the abstract concept classes (document, table, etc.)
+- the `codecs` suites have functional testing (encode -> decode cycle) of each code, plus UTs for codec-specific functionalities
+- `spec_helpers.rb` are a few constants and methods useful for testing
+
+Methodology
+===========
+
+The general workflow is to write specific UTs, then extend the functional test(s), then test on files generated with Libreoffice (from Libreoffice-built to spreadbase, from spreadbase-built to Libreoffice, and from Libreoffice-build to spreadbase to Libreoffice), using the `utils` scripts.

data/lib/spreadbase/cell.rb

@@ -0,0 +1,19 @@
+module SpreadBase # :nodoc:
+
+  # Represents the abstraction of a cell; values and their types are merged into a single entity.
+  #
+  class Cell
+
+    attr_accessor :value
+
+    def initialize(value)
+      @value = value
+    end
+
+    def ==(other)
+      other.is_a?(Cell) && @value == other.value
+    end
+
+  end
+
+end

data/lib/spreadbase/codecs/open_document_12.rb

@@ -1,23 +1,3 @@
-# encoding: UTF-8
-
-=begin
-Copyright 2012 Saverio Miroddi saverio.pub2 <a-hat!> gmail.com
-
-This file is part of SpreadBase.
-
-SpreadBase is free software: you can redistribute it and/or modify it under the
-terms of the GNU Lesser General Public License as published by the Free Software
-Foundation, either version 3 of the License, or (at your option) any later
-version.
-
-SpreadBase is distributed in the hope that it will be useful, but WITHOUT ANY
-WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more details.
-
-You should have received a copy of the GNU Lesser General Public License along
-with SpreadBase.  If not, see <http://www.gnu.org/licenses/>.
-=end
-
 require 'zipruby'
 require 'rexml/document'
 
@@ -49,20 +29,19 @@ module SpreadBase # :nodoc:
       #
       # _options_:
       #
-      # +force_18_strings_encoding+::   ('UTF-8') on ruby 1.8, when converting to UTF-8, assume the strings are using the specified format.
       # +prettify+::                    (false )prettifies the content.xml to be human readable.
       #
       # _returns_ the archive as binary string.
       #
-      def encode_to_archive( el_document, options={} )
-        document_buffer = encode_to_content_xml( el_document, options )
+      def encode_to_archive(el_document, options={})
+        document_buffer = encode_to_content_xml(el_document, options)
         zip_buffer      = ''
 
-        Zip::Archive.open_buffer( zip_buffer, Zip::CREATE ) do | zip_file |
-          zip_file.add_dir( 'META-INF' )
+        Zip::Archive.open_buffer(zip_buffer, Zip::CREATE) do | zip_file |
+          zip_file.add_dir('META-INF')
 
-          zip_file.add_buffer( 'META-INF/manifest.xml', MANIFEST_XML    );
-          zip_file.add_buffer( 'content.xml',           document_buffer );
+          zip_file.add_buffer('META-INF/manifest.xml', MANIFEST_XML);
+          zip_file.add_buffer('content.xml',           document_buffer);
         end
 
         zip_buffer
@@ -81,12 +60,12 @@ module SpreadBase # :nodoc:
       #
       # _returns_ the SpreadBase::Document instance.
       #
-      def decode_archive( zip_buffer, options={} )
-        content_xml_data = Zip::Archive.open_buffer( zip_buffer ) do | zip_file |
-          zip_file.fopen( 'content.xml' ) { | file | file.read }
+      def decode_archive(zip_buffer, options={})
+        content_xml_data = Zip::Archive.open_buffer(zip_buffer) do | zip_file |
+          zip_file.fopen('content.xml') { | file | file.read }
         end
 
-        decode_content_xml( content_xml_data, options )
+        decode_content_xml(content_xml_data, options)
       end
 
       # Utility method; encodes the Document to the content.xml format.
@@ -97,18 +76,17 @@ module SpreadBase # :nodoc:
       #
       # _options_:
       #
-      # +force_18_strings_encoding+::   ('UTF-8') on ruby 1.8, when converting to UTF-8, assume the strings are using the specified format.
       # +prettify+::                    (false ) prettifies the content.xml to be human readable.
       #
       # _returns_ content.xml as string.
       #--
       # "utility" is a fancy name for testing/utils helper.
       #
-      def encode_to_content_xml( el_document, options={} )
-        prettify = options[ :prettify ]
+      def encode_to_content_xml(el_document, options={})
+        prettify = options[:prettify]
 
-        document_xml_root = encode_to_document_node( el_document, options )
-        document_buffer   = prettify ? pretty_xml( document_xml_root ) : document_xml_root.to_s
+        document_xml_root = encode_to_document_node(el_document)
+        document_buffer   = prettify ? pretty_xml(document_xml_root) : document_xml_root.to_s
 
         document_buffer
       end
@@ -123,20 +101,20 @@ module SpreadBase # :nodoc:
       #--
       # "utility" is a fancy name for testing/utils helper.
       #
-      def decode_content_xml( content_xml_data, options={} )
-        root_node = REXML::Document.new( content_xml_data )
+      def decode_content_xml(content_xml_data, options={})
+        root_node = REXML::Document.new(content_xml_data)
 
-        decode_document_node( root_node, options )
+        decode_document_node(root_node, options)
       end
 
       private
 
-      def pretty_xml( document )
+      def pretty_xml(document)
         buffer = ""
 
         xml_formatter = REXML::Formatters::Pretty.new
         xml_formatter.compact = true
-        xml_formatter.write( document, buffer )
+        xml_formatter.write(document, buffer)
 
         buffer
       end

data/lib/spreadbase/codecs/open_document_12_modules/decoding.rb

@@ -1,23 +1,3 @@
-# encoding: UTF-8
-
-=begin
-Copyright 2012 Saverio Miroddi saverio.pub2 <a-hat!> gmail.com
-
-This file is part of SpreadBase.
-
-SpreadBase is free software: you can redistribute it and/or modify it under the
-terms of the GNU Lesser General Public License as published by the Free Software
-Foundation, either version 3 of the License, or (at your option) any later
-version.
-
-SpreadBase is distributed in the hope that it will be useful, but WITHOUT ANY
-WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more details.
-
-You should have received a copy of the GNU Lesser General Public License along
-with SpreadBase.  If not, see <http://www.gnu.org/licenses/>.
-=end
-
 require 'date'
 require 'bigdecimal'
 
@@ -37,32 +17,32 @@ module SpreadBase # :nodoc:
 
         # Returns a Document instance.
         #
-        def decode_document_node( root_node, options={} )
+        def decode_document_node(root_node, options={})
           document = Document.new
 
-          style_nodes = root_node.elements.to_a( '//office:document-content/office:automatic-styles/style:style' )
-          table_nodes = root_node.elements.to_a( '//office:document-content/office:body/office:spreadsheet/table:table' )
+          style_nodes = root_node.elements.to_a('//office:document-content/office:automatic-styles/style:style')
+          table_nodes = root_node.elements.to_a('//office:document-content/office:body/office:spreadsheet/table:table')
 
-          document.column_width_styles = decode_column_width_styles( style_nodes )
+          document.column_width_styles = decode_column_width_styles(style_nodes)
 
-          document.tables = table_nodes.map { | node | decode_table_node( node, options ) }
+          document.tables = table_nodes.map { | node | decode_table_node(node, options) }
 
           document
         end
 
         # Currently it has only the purpose of decoding the column widths (for this reason it has a different naming convention).
         #
-        def decode_column_width_styles( style_nodes )
-          style_nodes.inject( {} ) do | column_width_styles, style_node |
-            column_node = style_node.elements[ 'style:table-column-properties' ]
+        def decode_column_width_styles(style_nodes)
+          style_nodes.inject({}) do | column_width_styles, style_node |
+            column_node = style_node.elements['style:table-column-properties']
 
             if column_node
-              column_width = column_node.attributes[ 'style:column-width' ]
+              column_width = column_node.attributes['style:column-width']
 
               if column_width
-                style_name = style_node.attributes[ 'style:name' ]
+                style_name = style_node.attributes['style:name']
 
-                column_width_styles[ style_name] = column_width
+                column_width_styles[style_name] = column_width
               end
             end
 
@@ -70,98 +50,98 @@ module SpreadBase # :nodoc:
           end
         end
 
-        def decode_table_node( table_node, options )
-          table = Table.new( table_node.attributes[ 'table:name' ] )
+        def decode_table_node(table_node, options)
+          table = Table.new(table_node.attributes['table:name'])
 
-          column_nodes = table_node.elements.to_a( 'table:table-column' )
-          row_nodes    = table_node.elements.to_a( 'table:table-row' )
+          column_nodes = table_node.elements.to_a('table:table-column')
+          row_nodes    = table_node.elements.to_a('table:table-row')
 
           # A single column/row can represent multiple columns (table:number-(columns|rows)-repeated)
           #
-          table.column_width_styles = column_nodes.inject( [] ) { | current_styles, node | current_styles + decode_column_width_style( node ) }
-          table.data                = row_nodes.inject( [] ) { | current_rows, node | current_rows + decode_row_node( node, options ) }
+          table.column_width_styles = column_nodes.inject([]) { | current_styles, node | current_styles + decode_column_width_style(node) }
+          table.data                = row_nodes.inject([]) { | current_rows, node | current_rows + decode_row_node(node, options) }
 
           table
         end
 
-        def decode_column_width_style( column_node )
-          repetitions = ( column_node.attributes[ 'table:number-columns-repeated' ] || '1' ).to_i
-          style_name  = column_node.attributes[ 'table:style-name' ]
+        def decode_column_width_style(column_node)
+          repetitions = (column_node.attributes['table:number-columns-repeated'] || '1').to_i
+          style_name  = column_node.attributes['table:style-name']
 
           # WATCH OUT! See module note
           #
-          make_array_from_repetitions( style_name, repetitions )
+          make_array_from_repetitions(style_name, repetitions)
         end
 
-        def decode_row_node( row_node, options )
-          repetitions = ( row_node.attributes[ 'table:number-rows-repeated' ] || '1' ).to_i
-          cell_nodes  = row_node.elements.to_a( 'table:table-cell' )
+        def decode_row_node(row_node, options)
+          repetitions = (row_node.attributes['table:number-rows-repeated'] || '1').to_i
+          cell_nodes  = row_node.elements.to_a('table:table-cell')
 
           # Watch out the :flatten; a single cell can represent multiple cells (table:number-columns-repeated)
           #
-          values = cell_nodes.map { | node | decode_cell_node( node, options ) }.flatten
+          values = cell_nodes.map { | node | decode_cell_node(node, options) }.flatten
 
-          make_array_from_repetitions( values, repetitions )
+          make_array_from_repetitions(values, repetitions)
         end
 
-        def decode_cell_node( cell_node, options )
-          floats_as_bigdecimal = options[ :floats_as_bigdecimal ]
+        def decode_cell_node(cell_node, options)
+          value = decode_cell_value(cell_node, options)
 
-          value_type = cell_node.attributes[ 'office:value-type' ]
+          repetitions = (cell_node.attributes['table:number-columns-repeated'] || '1').to_i
 
-          value = \
-            case value_type
-            when 'string'
-              value_node = cell_node.elements[ 'text:p' ]
+          make_array_from_repetitions(value, repetitions)
+        end
 
-              value_node.text
-            when 'date'
-              date_string = cell_node.attributes[ 'office:date-value' ]
+        def decode_cell_value(cell_node, options)
+          floats_as_bigdecimal = options[:floats_as_bigdecimal]
 
-              if date_string =~ /T/
-                DateTime.strptime( date_string, '%Y-%m-%dT%H:%M:%S' )
-              else
-                Date.strptime( date_string, '%Y-%m-%d' )
-              end
-            when 'float', 'percentage'
-              float_string = cell_node.attributes[ 'office:value' ]
-
-              if float_string.include?( '.' )
-                if floats_as_bigdecimal
-                  BigDecimal.new( float_string )
-                else
-                  float_string.to_f
-                end
-              else
-                float_string.to_i
-              end
-            when 'boolean'
-              boolean_string = cell_node.attributes[ 'office:boolean-value' ]
-
-              case boolean_string
-              when 'true'
-                true
-              when 'false'
-                false
+          value_type = cell_node.attributes['office:value-type']
+
+          case value_type
+          when 'string'
+            value_node = cell_node.elements['text:p']
+
+            value_node.text
+          when 'date'
+            date_string = cell_node.attributes['office:date-value']
+
+            if date_string =~ /T/
+              DateTime.strptime(date_string, '%Y-%m-%dT%H:%M:%S')
+            else
+              Date.strptime(date_string, '%Y-%m-%d')
+            end
+          when 'float', 'percentage'
+            float_string = cell_node.attributes['office:value']
+
+            if float_string.include?('.')
+              if floats_as_bigdecimal
+                BigDecimal(float_string)
               else
-                raise "Invalid boolean value: #{ boolean_string }"
+                float_string.to_f
               end
-            when nil
-              nil
             else
-              raise "Unrecognized value type found in a cell: #{ value_type }"
+              float_string.to_i
             end
-
-          repetitions = ( cell_node.attributes[ 'table:number-columns-repeated' ] || '1' ).to_i
-
-          make_array_from_repetitions( value, repetitions )
+          when 'boolean'
+            boolean_string = cell_node.attributes['office:boolean-value']
+
+            case boolean_string
+            when 'true'
+              true
+            when 'false'
+              false
+            else
+              raise "Invalid boolean value: #{ boolean_string }"
+            end
+          when nil
+            nil
+          else
+            raise "Unrecognized value type found in a cell: #{ value_type }"
+          end
         end
 
       end
 
-      private
-
-
     end
 
   end

data/lib/spreadbase/codecs/open_document_12_modules/encoding.rb

@@ -1,27 +1,6 @@
-# encoding: UTF-8
-
-=begin
-Copyright 2012 Saverio Miroddi saverio.pub2 <a-hat!> gmail.com
-
-This file is part of SpreadBase.
-
-SpreadBase is free software: you can redistribute it and/or modify it under the
-terms of the GNU Lesser General Public License as published by the Free Software
-Foundation, either version 3 of the License, or (at your option) any later
-version.
-
-SpreadBase is distributed in the hope that it will be useful, but WITHOUT ANY
-WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
-PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more details.
-
-You should have received a copy of the GNU Lesser General Public License along
-with SpreadBase.  If not, see <http://www.gnu.org/licenses/>.
-=end
-
 require 'rexml/document'
 require 'date'
 require 'bigdecimal'
-require 'iconv' if RUBY_VERSION < '1.9'
 
 module SpreadBase # :nodoc:
 
@@ -81,17 +60,17 @@ module SpreadBase # :nodoc:
 
         # Returns the XML root node
         #
-        def encode_to_document_node( el_document, options={} )
-          root_node        = REXML::Document.new( BASE_CONTENT_XML )
-          spreadsheet_node = root_node.elements[ '//office:document-content/office:body/office:spreadsheet' ]
-          styles_node      = root_node.elements[ '//office:document-content/office:automatic-styles'        ]
+        def encode_to_document_node(el_document)
+          root_node        = REXML::Document.new(BASE_CONTENT_XML)
+          spreadsheet_node = root_node.elements['//office:document-content/office:body/office:spreadsheet']
+          styles_node      = root_node.elements['//office:document-content/office:automatic-styles']
 
           el_document.column_width_styles.each do | style_name, column_width |
-            encode_style( styles_node, style_name, column_width )
+            encode_style(styles_node, style_name, column_width)
           end
 
           el_document.tables.each do | table |
-            encode_table( table, spreadsheet_node, options )
+            encode_table(table, spreadsheet_node)
           end
 
           root_node
@@ -99,91 +78,83 @@ module SpreadBase # :nodoc:
 
         # Currently only encodes column width styles
         #
-        def encode_style( styles_node, style_name, column_width )
-          style_node = styles_node.add_element( 'style:style', 'style:name' => style_name, 'style:family' => 'table-column' )
+        def encode_style(styles_node, style_name, column_width)
+          style_node = styles_node.add_element('style:style', 'style:name' => style_name, 'style:family' => 'table-column')
 
-          style_node.add_element( 'style:table-column-properties', 'style:column-width' => column_width )
+          style_node.add_element('style:table-column-properties', 'style:column-width' => column_width)
         end
 
-        def encode_table( table, spreadsheet_node, options={} )
-          table_node = spreadsheet_node.add_element( 'table:table' )
+        def encode_table(table, spreadsheet_node)
+          table_node = spreadsheet_node.add_element('table:table')
 
-          table_node.attributes[ 'table:name' ] = table.name
+          table_node.attributes['table:name'] = table.name
 
           table.column_width_styles.each do | style_name |
-            encode_column( table_node, style_name ) if style_name
+            encode_column(table_node, style_name) if style_name
           end
 
           # At least one column element is required
           #
-          table_node.add_element( 'table:table-column' ) if table.column_width_styles.size == 0
+          table_node.add_element('table:table-column') if table.column_width_styles.size == 0
 
-          table.data.each do | row |
-            encode_row( row, table_node, options )
+          table.data(as_cell: true).each do | row |
+            encode_row(row, table_node)
           end
         end
 
         # Currently only encodes column width styles
         #
-        def encode_column( table_node, style_name )
-          table_node.add_element( 'table:table-column', 'table:style-name' => style_name )
+        def encode_column(table_node, style_name)
+          table_node.add_element('table:table-column', 'table:style-name' => style_name)
         end
 
-        def encode_row( row, table_node, options={} )
-          row_node = table_node.add_element( 'table:table-row' )
+        def encode_row(row, table_node)
+          row_node = table_node.add_element('table:table-row')
 
-          row.each do | value |
-            encode_cell( value, row_node, options )
+          row.each do | cell |
+            encode_cell(cell.value, row_node)
           end
         end
 
-        def encode_cell( value, row_node, options={} )
-          force_18_strings_encoding = options[ :force_18_strings_encoding ] || 'UTF-8'
-
-          cell_node = row_node.add_element( 'table:table-cell' )
+        def encode_cell(value, row_node)
+          cell_node = row_node.add_element('table:table-cell')
 
           # WATCH OUT!!! DateTime.new.is_a?( Date )!!!
           #
           case value
           when String
-            cell_node.attributes[ 'office:value-type' ] = 'string'
-
-            cell_value_node = cell_node.add_element( 'text:p' )
+            cell_node.attributes['office:value-type'] = 'string'
 
-            if RUBY_VERSION >= '1.9'
-              value = value.encode( 'UTF-8' )
-            else
-              value = Iconv.conv( 'UTF-8', force_18_strings_encoding, value )
-            end
+            cell_value_node = cell_node.add_element('text:p')
 
-            cell_value_node.text = value
+            cell_value_node.text = value.encode('UTF-8')
           when Time, DateTime
-            cell_node.attributes[ 'office:value-type' ] = 'date'
-            cell_node.attributes[ 'table:style-name'  ] = 'datetime'
+            cell_node.attributes['office:value-type'] = 'date'
+            cell_node.attributes['table:style-name'] = 'datetime'
 
-            encoded_value = value.strftime( '%Y-%m-%dT%H:%M:%S' )
+            encoded_value = value.strftime('%Y-%m-%dT%H:%M:%S')
 
-            cell_node.attributes[ 'office:date-value' ] = encoded_value
+            cell_node.attributes['office:date-value'] = encoded_value
           when Date
-            cell_node.attributes[ 'office:value-type' ] = 'date'
-            cell_node.attributes[ 'table:style-name'  ] = 'date'
+            cell_node.attributes['office:value-type'] = 'date'
+            cell_node.attributes['table:style-name'] = 'date'
 
-            encoded_value = value.strftime( '%Y-%m-%d' )
+            encoded_value = value.strftime('%Y-%m-%d')
 
-            cell_node.attributes[ 'office:date-value' ] = encoded_value
+            cell_node.attributes['office:date-value'] = encoded_value
           when BigDecimal
-            cell_node.attributes[ 'office:value-type' ] = 'float'
+            cell_node.attributes['office:value-type'] = 'float'
 
-            cell_node.attributes[ 'office:value' ] = value.to_s( 'F' )
-          when Float, Fixnum
-            cell_node.attributes[ 'office:value-type' ] = 'float'
+            cell_node.attributes['office:value'] = value.to_s('F')
+          when Float, Integer
+            cell_node.attributes['office:value-type'] = 'float'
 
-            cell_node.attributes[ 'office:value' ] = value.to_s
+            cell_node.attributes['office:value'] = value.to_s
           when true, false
-            cell_node.attributes[ 'office:value-type' ] = 'boolean'
-            cell_node.attributes[ 'table:style-name'  ] = 'boolean'
+            cell_node.attributes['office:value-type'] = 'boolean'
+            cell_node.attributes['table:style-name'] = 'boolean'
 
-            cell_node.attributes[ 'office:boolean-value' ] = value.to_s
+            cell_node.attributes['office:boolean-value'] = value.to_s
           when nil
             # do nothing
           else