spreadbase 0.1.2

data/.gitignore

@@ -0,0 +1,2 @@
+.rvmrc
+temp/

data/COPYING.LESSER

@@ -0,0 +1,165 @@
+                   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions.
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version.
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.

data/README.md

@@ -0,0 +1,140 @@
+SpreadBase!!
+============
+
+... because Excel IS a database.
+
+What is SpreadBase©?
+--------------------
+
+SpreadBase© is a set of APIs for programmatically accessing spreadsheets (currently, only OpenDocument 1.2).
+
+Usage
+-----
+
+Install/require the gem:
+
+    gem install spreadbase
+
+    require 'spreadbase'
+
+Create/open a document:
+
+    document = SpreadBase::Document.new( "Today's menu.ods" )
+
+Add a table:
+
+    document.tables << SpreadBase::Table.new(
+      'Transistors', [
+        [ 'Roasted 6502',                                 38.911 ],
+        [ '65000 with side dishes of Copper and Blitter', 512.0  ],
+      ]
+    )
+
+Modify an existing table; can be done also directly on the array:
+
+    table = document.tables.first
+
+    table.insert_row( 0, [ 'Dish',                    'Price' ] )
+    table.insert_row( 2, [ '8080, with an 8-bit bus', 8       ] )
+
+    table.insert_column( 2, [ 'Availability', Date.today, Time.now + 42, 'Never!!' ] )
+
+Add another (empty) table:
+
+    table_2 = SpreadBase::Table.new( 'Loud and annoying customers' )
+
+    document.tables << table_2
+
+Append a column:
+
+    table_2.append_column( [ 'Name' ] )
+
+Append a row:
+
+    table_2.append_row( [ 'Fabrizio F.' ] )
+
+Read a cell:
+
+    price_8080 = document.tables[ 0 ][ 1, 2 ]
+
+When a cell value is read from an existing file, the data type is directly converted to the closest ruby one.
+
+Write to a cell:
+
+    document.tables[ 0 ][ 1, 2 ] = price_8080 + 0.080
+
+Print a table:
+
+    puts document.tables[ 0 ].to_s( :with_headers => true )
+
+    +----------------------------------------------+--------+---------------------------+
+    | Dish                                         | Price  | Availability              |
+    +----------------------------------------------+--------+---------------------------+
+    | Roasted 6502                                 | 38.911 | 2012-04-21                |
+    | 8080, with an 8-bit bus                      | 8.08   | 2012-04-21 11:45:08 +0200 |
+    | 65000 with side dishes of Copper and Blitter | 512.0  | Never!!                   |
+    +----------------------------------------------+--------+---------------------------+
+
+Print a document:
+
+    puts document.to_s( :with_headers => true )
+
+    Transistors:
+
+      +----------------------------------------------+--------+---------------------------+
+      | Dish                                         | Price  | Availability              |
+      +----------------------------------------------+--------+---------------------------+
+      | Roasted 6502                                 | 38.911 | 2012-04-21                |
+      | 8080, with an 8-bit bus                      | 8.08   | 2012-04-21 11:45:08 +0200 |
+      | 65000 with side dishes of Copper and Blitter | 512.0  | Never!!                   |
+      +----------------------------------------------+--------+---------------------------+
+
+    Loud and annoying customers:
+
+      +-------------+
+      | Name        |
+      +-------------+
+      | Fabrizio F. |
+      +-------------+
+
+Save the document:
+
+    document.save
+
+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>' )`
+
+  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 column widths are retained (decoding/encoding), but at the current version, they're not [officially] accessible via any API.
+
+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

data/lib/spreadbase/codecs/open_document_12.rb

@@ -0,0 +1,148 @@
+# 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'
+
+module SpreadBase # :nodoc:
+
+  module Codecs # :nodoc:
+
+    # Interface for OpenDocument 1. encoding/decoding.
+    #
+    class OpenDocument12
+
+      MANIFEST_XML = %Q[\
+<?xml version="1.0" encoding="UTF-8"?>
+<manifest:manifest xmlns:manifest="urn:oasis:names:tc:opendocument:xmlns:manifest:1.0" manifest:version="1.2">
+  <manifest:file-entry manifest:media-type="application/vnd.oasis.opendocument.spreadsheet" manifest:version="1.2" manifest:full-path="/"/>
+  <manifest:file-entry manifest:media-type="text/xml" manifest:full-path="content.xml"/>
+</manifest:manifest>] # :nodoc:
+
+      include OpenDocument12Modules::Encoding
+      include OpenDocument12Modules::Decoding
+
+      # Encode a Document to an OpenDocument archive.
+      #
+      # The generated archive contains the strictly necessary data required to have a consistent archive.
+      #
+      # _params_:
+      #
+      # +el_document+::                 SpreadBase::Document instance
+      #
+      # _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 )
+        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 );
+        end
+
+        zip_buffer
+      end
+
+      # Decode an OpenDocument archive.
+      #
+      # _params_:
+      #
+      # +zip_buffer+::            archive as binary string.
+      #                           if it's been read from the disk, don't forget to read in binary fmode.
+      #
+      # _options_:
+      #
+      # +floats_as_bigdecimal+::  (false) decode floats as BigDecimal instead of Float
+      #
+      # _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
+
+        decode_content_xml( content_xml_data, options )
+      end
+
+      # Utility method; encodes the Document to the content.xml format.
+      #
+      # _params_:
+      #
+      # +el_document+::                  SpreadBase::Document instance
+      #
+      # _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 ]
+
+        document_xml_root = encode_to_document_node( el_document, options )
+        document_buffer   = prettify ? pretty_xml( document_xml_root ) : document_xml_root.to_s
+
+        document_buffer
+      end
+
+      # Utility method; decode the content.xml belonging to an OpenDocument archive.
+      #
+      # _options_:
+      #
+      # +floats_as_bigdecimal+::        (false) decode floats as BigDecimal instead of Float
+      #
+      # _returns_ the SpreadBase::Document instance.
+      #--
+      # "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 )
+
+        decode_document_node( root_node, options )
+      end
+
+      private
+
+      def pretty_xml( document )
+        buffer = ""
+
+        xml_formatter = REXML::Formatters::Pretty.new
+        xml_formatter.compact = true
+        xml_formatter.write( document, buffer )
+
+        buffer
+      end
+
+    end
+
+  end
+
+end

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

@@ -0,0 +1,169 @@
+# 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'
+
+module SpreadBase # :nodoc:
+
+  module Codecs # :nodoc:
+
+    module OpenDocument12Modules # :nodoc:
+
+      # Module containing the decoding routines of the OpenDocument12 format.
+      #
+      module Decoding
+
+        include SpreadBase::Helpers
+
+        private
+
+        # Returns a Document instance.
+        #
+        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' )
+
+          document.column_width_styles = decode_column_width_styles( style_nodes )
+
+          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' ]
+
+            if column_node
+              column_width = column_node.attributes[ 'style:column-width' ]
+
+              if column_width
+                style_name = style_node.attributes[ 'style:name' ]
+
+                column_width_styles[ style_name] = column_width
+              end
+            end
+
+            column_width_styles
+          end
+        end
+
+        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' )
+
+          # 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
+        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' ]
+
+          # WATCH OUT! See module note
+          #
+          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' )
+
+          # 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
+
+          make_array_from_repetitions( values, repetitions )
+        end
+
+        def decode_cell_node( cell_node, options )
+          floats_as_bigdecimal = options[ :floats_as_bigdecimal ]
+
+          value_type = cell_node.attributes[ 'office:value-type' ]
+
+          value = \
+            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.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
+              else
+                raise "Invalid boolean value: #{ boolean_string }"
+              end
+            when nil
+              nil
+            else
+              raise "Unrecognized value type found in a cell: #{ value_type }"
+            end
+
+          repetitions = ( cell_node.attributes[ 'table:number-columns-repeated' ] || '1' ).to_i
+
+          make_array_from_repetitions( value, repetitions )
+        end
+
+      end
+
+      private
+
+
+    end
+
+  end
+
+end