spreadbase 0.1.2 → 0.3.0

data/README.md

@@ -1,8 +1,17 @@
+[![CI](https://github.com/saveriomiroddi/spreadbase/actions/workflows/ci.yml/badge.svg)](https://github.com/saveriomiroddi/spreadbase/actions/workflows/ci.yml)
+
 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©?
 --------------------
 
@@ -53,6 +62,27 @@ Append a row:
 
     table_2.append_row( [ 'Fabrizio F.' ] )
 
+Read a column, or a range of columns:
+
+    table.column( 0 )
+
+    # [ 'Dish', 'Roasted 6502', '8080, with an 8-bit bus', '65000 with side dishes of Copper and Blitter' ]
+
+    table.column( 0 .. 1 )
+
+    # [ [ 'Dish',  'Roasted 6502', '8080, with an 8-bit bus', '65000 with side dishes of Copper and Blitter' ],
+    #   [ 'Price', 38.911,         8,                         512.0                                          ] ]
+
+Read a row, or a range of rows:
+
+    table.row( 1 )
+
+    # [ 'Roasted 6502', 38.911 ]
+
+    table.row( 1 .. 2 )
+
+    # [ [ 'Roasted 6502', 38.911 ], [ '8080, with an 8-bit bus', 8 ] ]
+
 Read a cell:
 
     price_8080 = document.tables[ 0 ][ 1, 2 ]
@@ -101,20 +131,17 @@ Save the document:
 
     document.save
 
+Enjoy many other APIs.
+
 Notes
 -----
 
 - Numbers are decoded to Fixnum or Float, depending on the existence of the fractional part.
   Alternatively, numbers with a fractional part can be decoded as Bigdecimal, using the option:
 
-  `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>' )`
+  `SpreadBase::Document.new( "Random numbers für alle!.ods", floats_as_bigdecimal: true )`
 
-  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 is tested on all the supported Ruby versions (see [Build](https://github.com/saveriomiroddi/spreadbase/actions/workflows/ci.yml)), and used mainly on Linux.
 - The column widths are retained (decoding/encoding), but at the current version, they're not [officially] accessible via any API.
 
 Currently unsupported features
@@ -123,17 +150,6 @@ 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
 ------------
 

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.rb

@@ -1,33 +1,12 @@
-# encoding: UTF-8
+require_relative 'spreadbase/helpers/helpers'
 
-=begin
-Copyright 2012 Saverio Miroddi saverio.pub2 <a-hat!> gmail.com
+require_relative 'spreadbase/document'
+require_relative 'spreadbase/table'
+require_relative 'spreadbase/cell'
 
-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 'rubygems'
-
-require File.expand_path( '../spreadbase/helpers/helpers', __FILE__ )
-
-require File.expand_path( '../spreadbase/document', __FILE__ )
-require File.expand_path( '../spreadbase/table',    __FILE__ )
-
-require File.expand_path( '../spreadbase/codecs/open_document_12_modules/encoding', __FILE__ )
-require File.expand_path( '../spreadbase/codecs/open_document_12_modules/decoding', __FILE__ )
-require File.expand_path( '../spreadbase/codecs/open_document_12',                  __FILE__ )
+require_relative 'spreadbase/codecs/open_document_12_modules/encoding'
+require_relative 'spreadbase/codecs/open_document_12_modules/decoding'
+require_relative 'spreadbase/codecs/open_document_12'
 
 # = Spreadbase
 #

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,24 +1,4 @@
-# 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 'zip'
 require 'rexml/document'
 
 module SpreadBase # :nodoc:
@@ -49,20 +29,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_ 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_file.add_buffer( 'META-INF/manifest.xml', MANIFEST_XML    );
-          zip_file.add_buffer( 'content.xml',           document_buffer );
+        Zip::File.open_buffer(zip_buffer) do | zip_file |
+          zip_file.get_output_stream('META-INF/manifest.xml') { |f| f << MANIFEST_XML }
+          zip_file.get_output_stream('content.xml') { |f| f << document_buffer }
         end
 
         zip_buffer
@@ -81,12 +58,11 @@ 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 }
-        end
+      def decode_archive(zip_buffer, options={})
+        io = StringIO.new(zip_buffer)
+        content_xml_data = Zip::File.new(io, false, true).read('content.xml')
 
-        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 +73,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 +98,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,123 @@ 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                = decode_row_nodes(row_nodes, 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_nodes(row_nodes, options)
+          rows = []
+          row_nodes.inject(0) do |size, node|
+            row, repetitions = decode_row_node(node, options)
+            row.empty? || append_row(rows, size, row, repetitions)
+            size + repetitions
+          end
+          rows
+        end
 
-          # 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
+        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')
 
-          make_array_from_repetitions( values, repetitions )
+          [decode_cell_nodes(cell_nodes, options), repetitions]
         end
 
-        def decode_cell_node( cell_node, options )
-          floats_as_bigdecimal = options[ :floats_as_bigdecimal ]
+        def append_row(rows, size, row, repetitions)
+          (size - rows.size).times { rows << [] }
+          rows.concat(make_array_from_repetitions(row, repetitions))
+        end
 
-          value_type = cell_node.attributes[ 'office:value-type' ]
+        def decode_cell_nodes(cell_nodes, options)
+          cells = []
+          cell_nodes.inject(0) do |size, node|
+            cell, repetitions = decode_cell_node(node, options)
+            cell.nil? || append_cell(cells, size, cell, repetitions)
+            size + repetitions
+          end
+          cells
+        end
 
-          value = \
-            case value_type
-            when 'string'
-              value_node = cell_node.elements[ 'text:p' ]
+        def decode_cell_node(cell_node, options)
+          [
+            decode_cell_value(cell_node, options),
+            (cell_node.attributes['table:number-columns-repeated'] || '1').to_i
+          ]
+        end
 
-              value_node.text
-            when 'date'
-              date_string = cell_node.attributes[ 'office:date-value' ]
+        def append_cell(cells, size, cell, repetitions)
+          cells[size - 1] = nil if size != cells.size
+          cells.concat(make_array_from_repetitions(cell, repetitions))
+        end
 
-              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
+        def decode_cell_value(cell_node, options)
+          floats_as_bigdecimal = options[:floats_as_bigdecimal]
+
+          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