xmlss 0.3.1 → 0.4.0

data/.gitignore

@@ -2,5 +2,4 @@ pkg/*
 .bundle
 *.gem
 *.log
-*.xml
-
+bench/*.xml

data/Gemfile

@@ -4,3 +4,4 @@ source "http://rubygems.org"
 gemspec
 
 gem 'rake', '~>0.9.2'
+gem 'ruby-prof'

data/Gemfile.lock

@@ -1,23 +1,23 @@
 PATH
   remote: .
   specs:
-    xmlss (0.3.1)
-      enumeration (~> 1.2)
-      nokogiri (~> 1.4)
+    xmlss (0.4.0)
+      enumeration (~> 1.3)
+      undies (~> 2.1)
 
 GEM
   remote: http://rubygems.org/
   specs:
-    ansi (1.3.0)
-    assert (0.6.0)
-      assert-view (~> 0.3)
-    assert-view (0.3.0)
+    ansi (1.4.1)
+    assert (0.7.3)
+      assert-view (~> 0.5)
+    assert-view (0.5.0)
       ansi (~> 1.3)
-      undies (~> 1.1)
-    enumeration (1.2.1)
-    nokogiri (1.5.0)
+      undies (~> 2.0)
+    enumeration (1.3.1)
     rake (0.9.2)
-    undies (1.1.0)
+    ruby-prof (0.10.8)
+    undies (2.1.0)
 
 PLATFORMS
   ruby
@@ -26,4 +26,5 @@ DEPENDENCIES
   assert (~> 0.6)
   bundler (~> 1.0)
   rake (~> 0.9.2)
+  ruby-prof
   xmlss!

data/README.rdoc

@@ -1,10 +1,7 @@
 = Xmlss
+A ruby DSL for generating spreadsheets in the XML Spreadsheet format.  It provides an api for constructing spreadsheet data and then uses that data to generate xml that can be interpreted by MS Excel.
 
-== Description
-
-This gem allows you to generate spreadsheets in the XML Spreadsheet format.  It provides an api for constructing spreadsheet data and then uses that data to generate xml that can be interpreted by MS Excel.
-
-** Note: this gem only generates XML according to a subset of the August 2001 XML Spreadsheet spec (http://msdn.microsoft.com/en-us/library/aa140066(office.10).aspx).  It does not generate the more modern open office spreadsheet spec (xlsx).
+** Note: this gem only generates XML according to a subset of the August 2001 XML Spreadsheet spec (http://msdn.microsoft.com/en-us/library/aa140066(office.10).aspx).  It does not generate the more modern open office spreadsheet spec (xlsx) and may have limited support in modern spreadsheet applications.
 
 == Installation
 
@@ -14,122 +11,159 @@ This gem allows you to generate spreadsheets in the XML Spreadsheet format.  It
 
     require 'xmlss'
 
-    workbook = Xmlss::Workbook.new
-    workbook.worksheets       # => []
+    workbook = Xmlss::Worksheet.new do
+
+      worksheet("5 columns, 1 row") {
+        5.times do
+          column
+        end
+
+          row {
+            # put data into the row (infer type)
+            [1, "text", 123.45, "0001267", "$45.23"].each do |data_value|
+              cell { data data_value }
+            end
+          }
+        end
+      }
+
+    end
+
+    workbook.to_s    # => "..." (XML Spreadsheet xml string)
+
+== DSL / API
+
+Use these directives to create workbook markup elements.
+
+worksheet(name):
+* name: string
+
+column(apts={}):
+* opts[:style_id]: string
+* opts[:width]: numeric
+* opts[:auto_fit_width]: bool, default: false
+* opts[:hidden]: bool, default: false
+
+row(opts={}):
+* opts[:style_id]: string
+* opts[:height]: numeric
+* opts[:auto_fit_height]: bool, default: false
+* opts[:hidden]: bool, default: false
+
+cell(opts={}):
+* opts[:style_id]: string
+* opts[:href]: string
+* opts[:formula]: string
+* opts[:merge_across]: fixnum, default: 0
+* opts[:merge_down]: fixnum, default: 0
+
+data(value, opts={}):
+* value: whatever
+* opts[:type]: enum: :number, :date_time, :boolean, :string, :error
+* the :type option is defaulted appropriately based on the value - use the option to override as necessary
+
+Use these directives to define markup element styles.  Bind to markup using the element's :style_id option.  See 'examples/styles.rb' for more details.
+
+style(id):
+* id: string, must be unique to the workbook
+
+alignment(opts={}):
+* opts[:wrap_text]: bool, default: false
+* opts[:rotate]: fixnum (-90 to 90)
+* opts[:horizontal]: enum: :automatic, :left, :center, :right, :default
+* opts[:vertical]: enum: :automatic, :top, :center, :bottom, :default
+
+borders:
+* use this to build a set of border directives (see examples/styles.rb for details)
+
+border(opts={}):
+* opts[:color]: string, hex value ('#00FF00')
+* opts[:position]: enum: :left, :top, :right, :bottom
+* opts[:style]: enum: :none, :continuous (default), :dash, :dot, :dash_dot, :dash_dot_dot
+* opts[:weight]: enum: :hairline, :thin (default), :medium, :thick
+
+font(opts={}):
+* opts[:bold]: bool, default: false
+* opts[:color]: string, hex value ('#00FF00')
+* opts[:name]: string
+* opts[:italic]: bool, default: false
+* opts[:size]: fixnum
+* opts[:strike_through]: bool, default: false
+* opts[:shadow]: bool, default: false
+* opts[:underline]: enum: :single, :double, :single_accounting, :double_accounting
+* opts[:alignment]: enum: :subscript, :superscript
+
+interior(opts={}):
+* opts[:color]: string, hex value ('#00FF00')
+* opts[:pattern]: enum (see code for options), default: :default
+* opts[:pattern_color]: string, hex value ('#00FF00')
+
+number_format(value):
+* value: there are MANY different options for this, I suggest saving a spreadsheet in the XML format and seeing what Excel uses
+
+protection(value):
+* value: bool, default: false
 
-    sheet1 = Xmlss::Worksheet.new({
-      :name => 'Sheet 1'
-    })
-    sheet1.table = Xmlss::Table.new
-    sheet1.table.rows         # => []
+== Usage
 
-    row1 = Xmlss::Row.new(1, 'some data', 54.54)
-    row1.cells.count = 3
-    row1.cells.first.data     # => 1
+To generate a spreadsheet, create an Xmlss::Workbook instance and build the workbook using the above DSL.  Workbook takes two optional parameters:
+* opts: hash: :data, :output
+* &build: proc containing DSL directives
 
-    sheet1.table.rows << row1
-    workbook.worksheets << sheet1
+=== Data option
 
-    workbook.to_xml           # => "..." (XML Spreadsheet xml string)
+Xmlss evals the build proc in the scope of the workbook instance.  This means that the build has access to only the data it is given or the DSL itself.  Data is given in the form of a Hash.  The string form of the hash keys are exposed as local workbook methods that return their corresponding values.
 
-== Usage
-see the examples folder for some use case examples.
+    Xmlss::Workbook.new(:data => {:sheet_name => 'A cool sheet'}) do
+      worksheet(sheet_name) {
+        ...
+      }
+    end
+
+=== Output option (Undies)
+
+Xmlss uses Undies (https://github.com/kelredd/undies) to render the XML output.  The :output Workbook option is used to create Undies::Ouput objects.  See their docs for usage details (https://github.com/kelredd/undies/blob/master/README.rdoc).
+
+    Xmlss::Workbook.new(:output => {:pp => 2}) do
+      worksheet(sheet_name) {
+        ...
+      }
+    end
+
+=== Builder approach
+
+The above examples all pass in a build proc that is eval'd in the scope of the workbook instance.  This works great when you know your build at the same time you create your Workbook object.  However, in some cases, the build may not be known upfront or you may want to use a more declarative style to specify your spreadsheet content.  Workbook builds can be specified programmatically using the "builder" approach.
+
+To render using this approach, create a Workbook instance passing it data and output info as above.  However, don't pass any build proc and save off the created workbook:
+
+    # choosing not to use any local data or output options
+    workbook = Xmlss::Workbook.new
+
+Now just interact with the Workbook API directly.
+
+    # notice that it becomes less important to bind any local data to the Workbook using this approach
+    something = "Some Thing!"
+    workbook.worksheet(something) {
+      workbook.column
+
+      workbook.row {
+        workbook.cell {
+          workbook.data "hi hi something hi"
+        }
+      }
+    }
+
+== Disclaimer
 
 Be aware this library only provides the basic, raw API for constructing spreadsheets using this spec and utilities to convert those objects to string xml data representing them.  It does not provide any macro logic to aid in constructing the sheets.  If you want a more convenient API for your use case, I suggest subclassing the objects and tailoring them to your needs.
 
 The XML Spreadsheet spec and format are legacy and may have limited support depending on your version of MS Excel.  For a more modern spreadsheet generation method, I suggest looking into Office Open XML Workbook format (http://en.wikipedia.org/wiki/Office_Open_XML).
 
-== API
-
-These classes define how a spreadsheet is constructed.
-=== Xmlss::Workbook
-* *styles*: array, Xmlss:Style objects, default: []
-* *worksheets*: array, Xmlss::Worksheet objects, default: []
-
-=== Xmlss::Worksheet
-* *name*: string
-* *table*: Xmlss::Table object
-
-=== Xmlss::Table
-* *columns*: array, Xmlss::Column objects, default: []
-* *rows*: array, Xmlss::Row objects, default: []
-
-=== Xmlss::Column
-* *style_id*: string
-* *width*: numeric
-* *auto_fit_width*: bool, default: false
-* *hidden*: bool, default: false
-
-=== Xmlss::Row
-* *style_id*: string
-* *height*: numeric
-* *auto_fit_height*: bool, default: false
-* *hidden*: bool, default: false
-* *cells*: array, Xmlss::Cell objects, default: []
-
-=== Xmlss::Cell
-* *style_id*: string
-* *data*: Xmlss::Data object
-* *href*: string
-* *merge_across*: int, default: 0
-* *merge_down*: int, default: 0
-
-=== Xmlss::Data
-* *type*: :number, :date_time, :boolean, :string, :error, required
-* *value*: needs to respond to 'to_s'
-
-
-These classes define how a spreadsheet cells are styled.
-=== Xmlss::Style
-* *id*: string, unique identifier for the style
-* *alignment*: Xmlss::Style::Alignment object
-* *borders*: array, Xmlss::Style::Border objects, default: []
-* *font*: Xmlss::Style::Font object
-* *interior*: Xmlss::Style::Interior object
-* *number_format*: Xmlss::Style::NumberFormat object
-* *protection*: Xmlss::Protection object
-
-=== Xmlss::Style::Alignment
-* *horizontal*: :automatic, :left, :center, :right, :default, default: :default
-* *vertical*: :automatic, :top, :center, :bottom, :default, default: :default
-* *wrap_text*: bool, default: false
-* *rotate*: int (-90 to 90)
-
-=== Xmlss::Style::Border
-* *position*: :left, :top, :right, :bottom
-* *color*: hex string
-* *style*: :none, :continuous, :dash, :dot, :dash_dot, :dash_dot_dot, default: :continuous
-* *weight*: :hairline, :thin, :medium, :thick, default: :thin
-
-=== Xmlss::Style::Font
-* *bold*: bool, default: false
-* *color*: hex string
-* *name*: string
-* *italic*: bool, default: false
-* *size*: int
-* *strike_through*: bool, default: false
-* *shadow*: bool, default: false
-* *underline*: :single, :double, :single_accounting, :double_accounting
-* *alignment*: :subscript, :superscript
-
-=== Xmlss::Style::Interior
-* *color*: hex string
-* *pattern*: symbol (see code for options), default: :default
-* *pattern_color*: hex string
-
-=== Xmlss::Style::NumberFormat
-* *format*: :symbol (there are MANY different options for this, I suggest saving a spreadsheet in the XML format and seeing what Excel uses)
-
-=== Xmlss::Style::Protection
-* *protected*: bool, default: false
-
-
-== For More Info
 * Full XML Spreadsheet spec: http://msdn.microsoft.com/en-us/library/aa140066(office.10).aspx
 
 == License
 
-Copyright (c) 2011 Kelly D. Redding
+Copyright (c) 2011-Present, Kelly D. Redding
 
 Permission is hereby granted, free of charge, to any person
 obtaining a copy of this software and associated documentation

data/Rakefile

@@ -4,4 +4,27 @@ include Assert::RakeTasks
 require 'bundler'
 Bundler::GemHelper.install_tasks
 
-task :default => :build
+task :default => :run_all
+
+desc "Run the example workbook builds."
+task :run_examples do
+  require 'examples/simple'
+  require 'examples/layout'
+  require 'examples/text'
+  require 'examples/styles'
+end
+
+desc "Run the profiler on 1000 rows."
+task :run_profiler do
+  require 'bench/profiler_runner'
+
+  runner = XmlssProfilerRunner.new(1000)
+  runner.print_flat(STDOUT, :min_percent => 3)
+end
+
+desc "Run all the tests, then the example builds, then the profiler."
+task :run_all do
+  Rake::Task['test'].invoke
+  Rake::Task['run_examples'].invoke
+  Rake::Task['run_profiler'].invoke
+end

data/bench/profiler.rb

@@ -0,0 +1,6 @@
+# $ bundle exec ruby bench/profiler.rb
+
+require 'bench/profiler_runner'
+
+runner = XmlssProfilerRunner.new(ARGV[0] ? ARGV[0].to_i : 1000)
+runner.print_flat(STDOUT, :min_percent => 1)

data/bench/profiler_runner.rb

@@ -0,0 +1,43 @@
+require 'ruby-prof'
+require 'xmlss'
+
+class XmlssProfilerRunner
+
+  attr_reader :result
+
+  def initialize(n)
+    build = Proc.new do
+      worksheet("5 columns, #{n} rows") {
+        column
+        column
+        column
+        column
+        column
+
+        n.times do |i|
+          row {
+            # put data into the row (infer type)
+            [1, "text", 123.45, "0001267", "$45.23"].each do |data_value|
+              cell { data data_value }
+            end
+          }
+        end
+      }
+    end
+
+    @result = RubyProf.profile do
+      Xmlss::Workbook.new(:output => {:pp => 2}, &build).to_file("./bench/profiler_#{n}.xml")
+    end
+
+  end
+
+  def print_flat(outstream, opts={})
+    RubyProf::FlatPrinter.new(@result).print(outstream, opts)
+    #RubyProf::GraphPrinter.new(@result).print(outstream, opts)
+  end
+
+  def print_graph(outstream, opts={})
+    RubyProf::GraphPrinter.new(@result).print(outstream, opts)
+  end
+
+end

data/examples/example_workbook.rb

@@ -1,19 +1,15 @@
-require 'rubygems'
-require 'test/env'
+require 'xmlss'
 
 class ExampleWorkbook < Xmlss::Workbook
-  def initialize
-    super
-    puts "Building #{self.name}.xml..."
-    build
-  end
 
-  def to_file(*options)
-    # write this workbooks xml data to a file
-    File.open("examples/#{self.name}.xml", "w") do |file|
-      file.write self.to_xml(*options)
-    end
+  def initialize(name, &build)
+    puts "Building #{name} workbook xml..."
+
+    super(:output => {:pp => 2}, &build)
+    self.to_file("./examples/#{name}.xml")
+
     puts "... ready - open in Excel or whatever..."
   end
+
 end
 

data/examples/layout.rb

@@ -1,16 +1,10 @@
 require 'examples/example_workbook'
 
-class Layout < ExampleWorkbook
-  def name; "layout"; end
-  def build
-    wksht = Xmlss::Worksheet.new('first')
-    4.times do
-      wksht.table.columns << Xmlss::Column.new
-    end
+# $ bundle exec ruby examples/layout.rb
 
-    5.times do
-      wksht.table.rows << Xmlss::Row.new
-    end
+ExampleWorkbook.new("layout") do
+
+  worksheet('first') {
 
     #  | A | B | C | D |
     # 1| x | x | x | x |
@@ -19,63 +13,43 @@ class Layout < ExampleWorkbook
     # 4| x |   x   | x |
     # 5| x |       | x |
 
+    4.times { column }
+
     # row 1: one cell per column
-    4.times do |i|
-      wksht.table.rows[0].cells << Xmlss::Cell.new({
-        :index => i+1,
-        :data => Xmlss::Data.new("x")
-      })
-    end
+    row {
+      4.times do |i|
+        cell(:index => i+1) { data "x" }
+      end
+    }
 
     # row 2: first cell colspan=2
-    wksht.table.rows[1].cells << Xmlss::Cell.new({
-      :index => 1,
-      :data => Xmlss::Data.new("x"),
-      :merge_across => 1
-    })
-    2.times do |i|
-      wksht.table.rows[1].cells << Xmlss::Cell.new({
-        :index => i+3,
-        :data => Xmlss::Data.new("x")
-      })
-    end
+    row {
+      cell(:index => 1, :merge_across => 1) { data "x" }
+      2.times do |i|
+        cell(:index => i+3) { data "x" }
+      end
+    }
 
     # row 3,4,5: more complex merging
     # => row 3
-    wksht.table.rows[2].cells << Xmlss::Cell.new({
-      :data => Xmlss::Data.new("x"),
-      :index => 1
-    })
-    wksht.table.rows[2].cells << Xmlss::Cell.new({
-      :data => Xmlss::Data.new("x"),
-      :merge_across => 1,
-      :merge_down => 2,
-      :index => 2
-    })
-    wksht.table.rows[2].cells << Xmlss::Cell.new({
-      :data => Xmlss::Data.new("x"),
-      :index => 4
-    })
+    row {
+      cell(:index => 1) { data "x" }
+      cell(:index => 2, :merge_across => 1, :merge_down => 2) { data "x" }
+      cell(:index => 4) { data "x" }
+    }
+
     # => row 4
-    wksht.table.rows[3].cells << Xmlss::Cell.new({
-      :data => Xmlss::Data.new("x"),
-      :index => 1
-    })
-    wksht.table.rows[3].cells << Xmlss::Cell.new({
-      :data => Xmlss::Data.new("x"),
-      :index => 4
-    })
+    row {
+      cell(:index => 1) { data "x" }
+      cell(:index => 4) { data "x" }
+    }
+
     # => row 5
-    wksht.table.rows[4].cells << Xmlss::Cell.new({
-      :data => Xmlss::Data.new("x"),
-      :index => 1
-    })
-    wksht.table.rows[4].cells << Xmlss::Cell.new({
-      :data => Xmlss::Data.new("x"),
-      :index => 4
-    })
+    row {
+      cell(:index => 1) { data "x" }
+      cell(:index => 4) { data "x" }
+    }
+
+  }
 
-    self.worksheets << wksht
-  end
 end
-Layout.new.to_file

data/examples/layout.xml

@@ -0,0 +1,66 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Workbook xmlns="urn:schemas-microsoft-com:office:spreadsheet" xmlns:ss="urn:schemas-microsoft-com:office:spreadsheet">
+  <Styles>
+  </Styles>
+  
+  <Worksheet ss:Name="first">
+    <Table>
+      <Column />
+      <Column />
+      <Column />
+      <Column />
+      <Row>
+        <Cell ss:Index="1">
+          <Data ss:Type="String">x</Data>
+        </Cell>
+        <Cell ss:Index="2">
+          <Data ss:Type="String">x</Data>
+        </Cell>
+        <Cell ss:Index="3">
+          <Data ss:Type="String">x</Data>
+        </Cell>
+        <Cell ss:Index="4">
+          <Data ss:Type="String">x</Data>
+        </Cell>
+      </Row>
+      <Row>
+        <Cell ss:Index="1" ss:MergeAcross="1">
+          <Data ss:Type="String">x</Data>
+        </Cell>
+        <Cell ss:Index="3">
+          <Data ss:Type="String">x</Data>
+        </Cell>
+        <Cell ss:Index="4">
+          <Data ss:Type="String">x</Data>
+        </Cell>
+      </Row>
+      <Row>
+        <Cell ss:Index="1">
+          <Data ss:Type="String">x</Data>
+        </Cell>
+        <Cell ss:Index="2" ss:MergeAcross="1" ss:MergeDown="2">
+          <Data ss:Type="String">x</Data>
+        </Cell>
+        <Cell ss:Index="4">
+          <Data ss:Type="String">x</Data>
+        </Cell>
+      </Row>
+      <Row>
+        <Cell ss:Index="1">
+          <Data ss:Type="String">x</Data>
+        </Cell>
+        <Cell ss:Index="4">
+          <Data ss:Type="String">x</Data>
+        </Cell>
+      </Row>
+      <Row>
+        <Cell ss:Index="1">
+          <Data ss:Type="String">x</Data>
+        </Cell>
+        <Cell ss:Index="4">
+          <Data ss:Type="String">x</Data>
+        </Cell>
+      </Row>
+    </Table>
+  </Worksheet>
+</Workbook>

data/examples/simple.rb

@@ -1,30 +1,25 @@
 require 'examples/example_workbook'
 
-class Simple < ExampleWorkbook
-  def name; "simple"; end
-  def build
+# $ bundle exec ruby examples/simple.rb
 
-    # add 1 row of simple data across 3 columns
-    wksht = Xmlss::Worksheet.new('1 row, 3 columns')
+# create a workbook with 1 row and 5 columns
+ExampleWorkbook.new("simple") do
 
-    wksht.table.columns << Xmlss::Column.new
-    wksht.table.columns << Xmlss::Column.new
-    wksht.table.columns << Xmlss::Column.new
-    wksht.table.columns << Xmlss::Column.new
-    wksht.table.columns << Xmlss::Column.new
+  worksheet('1 row, 5 columns') {
+    column
+    column
+    column
+    column
+    column
 
-    row1 = Xmlss::Row.new
+    row {
 
-    # put data into the row (infer type)
-    [1, "text", 123.45, "0001267", "$45.23"].each do |data|
-      row1.cells << Xmlss::Cell.new({
-        :data => Xmlss::Data.new(data)
-      })
-    end
+      # put data into the row (infer type)
+      [1, "text", 123.45, "0001267", "$45.23"].each do |data_value|
+        cell { data data_value }
+      end
 
-    wksht.table.rows << row1
-    self.worksheets << wksht
+    }
+  }
 
-  end
 end
-Simple.new.to_file(:format)