spreadbase 0.1.2

data/lib/spreadbase/table.rb

@@ -0,0 +1,273 @@
+# 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
+
+module SpreadBase # :nodoc:
+
+  # Represents the abstraction of a table and its contents.
+  #
+  # The max width of the table is 1024 cells - the last one being 'AMJ'.
+  #
+  # Row indexing follows the ruby semantics:
+  # - negative indexes represent an access starting from the end of an array
+  # - out-of-bounds access will return nil where a row is accessed as a whole, and raise an error when a cell has to be accessed.
+  #
+  class Table
+
+    include SpreadBase::Helpers
+
+    attr_accessor :name, :data
+
+    # Array of style names; nil when not associated to any column width.
+    #
+    attr_accessor :column_width_styles # :nodoc:
+
+    # _params_:
+    #
+    # +name+::                       (required) Name of the table
+    # +data+::                       (Array.new) 2d matrix of the data. if not empty, the rows need to be all of the same size
+    #
+    def initialize( name, data=[] )
+      raise "Table name required" if name.nil? || name == ''
+
+      @name                = name
+      @data                = data
+      @column_width_styles = []
+    end
+
+    # Access a cell value.
+    #
+    # _params_:
+    #
+    # +column_indentifier+::         either an int (0-based) or the excel-format identifier (AA...); limited to the given row size.
+    # +row_index+::                  int (0-based). see notes about the rows indexing.
+    #
+    # _returns_ the value, which is automatically converted to the Ruby data type.
+    #
+    def []( column_identifier, row_index )
+      row          = row( row_index )
+      column_index = decode_column_identifier( column_identifier )
+
+      check_column_index( row, column_index )
+
+      row[ column_index ]
+    end
+
+    # Writes a value in a cell.
+    #
+    # _params_:
+    #
+    # +column_indentifier+::         either an int (0-based) or the excel-format identifier (AA...); limited to the given row size.
+    # +row_index+::                  int (0-based). see notes about the rows indexing.
+    # +value+::                      value
+    #
+    def []=( column_identifier, row_index, value )
+      row          = row( row_index )
+      column_index = decode_column_identifier( column_identifier )
+
+      check_column_index( row, column_index )
+
+      row[ column_index ] = value
+    end
+
+    # Returns an array containing the values of a single row.
+    #
+    # _params_:
+    #
+    # +row_index+::                  int (0-based). see notes about the rows indexing.
+    #
+    def row( row_index )
+      check_row_index( row_index )
+
+      @data[ row_index ]
+    end
+
+    # Deletes a row.
+    #
+    # This operation won't modify the column width styles in any case.
+    #
+    # _params_:
+    #
+    # +row_index+::                  int (0-based). see notes about the rows indexing.
+    #
+    # _returns_ the deleted row
+    #
+    def delete_row( row_index )
+      check_row_index( row_index )
+
+      @data.slice!( row_index )
+    end
+
+    # Inserts a row.
+    #
+    # This operation won't modify the column width styles in any case.
+    #
+    # _params_:
+    #
+    # +row_index+::                  int (0-based). must be between 0 and (including) the table rows size.
+    # +row+::                        array of values. if the table is not empty, must have the same size of the table width.
+    #
+    def insert_row( row_index, row )
+      check_row_index( row_index, :allow_append => true )
+
+      @data.insert( row_index, row )
+    end
+
+    # This operation won't modify the column width styles in any case.
+    #
+    def append_row( row )
+      insert_row( @data.size, row )
+    end
+
+    # Returns an array containing the values of a single column.
+    #
+    # WATCH OUT! This method doesn't have the range restrictions that axis indexes generally has, that is, it's possible to access a column outside the boundaries of the rows - it will return nil for each of those values.
+    #
+    # _params_:
+    #
+    # +column_indentifier+::         either an int (0-based) or the excel-format identifier (AA...).
+    #                                when int, follow the same idea of the rows indexing (ruby semantics).
+    #
+    def column( column_identifier )
+      column_index = decode_column_identifier( column_identifier )
+
+      @data.map do | row |
+        row[ column_index ]
+      end
+    end
+
+    # Deletes a column.
+    #
+    # WATCH OUT! This method doesn't have the range restrictions that axis indexes generally has, that is, it's possible to delete a column outside the boundaries of the rows - it will return nil for each of those values.
+    #
+    # _params_:
+    #
+    # +column_indentifier+::         either an int (0-based) or the excel-format identifier (AA...).
+    #                                when int, follow the same idea of the rows indexing (ruby semantics).
+    #
+    # _returns_ the deleted column
+    #
+    def delete_column( column_identifier )
+      column_index = decode_column_identifier( column_identifier )
+
+      @column_width_styles.slice!( column_index )
+
+      @data.map do | row |
+        row.slice!( column_index )
+      end
+    end
+
+    # Inserts a column.
+    #
+    # WATCH OUT! This method doesn't have the range restrictions that axis indexes generally has, that is, it's possible to insert a column outside the boundaries of the rows - it will fill the cells in the middle with nils..
+    #
+    # _params_:
+    #
+    # +column_indentifier+::         either an int (0-based) or the excel-format identifier (AA...).
+    #                                when int, follow the same idea of the rows indexing (ruby semantics).
+    # +column+::                     array of values. if the table is not empty, it must have the same size of the table height.
+    #
+    def insert_column( column_identifier, column )
+      raise "Inserting column size (#{ column.size }) different than existing columns size (#{ @data.size })" if @data.size > 0 && column.size != @data.size
+
+      column_index = decode_column_identifier( column_identifier )
+
+      @column_width_styles.insert( column_index, nil )
+
+      if @data.size > 0
+        @data.zip( column ).each do | row, value |
+          row.insert( column_index, value )
+        end
+      else
+        @data = column.map { | value | [ value ] }
+      end
+
+    end
+
+    def append_column( column )
+      column_index = @data.size > 0 ? @data.first.size : 0
+
+      insert_column( column_index, column )
+    end
+
+    # _returns_ a matrix representation of the tables, with the values being separated by commas.
+    #
+    def to_s( options={} )
+      pretty_print_rows( @data, options )
+    end
+
+    private
+
+    # Check that row index points to an existing record, or, in case of :allow_append,
+    # point to one unit above the last row.
+    #
+    # _options_:
+    #
+    # +allow_append+::      Allow pointing to one unit above the last row.
+    #
+    def check_row_index( row_index, options={} )
+      allow_append = options [ :allow_append ]
+
+      positive_limit = allow_append ? @data.size : @data.size - 1
+
+      raise "Invalid row index (#{ row_index }) - allowed 0 to #{ positive_limit }" if row_index < 0 || row_index > positive_limit
+    end
+
+    def check_column_index( row, column_index )
+      raise "Invalid column index (#{ column_index }) for the given row - allowed 0 to #{ row.size - 1 }" if column_index >= row.size
+    end
+
+    # Accepts either an integer, or a MoFoBase26BisexNumber.
+    #
+    # Raises an error for invalid identifiers/indexes.
+    #
+    # _returns_ a 0-based decimal number.
+    #--
+    # Motherf#### base-26 bijective numeration - I would have gladly saved my f* time. At least
+    # there were a few cute ladies at the Charleston lesson.
+    #
+    def decode_column_identifier( column_identifier )
+      if column_identifier.is_a?( Fixnum )
+        raise "Negative column indexes not allowed: #{ column_identifier }" if column_identifier < 0
+
+        column_identifier
+      else
+        letters       = column_identifier.upcase.chars.to_a
+        upcase_a_ord  = 65
+
+        raise "Invalid letter for in column identifier (allowed 'a/A' to 'z/Z')" if letters.any? { | letter | letter < 'A' || letter > 'Z' }
+
+        base_10_value = letters.inject( 0 ) do | sum, letter |
+          letter_ord = letter.unpack( 'C' ).first
+          sum * 26 + ( letter_ord - upcase_a_ord + 1 )
+        end
+
+        base_10_value -= 1
+
+        # -1 is an empty string
+        #
+        raise "Invalid literal column identifier (allowed 'A' to 'AMJ')" if base_10_value < 0 || 1023 < base_10_value
+
+        base_10_value
+      end
+    end
+
+  end
+
+end

data/lib/spreadbase/version.rb

@@ -0,0 +1,5 @@
+# encoding: UTF-8
+
+module SpreadBase
+  VERSION = "0.1.2"
+end

data/lib/spreadbase.rb

@@ -0,0 +1,37 @@
+# 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 '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__ )
+
+# = Spreadbase
+#
+# See https://github.com/saveriomiroddi/spreadbase for usage.
+#
+module SpreadBase
+end

data/spec/codecs/open_document_12_spec.rb

@@ -0,0 +1,137 @@
+# 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 File.expand_path( '../../../lib/spreadbase', __FILE__ )
+require File.expand_path( '../../spec_helpers',      __FILE__ )
+
+require 'date'
+require 'bigdecimal'
+
+include SpecHelpers
+
+# See testing notes.
+#
+describe SpreadBase::Codecs::OpenDocument12 do
+
+  before :each do
+    table_1 = SpreadBase::Table.new(
+      'abc', [
+        [ 1,      1.1,        T_BIGDECIMAL ],
+        [ T_DATE, T_DATETIME, T_TIME       ],
+        [ nil,    'a',        nil          ]
+      ]
+    )
+
+    table_2 = SpreadBase::Table.new( 'cde' )
+
+    @sample_document = SpreadBase::Document.new
+
+    @sample_document.tables << table_1 << table_2
+  end
+
+  # :encode/:decode
+  #
+  it "should encode and decode the sample document" do
+    document_archive = SpreadBase::Codecs::OpenDocument12.new.encode_to_archive( @sample_document )
+
+    document = SpreadBase::Codecs::OpenDocument12.new.decode_archive( document_archive, :floats_as_bigdecimal => true )
+
+    assert_size( document.tables, 2 ) do | table_1, table_2 |
+
+      table_1.name.should == 'abc'
+
+      assert_size( table_1.data, 3 ) do | row_1, row_2, row_3 |
+
+        assert_size( row_1, 3 ) do | value_1, value_2, value_3 |
+          value_1.should == 1
+          value_1.should be_a( Fixnum )
+          value_2.should == 1.1
+          value_2.should be_a( BigDecimal )
+          value_3.should == T_BIGDECIMAL
+          value_3.should be_a( BigDecimal )
+        end
+
+        assert_size( row_2, 3 ) do | value_1, value_2, value_3 |
+          value_1.should == T_DATE
+          value_2.should == T_DATETIME
+          value_3.should == T_DATETIME
+        end
+
+        assert_size( row_3, 3 ) do | value_1, value_2, value_3 |
+          value_1.should == nil
+          value_2.should == 'a'
+          value_3.should == nil
+        end
+
+      end
+
+      table_2.name.should == 'cde'
+
+      assert_size( table_2.data, 0 )
+    end
+  end
+
+  # Not worth testing in detail; just ensure that the pref
+  #
+  it "should encode the document with makeup (:prettify) - SMOKE" do
+    formatter = stub_initializer( REXML::Formatters::Pretty )
+
+    formatter.should_receive( :write )
+
+    SpreadBase::Codecs::OpenDocument12.new.encode_to_archive( @sample_document, :prettify => true )
+  end
+
+  # Those methods are actually "utility" (read: testing) methods.
+  #
+  it "should encode/decode the content.xml - SMOKE" do
+    content_xml = SpreadBase::Codecs::OpenDocument12.new.encode_to_content_xml( @sample_document )
+
+    document = SpreadBase::Codecs::OpenDocument12.new.decode_content_xml( content_xml )
+
+    assert_size( document.tables, 2 )
+  end
+
+  # If values are not converted to UTF-8, some encodings cause an error to be
+  # raised when assigning a value to a cell.
+  #
+  # 1.8 tests can't be done, since the official platform is 1.9
+  #
+  it "should convert to utf-8 before saving" do
+    string = "à".encode( 'UTF-16' )
+
+    @sample_document.tables[ 0 ][ 0,  0 ] = string
+
+    # Doesn't encode correctly if the value is not converted
+    #
+    SpreadBase::Codecs::OpenDocument12.new.encode_to_content_xml( @sample_document )
+  end
+
+  it "should decode as BigDecimal" do
+    content_xml = SpreadBase::Codecs::OpenDocument12.new.encode_to_content_xml( @sample_document )
+
+    document = SpreadBase::Codecs::OpenDocument12.new.decode_content_xml( content_xml, :floats_as_bigdecimal => true )
+
+    value = document.tables[ 0 ][ 2, 0 ]
+
+    value.should be_a( BigDecimal )
+    value.should == T_BIGDECIMAL
+  end
+
+end

data/spec/elements/document_spec.rb

@@ -0,0 +1,134 @@
+# 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 File.expand_path( '../../../lib/spreadbase', __FILE__ )
+require File.expand_path( '../../spec_helpers',      __FILE__ )
+
+include SpecHelpers
+
+describe SpreadBase::Document do
+
+  before :each do
+    @sample_document = SpreadBase::Document.new
+    @sample_document.tables = [
+      SpreadBase::Table.new(
+        'abc', [
+          [ 1,      1.1,        T_BIGDECIMAL ],
+          [ T_DATE, T_DATETIME, T_TIME       ],
+          [ true,   'a',        nil          ]
+        ]
+      )
+    ]
+  end
+
+  # :-D
+  #
+  it "should initialize out of thin air" do
+    document = SpreadBase::Document.new
+
+    document.document_path.should == nil
+
+    document.tables.should be_empty
+  end
+
+  # A lazy use of stubs
+  #
+  it "should initialize from a file" do
+    codec = stub_initializer( SpreadBase::Codecs::OpenDocument12 )
+
+    File.should_receive( :'exists?' ).with( '/pizza/margerita.txt' ).and_return( true )
+    IO.should_receive( :read ).with( '/pizza/margerita.txt' ).and_return( 'abc' )
+    codec.should_receive( :decode_archive ).with( 'abc', {} ).and_return( @sample_document )
+
+    document = SpreadBase::Document.new( '/pizza/margerita.txt' )
+
+    assert_size( document.tables, 1 ) do | table |
+      table.name.should == 'abc'
+      table.data.size.should == 3
+    end
+  end
+
+  it "should initialize with a non-existing file" do
+    codec = stub_initializer( SpreadBase::Codecs::OpenDocument12 )
+
+    document = SpreadBase::Document.new( '/pizza/margerita.txt' )
+
+    assert_size( document.tables, 0 )
+  end
+
+  it "should save to a file" do
+    codec = stub_initializer( SpreadBase::Codecs::OpenDocument12 )
+
+    document = SpreadBase::Document.new
+    document.tables << SpreadBase::Table.new( 'Ya-ha!' )
+    document.document_path = '/tmp/abc.ods'
+
+    codec.should_receive( :encode_to_archive ).with( document, :prettify => 'abc' ).and_return( 'sob!' )
+    File.should_receive( :open ).with( '/tmp/abc.ods', 'wb' )
+
+    document.save( :prettify => 'abc' )
+  end
+
+  it "should raise an error when trying to save without a filename" do
+    document = SpreadBase::Document.new
+    document.tables << SpreadBase::Table.new( 'Ya-ha!' )
+
+    lambda { document.save }.should raise_error( RuntimeError, "Document path not specified" )
+  end
+
+  it "should raise an error when trying to save without tables" do
+    document = SpreadBase::Document.new
+    document.document_path = 'abc.ods'
+
+    lambda { document.save }.should raise_error( RuntimeError, "At least one table must be present" )
+  end
+
+  it "should return the data as string (:to_s)" do
+    expected_string = "\
+abc:
+
+  +------------+---------------------------+---------------------------+
+  | 1          | 1.1                       | 0.133E1                   |
+  | 2012-04-10 | 2012-04-11T23:33:42+00:00 | 2012-04-11 23:33:42 +0200 |
+  | true       | a                         |                           |
+  +------------+---------------------------+---------------------------+
+
+"
+
+    @sample_document.to_s.should == expected_string
+  end
+
+  it "should return the data as string, with headers (:to_s)" do
+    expected_string = "\
+abc:
+
+  +------------+---------------------------+---------------------------+
+  | 1          | 1.1                       | 0.133E1                   |
+  +------------+---------------------------+---------------------------+
+  | 2012-04-10 | 2012-04-11T23:33:42+00:00 | 2012-04-11 23:33:42 +0200 |
+  | true       | a                         |                           |
+  +------------+---------------------------+---------------------------+
+
+"
+
+    @sample_document.to_s( :with_headers => true ).should == expected_string
+  end
+
+end