ruby-spreadsheet 0.6.5

data/.document

@@ -0,0 +1,5 @@
+lib/**/*.rb
+bin/*
+- 
+features/**/*.feature
+LICENSE.txt

data/GUIDE.txt

@@ -0,0 +1,267 @@
+= Getting Started with Spreadsheet
+This guide is meant to get you started using Spreadsheet. By the end of it,
+you should be able to read and write Spreadsheets.
+
+
+== Reading is easy!
+First, make sure all that code is loaded:
+
+  require 'spreadsheet'
+
+Worksheets come in various Encodings. You need to tell Spreadsheet which
+Encoding you want to deal with. The Default is UTF-8
+
+  Spreadsheet.client_encoding = 'UTF-8'
+
+Let's open a workbook:
+
+  book = Spreadsheet.open '/path/to/an/excel-file.xls'
+
+We can either access all the Worksheets in a Workbook...
+
+  book.worksheets
+
+...or access them by index or name (encoded in your client_encoding)
+
+  sheet1 = book.worksheet 0
+  sheet2 = Book.worksheet 'Sheet1'
+
+Now you can either iterate over all rows that contain some data. A call to
+Worksheet.each without argument will omit empty rows at the beginning of the
+Worksheet:
+
+  sheet1.each do |row|
+    # do something interesting with a row
+  end
+
+Or you can tell Worksheet how many rows should be omitted at the beginning.
+The following starts at the 3rd row, regardless of whether or not it or the
+preceding rows contain any data:
+
+  sheet2.each 2 do |row|
+    # do something interesting with a row
+  end
+
+Or you can access rows directly, by their index (0-based):
+
+  row = sheet1.row(3)
+
+To access the values stored in a Row, treat the Row like an Array.
+
+  row[0]
+
+-> this will return a String, a Float, an Integer, a Formula, a Link or a Date
+or DateTime object - or nil if the cell is empty.
+
+More information about the formatting of a cell can be found in the Format
+with the equivalent index
+
+  row.format 2
+
+
+== Writing is easy
+As before, make sure you have Spreadsheet required and the client_encoding
+set. Then make a new Workbook:
+
+  book = Spreadsheet::Workbook.new
+
+Add a Worksheet and you're good to go:
+
+  sheet1 = book.create_worksheet
+
+This will create a Worksheet with the Name "Worksheet1". If you prefer another
+name, you may do either of the following:
+
+  sheet2 = book.create_worksheet :name => 'My Second Worksheet'
+  sheet1.name = 'My First Worksheet'
+
+Now, add data to the Worksheet, using either Worksheet#[]=,
+Worksheet#update_row, or work directly on Row using any of the Array-Methods
+that modify an Array in place:
+
+  sheet1.row(0).concat %w{Name Country Acknowlegement}
+  sheet1[1,0] = 'Japan'
+  row = sheet1.row(1)
+  row.push 'Creator of Ruby'
+  row.unshift 'Yukihiro Matsumoto'
+  sheet1.row(2).replace [ 'Daniel J. Berger', 'U.S.A.',
+                          'Author of original code for Spreadsheet::Excel' ]
+  sheet1.row(3).push 'Charles Lowe', 'Author of the ruby-ole Library'
+  sheet1.row(3).insert 1, 'Unknown'
+  sheet1.update_row 4, 'Hannes Wyss', 'Switzerland', 'Author'
+
+Add some Formatting for flavour:
+
+  sheet1.row(0).height = 18
+
+  format = Spreadsheet::Format.new :color => :blue,
+                                   :weight => :bold,
+                                   :size => 18
+  sheet1.row(0).default_format = format
+
+  bold = Spreadsheet::Format.new :weight => :bold
+  4.times do |x| sheet1.row(x + 1).set_format(0, bold) end
+
+And finally, write the Excel File:
+
+  book.write '/path/to/output/excel-file.xls'
+
+
+== Modifying an existing Document
+
+Spreadsheet has some limited support for modifying an existing Document. This
+is done by copying verbatim those parts of an Excel-document which Spreadsheet
+can't modify (yet), recalculating relevant offsets, and writing the data that
+can be changed.
+Here's what should work:
+* Adding, changing and deleting cells.
+* You should be able to fill in Data to be evaluated by predefined Formulas
+Limitations:
+* Spreadsheet can only write BIFF8 (Excel97 and higher). The results of
+  modifying an earlier version of Excel are undefined.
+* Spreadsheet does not modify Formatting at present. That means in particular
+  that if you set the Value of a Cell to a Date, it can only be read as a
+  Date if its Format was set correctly prior to the change.
+* Although it is theoretically possible, it is not recommended to write the
+  resulting Document back to the same File/IO that it was read from.
+
+And here's how it works:
+
+  book = Spreadsheet.open '/path/to/an/excel-file.xls'
+  sheet = book.worksheet 0
+  sheet.each do |row|
+    row[0] *= 2
+  end
+  book.write '/path/to/output/excel-file.xls'
+
+
+== Date and DateTime
+Excel does not know a separate Datatype for Dates. Instead it encodes Dates
+into standard floating-point numbers and recognizes a Date-Cell by its
+formatting-string:
+
+  row.format(3).number_format
+
+Whenever a Cell's Format describes a Date or Time, Spreadsheet will give you
+the decoded Date or DateTime value. Should you need to access the underlying
+Float, you may do the following:
+
+  row.at(3)
+
+If for some reason the Date-recognition fails, you may force Date-decoding:
+
+  row.date(3)
+  row.datetime(3)
+
+When you set the value of a Cell to a Date, Time or DateTime, Spreadsheet will
+try to set the cell's number-format to a corresponding value (one of Excel's
+builtin formats). If you have already defined a Date- or DateTime-format,
+Spreadsheet will use that instead. If a format has already been applied to
+a particular Cell, Spreadsheet will leave it untouched:
+
+  row[4] = Date.new 1975, 8, 21
+  # -> assigns the builtin Date-Format: 'M/D/YY'
+  book.add_format Format.new(:number_format => 'DD.MM.YYYY hh:mm:ss')
+  row[5] = DateTime.new 2008, 10, 12, 11, 59
+  # -> assigns the added DateTime-Format: 'DD.MM.YYYY hh:mm:ss'
+  row.set_format 6, Format.new(:number_format => 'D-MMM-YYYY')
+  row[6] = Time.new 2008, 10, 12
+  # -> the Format of cell 6 is left unchanged.
+
+== Outline (Grouping) and Hiding
+Spreadsheet supports outline (grouping) and hiding functions from version 
+0.6.5. In order to hide rows or columns, you can use 'hidden' property. 
+As for outline, 'outline_level' property is also available. You can use 
+both 'hidden' and 'outline_level' at the same time.
+
+You can create a new file with outline and hiding rows and columns as
+follows:
+
+  require 'spreadsheet'
+  
+  # create a new book and sheet
+  book = Spreadsheet::Workbook.new
+  sheet = book.create_worksheet
+  5.times {|j| 5.times {|i| sheet[j,i] = (i+1)*10**j}}
+  
+  # column
+  sheet.column(2).hidden = true
+  sheet.column(3).hidden = true
+  sheet.column(2).outline_level = 1
+  sheet.column(3).outline_level = 1
+  
+  # row
+  sheet.row(2).hidden = true
+  sheet.row(3).hidden = true
+  sheet.row(2).outline_level = 1
+  sheet.row(3).outline_level = 1
+  
+  # save file
+  book.write 'out.xls'
+
+Also you can read an existing file and change the hidden and outline
+properties. Here is the example below:
+
+  require 'spreadsheet'
+  
+  # read an existing file
+  file = ARGV[0]
+  book = Spreadsheet.open(file, 'rb')
+  sheet= book.worksheet(0)
+  
+  # column
+  sheet.column(2).hidden = true
+  sheet.column(3).hidden = true
+  sheet.column(2).outline_level = 1
+  sheet.column(3).outline_level = 1
+  
+  # row
+  sheet.row(2).hidden = true
+  sheet.row(3).hidden = true
+  sheet.row(2).outline_level = 1
+  sheet.row(3).outline_level = 1
+  
+  # save file
+  book.write "out.xls"
+
+Notes
+  * The outline_level should be under 8, which is due to the Excel data format.
+
+== More about Encodings
+Spreadsheet assumes it's running on Ruby 1.8 with Iconv-support. It is your
+responsibility to handle Conversion Errors, or to prevent them e.g. by using
+the Iconv Transliteration and Ignore flags:
+Spreadsheet.client_encoding = 'LATIN1//TRANSLIT//IGNORE'
+
+
+== Backward Compatibility
+Spreadsheet is designed to be a drop-in replacement for both ParseExcel and
+Spreadsheet::Excel. It provides a number of require-paths for backward
+compatibility with its predecessors. If you have been working with ParseExcel,
+you have probably used one or more of the following:
+
+  require 'parseexcel'
+  require 'parseexcel/parseexcel'
+  require 'parseexcel/parser'
+
+Either of the above will define the ParseExcel.parse method as a facade to
+Spreadsheet.open. Additionally, this will alter Spreadsheets behavior to define
+the ParseExcel::Worksheet::Cell class and fill each parsed Row with instances
+thereof, which in turn provide ParseExcel's Cell#to_s(encoding) and Cell#date
+methods.
+You will have to manually uninstall the parseexcel library.
+
+If you are upgrading from Spreadsheet::Excel, you were probably using
+Workbook#add_worksheet and Worksheet#write, write_row or write_column.
+Use the following to load the code which provides them:
+
+  require 'spreadsheet/excel'
+
+Again, you will have to manually uninstall the spreadsheet-excel library.
+
+If you perform fancy formatting, you may run into trouble as the
+Format implementation has changed considerably. If that is the case, please
+drop me a line at hannes.wyss@gmail.com and I will try to help you. Don't
+forget to include the offending code-snippet!
+
+All compatibility code is deprecated and will be removed in version 1.0.0

data/Gemfile

@@ -0,0 +1,12 @@
+source "http://rubygems.org"
+# Add dependencies required to use your gem here.
+# Example:
+gem "ruby-ole"
+
+# Add dependencies to develop your gem here.
+# Include everything needed to run rake, tests, features, etc.
+group :development do
+  gem "bundler"
+  gem "jeweler"
+  gem "rcov"
+end

data/Gemfile.lock

@@ -0,0 +1,20 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    git (1.2.5)
+    jeweler (1.5.2)
+      bundler (~> 1.0.0)
+      git (>= 1.2.5)
+      rake
+    rake (0.8.7)
+    rcov (0.9.9)
+    ruby-ole (1.2.11.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler
+  jeweler
+  rcov
+  ruby-ole

data/History.txt

@@ -0,0 +1,307 @@
+=== 0.6.5 / 07.12.2010
+
+* 2 Enhancements courtesy to ISS AG.
+
+  * Outlining (Grouping) of lines and columns is now possible. The outlining 
+    maximum is 8. This means you can do 8 subgroups in a group.
+
+  * Hiding and Unhiding of lines and columns is now possible. 
+
+  * Both of above two points is now possible by creating a new Excel File from 
+    scratch or editing an existing XLS and adding groups or hiding lines to it.
+
+=== 0.6.4.1 / 2009-09-17
+
+* 3 Bugfixes
+
+  * Fixes the issue reported by Thomas Preymesser and tracked down most of the
+    way by Hugh McGowan in
+    http://rubyforge.org/tracker/index.php?func=detail&aid=26647&group_id=678&atid=2677
+    where reading the value of the first occurrence of a shared formula
+    failed.
+
+  * Fixes the issue reported by Anonymous in
+    http://rubyforge.org/tracker/index.php?func=detail&aid=26546&group_id=678&atid=2677
+    where InvalidDate was raised for some Dates.
+
+  * Fixes the issue reported by John Lee in
+    http://rubyforge.org/tracker/index.php?func=detail&aid=27110&group_id=678&atid=2677
+    which is probably a duplicate of the Bug previously reported by Kadvin XJ in
+    http://rubyforge.org/tracker/index.php?func=detail&aid=26182&group_id=678&atid=2677
+    where unchanged rows were marked as changed in the Excel-Writer while the
+    File was being written, triggering an Error.
+
+* 1 minor enhancement
+
+  * Detect row offsets from Cell data if Row-Ops are missing
+    This fixes a bug reported by Alexander Logvinov in
+    http://rubyforge.org/tracker/index.php?func=detail&aid=26513&group_id=678&atid=2677
+
+
+=== 0.6.4 / 2009-07-03
+
+* 5 Bugfixes
+
+  * Fixes the issue reported by Harley Mackenzie in
+    http://rubyforge.org/tracker/index.php?func=detail&aid=24119&group_id=678&atid=2677
+    where in some edge-cases numbers were stored incorrectly
+
+  * Fixes the issue reported and fixed by someone23 in
+    http://rubyforge.org/tracker/index.php?func=detail&aid=25732&group_id=678&atid=2677
+    where using Row-updater methods with blocks caused LocalJumpErrors
+
+  * Fixes the issue reported and fixed by Corey Burrows in
+    http://rubyforge.org/tracker/index.php?func=detail&aid=25784&group_id=678&atid=2677
+    where "Setting the height of a row, either in Excel directly, or via the
+    Spreadsheet::Row#height= method results in a row that Excel displays with
+    the maximum row height (409)."
+
+  * Fixes the issue reported by Don Park in
+    http://rubyforge.org/tracker/index.php?func=detail&aid=25968&group_id=678&atid=2677
+    where some Workbooks could not be parsed due to the OLE-entry being all
+    uppercase
+
+  * Fixes the issue reported by Iwan Buetti in
+    http://rubyforge.org/tracker/index.php?func=detail&aid=24414&group_id=678&atid=2677
+    where parsing some Workbooks failed with an Invalid date error.
+
+
+* 1 major enhancement
+
+  * Spreadsheet now runs on Ruby 1.9
+
+=== 0.6.3.1 / 2009-02-13
+
+* 3 Bugfixes
+
+  * Only selects the First Worksheet by default
+    This deals with an issue reported by Biörn Andersson in
+    http://rubyforge.org/tracker/?func=detail&atid=2677&aid=23736&group_id=678
+    where data-edits in OpenOffice were propagated through all selected
+    sheets.
+
+  * Honors Row, Column, Worksheet and Workbook-formats
+    and thus fixes a Bug introduced in
+    http://scm.ywesee.com/?p=spreadsheet;a=commit;h=52755ad76fdda151564b689107ca2fbb80af3b78
+    and reported in
+    http://rubyforge.org/tracker/index.php?func=detail&aid=23875&group_id=678&atid=2678
+    and by Joachim Schneider in
+    http://rubyforge.org/forum/forum.php?thread_id=31056&forum_id=2920
+
+  * Fixes a bug reported by Alexander Skwar in
+    http://rubyforge.org/forum/forum.php?thread_id=31403&forum_id=2920
+    where the user-defined formatting of Dates and Times was overwritten with
+    a default format, and other issues connected with writing Dates and Times
+    into Spreadsheets.
+
+* 1 minor enhancements
+
+  * Spreadsheet shold now be completely warning-free,
+    as requested by Eric Peterson in
+    http://rubyforge.org/forum/forum.php?thread_id=31346&forum_id=2920
+
+=== 0.6.3 / 2009-01-14
+
+* 1 Bugfix
+
+  * Fixes the issue reported by Corey Martella in
+    http://rubyforge.org/forum/message.php?msg_id=63651
+    as well as other issues engendered by the decision to always shorten
+    Rows to the last non-nil value.
+
+* 2 minor enhancements
+
+  * Added bin/xlsopcodes, a tool for examining Excel files
+
+  * Documents created by Spreadsheet can now be Printed in Excel and
+    Excel-Viewer.
+    This issue was reported by Spencer Turner in
+    http://rubyforge.org/tracker/index.php?func=detail&aid=23287&group_id=678&atid=2677
+
+=== 0.6.2.1 / 2008-12-18
+
+* 1 Bugfix
+
+  * Using Spreadsheet together with 'jcode' could lead to broken Excel-Files
+    Thanks to Eugene Mikhailov for tracking this one down in:
+    http://rubyforge.org/tracker/index.php?func=detail&aid=23085&group_id=678&atid=2677
+
+=== 0.6.2 / 2008-12-11
+
+* 14 Bugfixes
+
+  * Fixed a bug where #<boolean>! methods did not trigger a call to
+    #row_updated
+
+  * Corrected the Row-Format in both Reader and Writer (was Biff5 for some
+    reason)
+
+  * Populates Row-instances with @default_format, @height, @outline_level
+    and @hidden attributes
+
+  * Fixed a Bug where Workbooks deriving from a Template-Workbook without
+    SST could not be saved
+    Reported in
+    http://rubyforge.org/tracker/index.php?func=detail&aid=22863&group_id=678&atid=2678
+
+  * Improved handling of Numeric Values (writes a RK-Entry for a Float
+    only if it can be encoded with 4 leading zeroes, and a Number-Entry for an
+    Integer only if it cannot be encoded as an RK)
+
+  * Fixes a bug where changes to a Row were ignored if they were
+    outside of an existing Row-Block.
+
+  * Fixes a bug where MULRK-Entries sometimes only contained a single RK
+
+  * Fixes a bug where formatting was ignored if it was applied to empty Rows
+    Reported by Zomba Lumix in
+    http://rubyforge.org/forum/message.php?msg_id=61985
+
+  * Fixes a bug where modifying a Row in a loaded Workbook could lead to Rows
+    with smaller indices being set to nil.
+    Reported by Ivan Samsonov in
+    http://rubyforge.org/forum/message.php?msg_id=62816
+
+  * Deals with rounding-problems when calculating Time
+    Reported by Bughunter extraordinaire Bjørn Hjelle
+
+  * Correct splitting of wide characters in SST
+    Reported by Michel Ziegler and by Eugene Mikhailov in
+    http://rubyforge.org/tracker/index.php?func=detail&aid=23085&group_id=678&atid=2677
+
+  * Fix an off-by-one error in write_mulrk that caused Excel to complain that
+    'Data may be lost', reported by Emma in
+    http://blade.nagaokaut.ac.jp/cgi-bin/scat.rb/ruby/ruby-talk/321979
+    and by Chris Lowis in
+    http://rubyforge.org/tracker/index.php?func=detail&aid=22892&group_id=678&atid=2677
+
+
+  * Read formats correctly in read_mulrk
+    Reported by Ivan Samsonov
+    Fixes that part of http://rubyforge.org/forum/message.php?msg_id=62821
+    which is a bug. Does nothing for the disappearance of Rich-Text
+    formatting, which will not be addressed until 0.7.0
+
+  * Fixes a (benign?) bug, where adding text to a template-file resulted in
+    a duplicate extsst-record.
+
+* 2 minor enhancements
+
+  * Improved recognition of Time-Formats
+
+  * Improvement to Robustness: allow Spreadsheet::Workbook.new
+    Takes care of http://rubyforge.org/forum/message.php?msg_id=62941
+    Reported by David Chamberlain
+
+=== 0.6.1.9 / 2008-11-07
+
+* 1 Bugfix
+
+  * Fixes a precision-issue in Excel::Row#datetime: Excel records Time-Values
+    with more significant bits (but not necessarily more precise) than
+    DateTime can handle.
+    (Thanks to Bjørn Hjelle for the Bugreport)
+
+* 1 minor enhancement
+
+  * Added support for appending Worksheets to a Workbook
+    (Thanks to Mohammed Rabbani for the report)
+
+=== 0.6.1.8 / 2008-10-31
+
+* 1 Bugfix
+
+  * Fixes a bug where out-of-sequence reading of multiple Worksheets could
+    lead to data from the wrong Sheet being returned.
+    (Thanks to Bugreporter extraordinaire Bjørn Hjelle)
+
+=== 0.6.1.7 / 2008-10-30
+
+* 1 Bugfix
+
+  * Fixes a bug where all Formulas were ignored.
+    (Thanks to Bjørn Hjelle for the report)
+
+* 1 minor enhancement
+
+  * Allow the substitution of an IO object with a StringIO.
+    (Thanks to luxor for the report)
+
+=== 0.6.1.6 / 2008-10-28
+
+* 2 Bugfixes
+
+  * Fixed encoding and decoding of BigNums, negative and other large Numbers
+    http://rubyforge.org/tracker/index.php?func=detail&aid=22581&group_id=678&atid=2677
+  * Fix a bug where modifications to default columns weren't stored
+    http://rubyforge.org/forum/message.php?msg_id=61567
+
+* 1 minor enhancement
+
+  * Row#enriched_data won't return a Bogus-Date if the data isn't a Numeric
+    value
+    (Thanks to Bjørn Hjelle for the report)
+
+=== 0.6.1.5 / 2008-10-24
+
+* 2 Bugfixes
+
+  * Removed obsolete code which triggered Iconv::InvalidEncoding
+    on Systems with non-gnu Iconv:
+    http://rubyforge.org/tracker/index.php?func=detail&aid=22541&group_id=678&atid=2677
+  * Handle empty Worksheets
+    (Thanks to Charles Lowe for the Patches)
+
+=== 0.6.1.4 / 2008-10-23
+
+* 1 Bugfix
+
+  * Biff8#wide now works properly even if $KCODE=='UTF-8'
+    (Thanks to Bjørn Hjelle for the Bugreport)
+
+* 1 minor enhancement
+
+  * Read/Write functionality for Links (only URLs can be written as of now)
+
+=== 0.6.1.3 / 2008-10-21
+
+* 2 Bugfixes
+
+  * Renamed UTF8 to UTF-8 to support freebsd
+    (Thanks to Jacob Atzen for the Patch)
+  * Fixes a Bug where only the first Rowblock was read correctly if there were
+    no DBCELL records terminating the Rowblocks.
+    (Thanks to Bjørn Hjelle for the Bugreport)
+
+=== 0.6.1.2 / 2008-10-20
+
+* 2 Bugfixes
+
+  * Corrected the Font-Encoding values in Excel::Internals
+    (Thanks to Bjørn Hjelle for the Bugreport)
+  * Spreadsheet now skips Richtext-Formatting runs and Asian Phonetic 
+    Settings when reading the SST, fixing a problem where the presence of
+    Richtext could lead to an incomplete SST.
+
+=== 0.6.1.1 / 2008-10-20
+
+* 1 Bugfix
+
+  * Corrected the Manifest - included column.rb
+
+=== 0.6.1 / 2008-10-17
+
+* 3 minor enhancements
+
+  * Adds Column formatting and Worksheet#format_column
+  * Reads and writes correct Fonts (Font-indices > 3 appear to be 1-based)
+  * Reads xf data
+
+=== 0.6.0 / 2008-10-13
+
+* 1 major enhancement
+
+  * Initial upload of the shiny new Spreadsheet Gem after three weeks of
+    grueling labor in the dark binary mines of Little-Endian Biff and long
+    hours spent polishing the surfaces of documentation.
+