spreadsheet-excel 0.3.4

data/doc/spreadsheet.txt

@@ -0,0 +1,178 @@
+== Description
+   spreadsheet - A package for generating MS Excel (95) compatable files on
+   any platform.
+
+   Based on version .43 of John McNamara's Perl module
+   Spreadsheet::WriteExcel.
+   
+== Synopsis
+   require "spreadsheet/excel"
+   include Spreadsheet
+
+   workbook = Excel.new("test.xls")
+
+   # There are three ways to create a format
+   format = workbook.add_format(:color=>"blue",:bold=>1,:underline=>1)
+
+   format2 = Format.new(
+      :color     => "green",
+      :bold      => true,
+      :underline => true
+   )
+   workbook.add_format(format2)
+
+   format3 = Format.new{ |f|
+      f.color = "red"
+      f.bold  = true
+      f.underline = true
+   }
+   workbook.add_format(format3)
+
+   worksheet1 = workbook.add_worksheet
+   worksheet2 = workbook.add_worksheet("Numbers")
+   worksheet3 = workbook.add_worksheet("Text")
+   
+   worksheet1.write(0,0,"Hello",format)
+   worksheet1.write(1,1,["Matz","Larry","Guido"])
+
+   worksheet2.write(1,3,8876,format2)
+   worksheet2.write_column(4,4,[1,2,3])
+
+   worksheet3.write(2,2,"World",format3)
+   worksheet3.write(3,3,[[1,2,3],[4,5,6],[7,8,9]])
+
+   worksheet1.format_row(1,25,format1)
+   worksheet2.format_column(0..2,30,format2)
+
+   workbook.close
+   
+== Constants
+VERSION
+   The current version number (a string).
+    
+== Classes
+=== Excel
+Excel.new(file_name)
+   Returns a workbook object.  You may only have one workbook per file.  A
+   ".xls" extension for your +file_name+ is recommended but not enforced.
+    
+=== Workbook
+Workbook#add_worksheet(sheet_name=nil)
+   Adds a worksheet named +sheet_name+ to the workbook object. If +sheet_name+
+   is nil it will default to 'Sheet1', 'Sheet2', etc.  Returns a Worksheet
+   instance.
+    
+Workbook#add_format(format)
+   Adds the +format+ to the workbook.  When included as part of the 'write'
+   method, the cells specified are formatted appropriately.  Returns a Format
+   instance.  Note that +format+ can be a format object, or a hash that is
+   automagically converted to a Format object.
+
+   See the synopsis above for different ways to add formats.
+    
+Workbook#close
+   Closes the workbook (and, hence, the IO stream). Be sure to do this.
+    
+=== Worksheet
+Worksheet#write(row, column, value, format=nil)
+   Writes data to the cell you provide.  If +value+ is an Array, the
+   write_row method is called internally.
+    
+   If +value+ is a multi-dimensional array, then each element of the array
+   is written within its own row at the appropriate column.  In other words,
+   it's written to the spreadsheet in the same manner you would visualize it.
+    
+   If +format+ is provided, the cells are each formatted appropriately.
+    
+Worksheet#write_row(row, column, Array, format=nil)
+    Writes a row of data starting at +row+ and +column+ in a left to
+    right manner, with one array element per cell.
+
+    If +format+ is provided, formatting will be applied to each cell.
+    
+Worksheet#write_column(row, column, Array, format=nil)
+    Writes a column of data starting at +row+ and +column+ in a top to
+    bottom manner, with one array element per cell.
+
+    If +format+ is provided, formatting will be applied to each cell.
+    
+Worksheet#format_row(row, height=nil, format=nil, hidden=0, level=0)
+    Applies formatting for an entire row or Range of rows. In addition, you
+    can specify the row height. If you wish to apply row-level formatting
+    without modifying the height, simply pass nil as the second argument.
+
+    Note that this will override any previously defined cell formatting.
+    
+Worksheet#format_column(col, width=nil, format=nil, hidden=false, level=0)
+    Applies formatting for an entire row or Range of columns. In addition, you
+    can specify the column width.  If you wish to apply column-level formatting
+    without modifying the width, simply pass nil as the second argument.
+    
+    If +hidden+ is any value other than false or nil, the row will be hidden.
+    
+    The +level+ value sets the outline level of the row.  Adjacent rows with
+    the same outline level are grouped together into a single outline.
+
+    Note that this will override any previously defined cell formatting.
+    
+=== Format
+Format.new
+Format.new({key=>val, ...})
+Format.new{ ... }
+   Creates a new Format object.  See the Format documentation (format.txt)
+   for more details.
+    
+== Notes
+   This is a port of John McNamara's Spreadsheet::WriteExcel Perl module,
+   version 0.43 (approximately). There is no support for formulas or large
+   files yet.
+
+   This package creates files in the Excel 95 format.
+    
+== Design Changes
+   The only somewhat major change was to make OLEWriter a subclass of IO,
+   rather than store a filehandle as an attribute within the class.  This
+   seems to have worked out fine.
+
+   The set_row() and set_column() methods were renamed as format_row()
+   and format_column(), respectively.  All other methods are either
+   identical in name or very similar.
+   
+   Other changes consisted mostly of minor code optimizations.  Occasionally
+   I was more terse than John was (for better or for worse).
+    
+== Questions
+   Questions about MS Excel should be directed to Microsoft.
+   Questions about the MS Excel format should be directed to Microsoft.
+   Questions about why I use the hex values that I use should be directed to
+   John McNamara (jmcnamara at cpan dot org) or to Microsoft.
+
+== Future Plans
+   Add support for files > 7MB - need help
+   Add formulas - need help
+    
+== Acknowledgements
+   Many thanks go to John McNamara for his tireless dedication to a very useful
+   and popular module.  I also thank him for taking the time to answer some of
+   the questions I had for him while porting his code.
+   
+   Thanks go to Jade Meskill for the outline patch.
+    
+== License
+   Ruby's
+    
+== Copyright
+   � 2002-2006, Daniel J. Berger
+
+   All Rights Reserved. This module is free software. It may be used,
+   redistributed and/or modified under the same terms as Ruby itself.
+
+== Warranty
+    This package is provided "as is" and without any express or
+    implied warranties, including, without limitation, the implied
+    warranties of merchantability and fitness for a particular purpose.
+    
+== Author
+   Daniel J. Berger
+   djberg96 at gmail dot com
+   imperator on IRC (freenode)

data/examples/CVS/Entries

@@ -0,0 +1,3 @@
+/example_basic.rb/1.2/Wed Oct 12 21:05:44 2005//
+/example_format.rb/1.2/Wed Oct 12 21:11:40 2005//
+D

data/examples/CVS/Repository

@@ -0,0 +1 @@
+RubySpreadsheet/examples

data/examples/CVS/Root

@@ -0,0 +1 @@
+:ext:hwyss@rubyspreadsheet.cvs.sourceforge.net:/cvsroot/rubyspreadsheet

data/examples/example_basic.rb

@@ -0,0 +1,27 @@
+########################################################################
+# example_basic.rb
+# 
+# Simply run this and then open up basic_example.xls with MS Excel
+# (or Gnumeric or whatever) to view the results.
+########################################################################
+base = File.basename(Dir.pwd)
+if base == "examples" || base =~ /spreadsheet/i
+   Dir.chdir("..") if base == "examples"
+   $LOAD_PATH.unshift(Dir.pwd)
+   $LOAD_PATH.unshift(Dir.pwd + "/lib")
+   Dir.chdir("examples") rescue nil
+end
+
+require "spreadsheet/excel"
+include Spreadsheet
+
+puts "VERSION: " + Excel::VERSION
+
+workbook = Excel.new("basic_example.xls")
+
+worksheet = workbook.add_worksheet
+
+worksheet.write(0, 0, "Hello")
+worksheet.write(1, 0, ["Matz","Larry","Guido"])
+
+workbook.close

data/examples/example_format.rb

@@ -0,0 +1,69 @@
+########################################################################
+# example_formula.rb
+# 
+# Simply run this and then open up format_example.xls with MS Excel
+# (or Gnumeric or whatever) to view the results.
+########################################################################
+base = File.basename(Dir.pwd)
+if base == "examples" || base =~ /spreadsheet/i
+   Dir.chdir("..") if base == "examples"
+   $LOAD_PATH.unshift(Dir.pwd)
+   $LOAD_PATH.unshift(Dir.pwd + "/lib")
+   Dir.chdir("examples") rescue nil
+end
+
+require "spreadsheet/excel"
+include Spreadsheet
+
+version = Excel::VERSION
+puts "VERSION: " + version
+
+workbook = Excel.new("format_example.xls")
+
+# Preferred way to add a format
+f1 = workbook.add_format(:color=>"blue", :bold=>1, :italic=>true)
+
+# Another way to add a format
+f2 = Format.new(
+   :color  => "red",
+   :bold   => 1,
+   :italic => true
+)
+workbook.add_format(f2)
+
+# Yet another way to add a format
+# A tiny bit more overhead doing it this way
+f3 = Format.new{ |f|
+   f.color  = "green"
+   f.bold   = 1
+   f.italic = true
+}
+workbook.add_format(f3)
+
+f4 = Format.new(:num_format => "d mmm yyyy")
+f5 = Format.new(:num_format => 0x0f)
+workbook.add_format(f4)
+workbook.add_format(f5)
+
+worksheet1 = workbook.add_worksheet
+worksheet2 = workbook.add_worksheet("number")
+worksheet3 = workbook.add_worksheet("text")
+
+worksheet1.write(0, 0, version)
+worksheet1.write(0, 1, "Hello", f1)
+worksheet1.write(1, 1, ["Matz","Larry","Guido"])
+
+worksheet2.write_column(1, 1, [[1,2,3],[4,5,6],[7,8,9]])
+worksheet2.write(0, 0, 8888, f2)
+
+worksheet3.write(0, 0, 36892.521, f5)
+
+worksheet1.format_row(4..5, 30, f1)
+
+worksheet2.format_column(3..4, 25, f2)
+
+worksheet1.write(5,0,"This should be blue")
+
+worksheet2.write(0,4,"This should be red")
+
+workbook.close

data/lib/CVS/Entries

@@ -0,0 +1 @@
+D/spreadsheet////

data/lib/CVS/Repository

@@ -0,0 +1 @@
+RubySpreadsheet/lib

data/lib/CVS/Root

@@ -0,0 +1 @@
+:ext:hwyss@rubyspreadsheet.cvs.sourceforge.net:/cvsroot/rubyspreadsheet

data/lib/spreadsheet/CVS/Entries

@@ -0,0 +1,7 @@
+/biffwriter.rb/1.1/Tue Oct 11 17:09:08 2005//
+/excel.rb/1.4/Fri Feb 17 03:34:00 2006//
+/format.rb/1.1/Tue Oct 11 17:09:08 2005//
+/olewriter.rb/1.3/Mon Dec  5 02:03:48 2005//
+/workbook.rb/1.4/Sun Feb 12 16:42:10 2006//
+/worksheet.rb/1.2/Fri Feb 17 03:33:24 2006//
+D

data/lib/spreadsheet/CVS/Repository

@@ -0,0 +1 @@
+RubySpreadsheet/lib/spreadsheet

data/lib/spreadsheet/CVS/Root

@@ -0,0 +1 @@
+:ext:hwyss@rubyspreadsheet.cvs.sourceforge.net:/cvsroot/rubyspreadsheet

data/lib/spreadsheet/biffwriter.rb

@@ -0,0 +1,46 @@
+class BIFFWriter
+
+   BIFF_Version = 0x0500
+   BigEndian    = [1].pack("I") == [1].pack("N")
+
+   attr_reader :byte_order, :data, :datasize
+
+   ######################################################################
+   # The args here aren't used by BIFFWriter, but they are needed by its 
+   # subclasses.  I don't feel like creating multiple constructors.
+   ######################################################################
+   def initialize(*args)
+      @data       = ""
+      @datasize   = 0
+   end
+
+   def prepend(*args)
+      @data = args.join << @data
+      @datasize += args.join.length
+   end
+
+   def append(*args)
+      @data << args.join
+      @datasize += args.join.length
+   end
+
+   def store_bof(type = 0x0005)
+      record  = 0x0809
+      length  = 0x0008
+      build   = 0x096C
+      year    = 0x07C9
+
+      header  = [record,length].pack("vv")
+      data    = [BIFF_Version,type,build,year].pack("vvvv") 
+
+      prepend(header, data)
+   end
+
+   def store_eof
+      record = 0x000A
+      length = 0x0000
+      header = [record,length].pack("vv")
+ 
+      append(header)
+   end
+end   

data/lib/spreadsheet/excel.rb

@@ -0,0 +1,13 @@
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+
+require "biffwriter"
+require "olewriter"
+require "workbook"
+require "worksheet"
+require "format"
+
+module Spreadsheet
+   class Excel < Workbook
+      VERSION = "0.3.4"
+   end
+end

data/lib/spreadsheet/format.rb

@@ -0,0 +1,359 @@
+class Format
+
+   COLORS = {
+      'aqua'    => 0x0F,
+      'black'   => 0x08,
+      'blue'    => 0x0C,
+      'brown'   => 0x10,
+      'cyan'    => 0x0F,
+      'fuchsia' => 0x0E,
+      'gray'    => 0x17,
+      'grey'    => 0x17,
+      'green'   => 0x11,
+      'lime'    => 0x0B,
+      'magenta' => 0x0E,
+      'navy'    => 0x12,
+      'orange'  => 0x1D,
+      'purple'  => 0x24,
+      'red'     => 0x0A,
+      'silver'  => 0x16,
+      'white'   => 0x09,
+      'yellow'  => 0x0D
+   }
+
+   attr_accessor :xf_index
+
+   def initialize(args={}, xf_index=0)
+      defaults = {}
+
+      defaults.update(:color     => 0x7FFF, :bold   => 0x0190)
+      defaults.update(:fg_color  => 0x40, :pattern  => 0,  :size => 10)
+      defaults.update(:bg_color  => 0x41, :rotation => 0,  :font => "Arial")
+      defaults.update(:underline => 0,    :italic   => 0,  :top  => 0)
+      defaults.update(:bottom    => 0,    :right    => 0,  :left => 0)
+
+      defaults.update(:font_index     => 0, :font_family  => 0)
+      defaults.update(:font_strikeout => 0, :font_script  => 0)
+      defaults.update(:font_outline   => 0, :left_color   => 0)
+      defaults.update(:font_charset   => 0, :right_color  => 0)
+      defaults.update(:font_shadow    => 0, :top_color    => 0x40)
+      defaults.update(:text_v_align   => 2, :bottom_color => 0x40)
+      defaults.update(:text_h_align   => 0, :num_format   => 0)
+      defaults.update(:text_justlast  => 0, :text_wrap    => 0)
+
+      ########################################################################
+      # We must manually create accessors for these so that they can handle
+      # both 0/1 and true/false.
+      ########################################################################
+      no_acc = [:bold,:italic,:underline,:strikeout,:text_wrap,:text_justlast]
+      no_acc.push(:fg_color,:bg_color,:color,:font_outline,:font_shadow)
+
+      args.each{|key,val|
+         key = key.to_s.downcase.intern
+         val = 1 if val == true
+         val = 0 if val == false
+         defaults.fetch(key)
+         defaults.update(key=>val)
+      }
+
+      defaults.each{|key,val|
+         unless no_acc.member?(key)
+            self.class.send(:attr_accessor,"#{key}")
+         end
+         send("#{key}=",val)
+      }
+
+      @xf_index = xf_index
+
+      yield self if block_given?
+   end
+
+   def color=(colour)
+      if COLORS.has_key?(colour)
+         @color = COLORS[colour]
+      else
+         if colour.kind_of?(String)
+            raise ArgumentError, "unknown color"
+         else
+            @color = colour
+         end
+      end
+      @color
+   end
+
+   def bg_color=(colour)
+      if COLORS.has_key?(colour)
+         @bg_color = COLORS[colour]
+      else
+         if colour.kind_of?(String)
+            raise ArgumentError, "unknown color"
+         else
+            @bg_color = colour
+         end
+      end
+      @bg_color
+   end
+
+   def fg_color=(colour)
+      if COLORS.has_key?(colour)
+         @fg_color = COLORS[colour]
+      else
+         if colour.kind_of?(String)
+            raise ArgumentError, "unknown color"
+         else
+            @fg_color = colour
+         end
+      end
+      @fg_color
+   end
+
+   def fg_color
+      @fg_color
+   end
+
+   def bg_color
+      @bg_color
+   end
+
+   # Should I return the stringified version of the color if applicable?
+   def color
+      #COLORS.invert.fetch(@color)
+      @color
+   end
+
+   def italic
+      return true if @italic >= 1
+      return false
+   end
+
+   def italic=(val)
+      val = 1 if val == true
+      val = 0 if val == false
+      @italic = val
+   end
+
+   def font_shadow
+      return true if @font_shadow == 1
+      return false
+   end
+
+   def font_shadow=(val)
+      val = 1 if val == true
+      val = 0 if val == false
+      @font_shadow = val
+   end
+
+   def font_outline
+      return true if @font_outline == 1
+      return false
+   end
+
+   def font_outline=(val)
+      val = 1 if val == true
+      val = 0 if val == false
+      @font_outline = val
+   end
+
+   def text_justlast
+      return true if @text_justlast == 1
+      return false
+   end
+
+   def text_justlast=(val)
+      val = 1 if val == true
+      val = 0 if val == false
+      @text_justlast = val
+   end
+
+   def text_wrap
+      return true if @text_wrap == 1
+      return false
+   end
+
+   def text_wrap=(val)
+      val = 1 if val == true
+      val = 0 if val == false
+      @text_wrap = val
+   end
+
+   def strikeout
+      return true if @strikeout == 1
+      return false
+   end
+
+   def strikeout=(val)
+      val = 1 if val == true
+      val = 0 if val == false
+      @strikeout = val
+   end
+
+   def underline
+      return true if @underline == 1
+      return false
+   end
+
+   def underline=(val)
+      val = 1 if val == true
+      val = 0 if val == false
+      @underline = val
+   end
+
+
+   def xf_biff(style=0)
+      atr_num = 0
+      atr_num = 1 if @num_format != 0
+
+      atr_fnt = 0
+      atr_fnt = 1 if @font_index != 0
+
+      atr_alc = @text_wrap
+      atr_bdr = [@bottom,@top,@left,@right].find{ |n| n > 0 } || 0
+      atr_pat = [@fg_color,@bg_color,@pattern].find{ |n| n > 0 } || 0
+
+      atr_prot    = 0
+
+      @bottom_color = 0 if @bottom == 0
+      @top_color    = 0 if @top    == 0
+      @right_color  = 0 if @right  == 0
+      @left_color   = 0 if @left   == 0
+
+      record         = 0x00E0
+      length         = 0x0010
+
+      align  = @text_h_align
+      align  |= @text_wrap     << 3
+      align  |= @text_v_align  << 4
+      align  |= @text_justlast << 7
+      align  |= @rotation      << 8
+      align  |= atr_num        << 10
+      align  |= atr_fnt        << 11
+      align  |= atr_alc        << 12
+      align  |= atr_bdr        << 13
+      align  |= atr_pat        << 14
+      align  |= atr_prot       << 15
+
+      # Assume a solid fill color if the bg_color or fg_color are set but
+      # the pattern value is not set
+      if @pattern <= 0x01 and @bg_color != 0x41 and @fg_color == 0x40
+         @fg_color = @bg_color
+         @bg_color = 0x40
+         @pattern  = 1
+      end
+
+      if @pattern < 0x01 and @bg_color == 0x41 and @fg_color != 0x40
+         @bg_color = 0x40
+         @pattern  = 1
+      end
+
+      icv   = @fg_color
+      icv  |= @bg_color << 7
+
+      fill = @pattern
+      fill |= @bottom << 6
+      fill |= @bottom_color << 9
+
+      border1 = @top
+      border1 |= @left      << 3
+      border1 |= @right     << 6
+      border1 |= @top_color << 9
+
+      border2 = @left_color
+      border2 |= @right_color << 7
+
+      header = [record,length].pack("vv")
+      fields = [@font_index,@num_format,style,align,icv,fill,border1,border2]
+      data = fields.pack("vvvvvvvv")
+
+      rv = header + data
+      return rv
+   end
+
+   def font_biff
+      dyheight = @size * 20
+      cch      = @font.length
+      record   = 0x31
+      length   = 0x0F + cch
+      reserved = 0x00
+
+      grbit = 0x00
+      grbit |= 0x02 if @italic > 0
+      grbit |= 0x08 if @font_strikeout > 0
+      grbit |= 0x10 if @font_outline > 0
+      grbit |= 0x20 if @font_shadow > 0
+
+      header = [record,length].pack("vv")
+      fields = [dyheight,grbit,@color,@bold,@font_script,@underline,@font_family]
+      fields.push(@font_charset,reserved,cch)
+
+      data = fields.pack("vvvvvCCCCC")
+      rv = header + data + @font
+
+      return rv
+   end
+
+   def font_key
+      key = @font.to_s + @size.to_s + @font_script.to_s + @underline.to_s
+      key += @font_strikeout.to_s + @bold.to_s + @font_outline.to_s
+      key += @font_family.to_s + @font_charset.to_s + @font_shadow.to_s
+      key += @color.to_s + @italic.to_s
+      return key
+   end
+
+   def align=(location = nil)
+      return if location.nil?
+      return if location.kind_of?(Fixnum)
+      location.downcase!
+
+      @text_h_align = 1 if location == 'left'
+      @text_h_align = 2 if location == 'centre'
+      @text_h_align = 2 if location == 'center'
+      @text_h_align = 3 if location == 'right'
+      @text_h_align = 4 if location == 'fill'
+      @text_h_align = 5 if location == 'justify'
+      @text_h_align = 6 if location == 'merge'
+
+      @text_v_align = 0 if location == 'top'
+      @text_v_align = 1 if location == 'vcentre'
+      @text_v_align = 1 if location == 'vcenter'
+      @text_v_align = 2 if location == 'bottom'
+      @text_v_align = 3 if location == 'vjustify'
+   end
+
+   def align
+      [@text_h_align,@text_v_align]
+   end
+
+   def bold=(weight)
+      weight = 1 if weight == true
+      weight = 0 if weight == false
+      weight = 0x2BC if weight.nil?
+      weight = 0x2BC if weight == 1
+      weight = 0x190 if weight == 0
+      weight = 0x190 if weight < 0x064
+      weight = 0x190 if weight > 0x3E8
+      @bold = weight
+      @bold
+   end
+
+   def bold
+      return true if @bold >= 1
+      return false
+   end
+
+   def border=(style)
+      [@bottom,@top,@right,@left].each{ |attr| attr = style }
+   end
+
+   def border
+      [@bottom,@top,@right,@left]
+   end
+
+   def border_color=(color)
+      [@bottom_color,@top_color,@left_color,@right_color].each{ |a| a = color }
+   end
+
+   def border_color
+      [@bottom_color,@top_color,@left_color,@right_color]
+   end
+
+end