rods 0.5.1 → 0.6.0

data/README

@@ -5,7 +5,7 @@
  manipulates the XML-files in the zipped *.ods-container.
 
  On my website http://ruby.homelinux.com/ruby/rods/ you can see the output of the script below.
- You can contact me at rodsdotrubyatonlinedotde.
+ You can contact me at rodsdotrubyatonlinedotde (and drop me a line, if you like it ;-).
 
  link:images/Rods.jpg
  
@@ -14,6 +14,11 @@
  Licensed under the same terms as Ruby. No warranty is provided.
 
  = Changelog
+ * 0.5.2
+   * changed interface from
+     * getNextRow, getPreviousRow, getNextCell, getPreviousCell to
+     * getNextExistentRow, getPreviousExistentRow, getNextExistentCell, getPreviousExistentCell
+   See explanation below
  * 0.5.1 
    * made readCellFromRow() more user-friendly by returning defaults for text and type where 
      till recently error-messages were thrown due to missing values
@@ -47,10 +52,26 @@
    * OpenOffice.org 3.0 (German)
    * Ruby 1.9.1 and 1.8.7
  
+ = What you must know
+ When you open a (new) spreadsheet in an application like OpenOffice.org, you'll see an infinity of empty cells and
+ might be tempted to assume that all these cells actually "exist" in the underlying file format/XML-structure.
+ This is not the case ! A "newly born" spreadsheet does not contain even a single cell ! They're created on demand along
+ with all other cells of lesser x- or y-coordinate.
+ That is: If you write a cell with coordinates (10,10) all cells from (1,1) to (10,10)
+ spring into existence or vice versa: If the cell farthest down the sheet and farthest to the right
+ having a visible value has coordinates (90,87), then all cells from row 1-90 and column 1-87 exist, 
+ but no cell out of this virutal rectangle is "alive".
+ This is very important for using the interface appropriately: All routines matching 'Existent' merely return "living"
+ cells, while all other routines bearing a "get|Get" create a row or cell if necessary (and implicitly all other cells
+ within the new boundaries).
+ In other words: Use
+ * getNextExistentRow, getPreviousExistentRow, getNextExistentCell, getPreviousExistentCell
+   whenever you just want to read values you already have (seemlessly skipping visibly emtpy lines and columns) and
+ * getCell, writeGetCell and writeGetCellFromRow whenever you want a cell to be created if it does not exist (which
+   is undoubtedly the case, when you want to write to it or assign it a style) !
+ The first return nil, if an element does not exist yet, the second always return the desired element.
+ 
  = Howto
- Please consider the hints in the next chapter to boost performance when walking
- your way through many rows. But first the basics:
-
    $ sudo gem install rods (root-privileges necessary)
  
    # coding: UTF-8
@@ -274,17 +295,10 @@
      puts("Read #{text1} of #{type1} and #{text2} of #{type2}
    }
 
- in spite of the fact that
-   getRow 
- even creates a row if it does not yet exist (returns the specified row in any case !), while
-   readCell
- merely looks up exisiting rows and cells (returns nil,nil otherwise).
-
  This difference hardly matters while dealing with small documents, but degrades performance significantly when you 
  move up or down a sheet with a lot of rows and process several cells on the same row !
 
- Provided you just want to read exisiting cells and not write to at the user level seemingly empty ones, but de facto
- non-existent cells according to Open Document format, an absolute speed-booster compared to the above is the following
+ Provided you just want to read exisiting cells (i.e. cells with "visible values"), the following is a real speed-buster.
 
    # coding: UTF-8
    #
@@ -299,15 +313,16 @@
    row=mySheet.getRow(1)
    #---------------------------------------------------------------------------------
    # The routines
-   # - getNextRow(row)
-   # - getPreviousRow(row)
-   # - getNextCell(cell)
-   # - getPreviousCell(cell)
+   # - getNextExistentRow(row)
+   # - getPreviousExistentRow(row)
+   # - getNextExistentCell(cell)
+   # - getPreviousExistentCell(cell)
    # allow the XML-Parser to just continue from the "adjacent" node and 
    # return the previsous/next element without having to start from the top-node 
    # of the document over and over again !
+   # 
    #---------------------------------------------------------------------------------
-   while(row=mySheet.getNextRow(row))  
+   while(row=mySheet.getNextExistentRow(row))  
      i+=1
      puts("#{i}")
      confirmed,type=mySheet.readCellFromRow(row,1)

data/Rakefile

@@ -2,8 +2,8 @@ require 'rubygems'
 require 'rake'
 require 'echoe'
 
-Echoe.new('rods', '0.5.1') do |p|
-  p.description    = "OpenOffice.org oocalc: Fast automated batch-processing of spreadsheets (*.ods) conforming to Open Document Format v1.1. used by e.g. OpenOffice.org and LibreOffice. Please see screenshot and Rdoc-Documentation at http://ruby.homelinux.com/ruby/rods/. You can contact me at rodsdotrubyatonlinedotde."
+Echoe.new('rods', '0.6.0') do |p|
+  p.description    = "OpenOffice.org oocalc: Fast automated batch-processing of spreadsheets (*.ods) conforming to Open Document Format v1.1. used by e.g. OpenOffice.org and LibreOffice. Please see screenshot and Rdoc-Documentation at http://ruby.homelinux.com/ruby/rods/. You can contact me at rodsdotrubyatonlinedotde (and drop me a line, if you like it ;-)"
   p.summary        = "Automation of OpenOffice/LibreOffice by batch-processing of spreadsheets conforming to Open Document v1.1"
   p.url            = "http://ruby.homelinux.com/ruby/rods/"
   p.author         = "Dr. Heinz Breinlinger"

data/lib/rods.rb

@@ -2460,32 +2460,36 @@ class Rods
   # Fast Routine to get the previous row, because XML-Parser does not have
   # to start from top-node of document to find row ! 
   # Returns previous row as a REXML::Element or nil if no element exists.
+  # Cf. explanation in README !
   #------------------------------------------------------------------------
-  def getPreviousRow(row)
+  def getPreviousExistentRow(row)
     return row.previous_sibling
   end
   ##########################################################################
   # Fast Routine to get the next cell, because XML-Parser does not have
   # to start from top-node of row to find cell ! 
   # Returns next cell as a REXML::Element or nil if no element exists
+  # Cf. explanation in README !
   #------------------------------------------------------------------------
-  def getNextCell(cell)
+  def getNextExistentCell(cell)
     return cell.next_sibling
   end
   ##########################################################################
   # Fast Routine to get the previous cell, because XML-Parser does not have
   # to start from top-node of row to find cell ! 
   # Returns previous cell as a REXML::Element or nil if no element exists
+  # Cf. explanation in README !
   #------------------------------------------------------------------------
-  def getPreviousCell(cell)
+  def getPreviousExistentCell(cell)
     return cell.previous_sibling
   end
   ##########################################################################
   # Fast Routine to get the next row, because XML-Parser does not have
   # to start from top-node of document to find row ! 
   # Returns next row as a REXML::Element or nil if no element exists
+  # Cf. explanation in README !
   #------------------------------------------------------------------------
-  def getNextRow(row)
+  def getNextExistentRow(row)
     return row.next_sibling
   end
   ##########################################################################
@@ -2507,8 +2511,8 @@ class Rods
   public :setDateFormat, :writeGetCell, :writeCell, :writeGetCellFromRow, :writeCellFromRow, 
          :getCellFromRow, :getCell, :getRow, :renameTable, :setCurrentTable, 
          :insertTable, :deleteTable, :readCellFromRow, :readCell, :setAttributes, :writeStyleAbbr, 
-         :setStyle, :printOfficeStyles, :printAutoStyles, :getNextRow, :getPreviousRow, 
-	 :getNextCell, :getPreviousCell,
+         :setStyle, :printOfficeStyles, :printAutoStyles, :getNextExistentRow, :getPreviousExistentRow, 
+	 :getNextExistentCell, :getPreviousExistentCell,
          :writeComment, :save, :saveAs, :initialize, :writeText
 
   private :tell, :die, :createCell, :createRow, :getChildByIndex, :createElement, :setRepetition, :initHousekeeping, 

data/rods.gemspec

@@ -2,12 +2,12 @@
 
 Gem::Specification.new do |s|
   s.name = %q{rods}
-  s.version = "0.5.1"
+  s.version = "0.6.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
   s.authors = ["Dr. Heinz Breinlinger"]
   s.date = %q{2011-01-07}
-  s.description = %q{OpenOffice.org oocalc: Fast automated batch-processing of spreadsheets (*.ods) conforming to Open Document Format v1.1. used by e.g. OpenOffice.org and LibreOffice. Please see screenshot and Rdoc-Documentation at http://ruby.homelinux.com/ruby/rods/. You can contact me at rodsdotrubyatonlinedotde.}
+  s.description = %q{OpenOffice.org oocalc: Fast automated batch-processing of spreadsheets (*.ods) conforming to Open Document Format v1.1. used by e.g. OpenOffice.org and LibreOffice. Please see screenshot and Rdoc-Documentation at http://ruby.homelinux.com/ruby/rods/. You can contact me at rodsdotrubyatonlinedotde (and drop me a line, if you like it ;-)}
   s.email = %q{rods.ruby@online.de}
   s.extra_rdoc_files = ["README", "lib/example.rb", "lib/rods.rb"]
   s.files = ["Manifest", "README", "Rakefile", "lib/example.rb", "lib/rods.rb", "rods.gemspec"]

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: rods
 version: !ruby/object:Gem::Version 
-  hash: 9
+  hash: 7
   prerelease: false
   segments: 
   - 0
-  - 5
-  - 1
-  version: 0.5.1
+  - 6
+  - 0
+  version: 0.6.0
 platform: ruby
 authors: 
 - Dr. Heinz Breinlinger
@@ -19,7 +19,7 @@ date: 2011-01-07 00:00:00 +01:00
 default_executable: 
 dependencies: []
 
-description: "OpenOffice.org oocalc: Fast automated batch-processing of spreadsheets (*.ods) conforming to Open Document Format v1.1. used by e.g. OpenOffice.org and LibreOffice. Please see screenshot and Rdoc-Documentation at http://ruby.homelinux.com/ruby/rods/. You can contact me at rodsdotrubyatonlinedotde."
+description: "OpenOffice.org oocalc: Fast automated batch-processing of spreadsheets (*.ods) conforming to Open Document Format v1.1. used by e.g. OpenOffice.org and LibreOffice. Please see screenshot and Rdoc-Documentation at http://ruby.homelinux.com/ruby/rods/. You can contact me at rodsdotrubyatonlinedotde (and drop me a line, if you like it ;-)"
 email: rods.ruby@online.de
 executables: []