xmlss 0.0.1

data/.gitignore

@@ -0,0 +1,6 @@
+pkg/*
+.bundle
+*.gem
+*.log
+*.xml
+

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in xmlss.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,28 @@
+PATH
+  remote: .
+  specs:
+    xmlss (0.0.1)
+      nokogiri (~> 1.4.0)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    json (1.5.1)
+    kelredd-useful (0.4.1)
+      json
+    leftright (0.9.0)
+    nokogiri (1.4.4)
+    shoulda (2.11.3)
+    test-belt (0.2.1)
+      kelredd-useful (~> 0.4.0)
+      leftright (~> 0.9.0)
+      shoulda (~> 2.11)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.0)
+  nokogiri (~> 1.4.0)
+  test-belt (= 0.2.1)
+  xmlss!

data/README.rdoc

@@ -0,0 +1,154 @@
+= Xmlss
+
+== 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).
+
+== Installation
+
+    gem install xmlss
+
+== Simple Example
+
+    require 'xmlss'
+
+    workbook = Xmlss::Workbook.new
+    workbook.worksheets       # => []
+
+    sheet1 = Xmlss::Worksheet.new({
+      :name => 'Sheet 1'
+    })
+    sheet1.table = Xmlss::Table.new
+    sheet1.table.rows         # => []
+
+    row1 = Xmlss::Row.new(1, 'some data', 54.54)
+    row1.cells.count = 3
+    row1.cells.first.data     # => 1
+
+    sheet1.table.rows << row1
+    workbook.worksheets << sheet1
+
+    workbook.to_xml           # => "..." (XML Spreadsheet xml string)
+
+== Usage
+see the examples folder for some use case examples.
+
+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
+* *formula*: string
+* *href*: string
+* *merge_across*: int, default: 0
+* *merge_down*: int, default: 0
+* *tool_tip*: string
+
+=== Xmlss::Data
+* *type*: :number, :datetime, :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
+* *underline*: :none, :single, :double
+* *alignment*: :none, :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 (see code for options)
+
+=== 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
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,7 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'test_belt/rake_tasks'
+TestBelt::RakeTasks.for :test
+
+task :default => :build

data/examples/example_workbook.rb

@@ -0,0 +1,19 @@
+require 'rubygems'
+require 'test/env'
+
+class ExampleWorkbook < Xmlss::Workbook
+  def initialize
+    super
+    puts "Builing #{self.name}.xml..."
+    build
+  end
+
+  def to_file
+    # write this workbooks xml data to a file
+    File.open("examples/#{self.name}.xml", "w") do |file|
+      file.write self.to_xml
+    end
+    puts "... ready - open in Excel or whatever..."
+  end
+end
+

data/examples/layout.rb

@@ -0,0 +1,81 @@
+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
+
+    5.times do
+      wksht.table.rows << Xmlss::Row.new
+    end
+
+    #  | A | B | C | D |
+    # 1| x | x | x | x |
+    # 2|   x   | x | x |
+    # 3| x |       | x |
+    # 4| x |   x   | x |
+    # 5| x |       | x |
+
+    # 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 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 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 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 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
+    })
+
+    self.worksheets << wksht
+  end
+end
+Layout.new.to_file

data/examples/simple.rb

@@ -0,0 +1,30 @@
+require 'examples/example_workbook'
+
+class Simple < ExampleWorkbook
+  def name; "simple"; end
+  def build
+
+    # add 1 row of simple data across 3 columns
+    wksht = Xmlss::Worksheet.new('1 row, 3 columns')
+
+    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
+
+    row1 = Xmlss::Row.new
+
+    # 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
+
+    wksht.table.rows << row1
+    self.worksheets << wksht
+
+  end
+end
+Simple.new.to_file

data/examples/styles.rb

@@ -0,0 +1,85 @@
+require 'examples/example_workbook'
+
+class Styles < ExampleWorkbook
+  def name; "styles"; end
+  def build
+
+    wksht = Xmlss::Worksheet.new('styles')
+    wksht.table.columns << Xmlss::Column.new
+
+    self.styles << Xmlss::Style::Base.new('centered') do
+      alignment(
+        :horizontal => :center,
+        :vertical => :center
+      )
+    end
+    wksht.table.rows << Xmlss::Row.new
+    wksht.table.rows[0].cells << Xmlss::Cell.new({
+      :style_id => "centered",
+      :data => Xmlss::Data.new("x")
+    })
+
+    self.styles << Xmlss::Style::Base.new('bordered') do
+      alignment(:wrap_text => true)
+      border(
+        :position => :top,
+        :weight => :hairline,
+        :line_style => :continuous
+      )
+      border(
+        :position => :right,
+        :weight => :medium,
+        :line_style => :continuous
+      )
+      border(
+        :position => :bottom,
+        :weight => :thick,
+        :line_style => :dash_dot,
+        :color => '#00FF00'
+      )
+      border(
+        :position => :left,
+        :weight => :thin,
+        :line_style => :dot
+      )
+    end
+    wksht.table.rows << Xmlss::Row.new
+    wksht.table.rows[1].cells << Xmlss::Cell.new({
+      :style_id => "bordered",
+      :data => Xmlss::Data.new(%{blah blah blah blah blah\nblah blah blah blah\nblah blah blah blah})
+    })
+
+    self.styles << Xmlss::Style::Base.new('fonted') do
+      font(
+        :bold => true,
+        :color => "#FF0000",
+        :italic => true,
+        :size => 18,
+        :strike_through => true,
+        :underline => true
+      )
+    end
+    wksht.table.rows << Xmlss::Row.new
+    wksht.table.rows[2].cells << Xmlss::Cell.new({
+      :style_id => "fonted",
+      :data => Xmlss::Data.new("Cool Font Styles!!")
+    })
+
+    self.styles << Xmlss::Style::Base.new('interior') do
+      interior(
+        :color => "#FF0000",
+        :pattern => :diag_cross,
+        :pattern_color => '#00FFFF'
+      )
+      font(:color => "#FFFFFF")
+    end
+    wksht.table.rows << Xmlss::Row.new
+    wksht.table.rows[3].cells << Xmlss::Cell.new({
+      :style_id => "interior",
+      :data => Xmlss::Data.new("Weird Styles Man...")
+    })
+
+    self.worksheets << wksht
+  end
+end
+Styles.new.to_file

data/examples/text.rb

@@ -0,0 +1,36 @@
+require 'examples/example_workbook'
+
+class Text < ExampleWorkbook
+  def name; "text"; end
+  def build
+
+    # add in general text style
+    self.styles << Xmlss::Style::Base.new('general_text') do
+      alignment(
+        :horizontal => :left,
+        :vertical => :top,
+        :wrap_text => true
+      )
+      number_format(
+        :format => "@"  # set format to text explicitly
+      )
+    end
+
+    # add single cell with text data and specify general text style
+    wksht = Xmlss::Worksheet.new('text')
+    wksht.table.columns << Xmlss::Column.new
+    row1 = Xmlss::Row.new
+    row1.cells << Xmlss::Cell.new({
+      :style_id => "general_text",
+      :data => Xmlss::Data.new(%{
+A blob of text
+with line breaks
+  and leading space
+      })
+    })
+    wksht.table.rows << row1
+    self.worksheets << wksht
+
+  end
+end
+Text.new.to_file

data/lib/xmlss/cell.rb

@@ -0,0 +1,38 @@
+require 'xmlss/data'
+
+module Xmlss
+  class Cell
+
+    include Xmlss::Xml
+    def xml
+      { :node => :cell,
+        :attributes => [:index, :style_i_d, :formula, :h_ref, :merge_across, :merge_down],
+        :children => [:data] }
+    end
+
+    attr_accessor :style_id, :formula, :href, :merge_across, :merge_down
+    attr_accessor :index, :data
+    alias_method :style_i_d, :style_id
+    alias_method :h_ref, :href
+
+    def initialize(attrs={})
+      self.index = attrs[:index]
+      self.style_id = attrs[:style_id]
+      self.formula = attrs[:formula]
+      self.href = attrs[:href]
+      self.merge_across = attrs[:merge_across] || 0
+      self.merge_down = attrs[:merge_down] || 0
+      self.data = attrs[:data]
+    end
+
+    [:index, :merge_across, :merge_down].each do |meth|
+      define_method("#{meth}=") do |value|
+        if value && !value.kind_of?(::Fixnum)
+          raise ArgumentError, "must specify #{meth} as a Fixnum"
+        end
+        instance_variable_set("@#{meth}", value && value <= 0 ? nil : value)
+      end
+    end
+
+  end
+end

data/lib/xmlss/column.rb

@@ -0,0 +1,28 @@
+module Xmlss
+  class Column
+
+    include Xmlss::Xml
+    def xml
+      { :node => :column,
+        :attributes => [:style_i_d, :width, :auto_fit_width, :hidden] }
+    end
+
+    attr_accessor :style_id, :width, :auto_fit_width, :hidden
+    alias_method :style_i_d, :style_id
+
+    def initialize(attrs={})
+      self.style_id = attrs[:style_id]
+      self.width = attrs[:width]
+      self.auto_fit_width = attrs[:auto_fit_width] || false
+      self.hidden = attrs[:hidden] || false
+    end
+
+    def width=(value)
+      if value && !value.kind_of?(::Numeric)
+        raise ArgumentError, "must specify width as a Numeric"
+      end
+      @width = value && value < 0 ? nil : value
+    end
+
+  end
+end

data/lib/xmlss/data.rb

@@ -0,0 +1,67 @@
+require 'date'
+
+module Xmlss
+  class Data
+
+    LB = "
"
+
+    include Xmlss::Xml
+    def xml
+      { :node => :data,
+        :attributes => [:type],
+        :value => :xml_value }
+    end
+
+    include Xmlss::Enum
+    enum :type, {
+      :number => "Number",
+      :date_time => "DateTime",
+      :boolean => "Boolean",
+      :string => "String",
+      :error => "Error"
+    }
+
+    attr_accessor :value
+
+    def initialize(value="", attrs={})
+      self.value = value
+      self.type = attrs[:type] if attrs[:type]
+    end
+
+    def value=(v)
+      if self.type.nil?
+        self.type = value_type(v)
+      end
+      @value = v
+    end
+
+    def xml_value
+      case value
+      when ::Date, ::Time, ::DateTime
+        value.strftime("%Y-%m-%dT%H:%M:%S")
+      when ::String, ::Symbol
+        value.to_s.gsub(/(\r|\n)+/, LB)
+      else
+        value.to_s
+      end
+    end
+
+    private
+
+    def value_type(v)
+      case v
+      when ::Numeric
+        :number
+      when ::Date, ::Time
+        :date_time
+      when ::TrueClass, ::FalseClass
+        :boolean
+      when ::String, ::Symbol
+        :string
+      else
+        :string
+      end
+    end
+
+  end
+end

data/lib/xmlss/enum.rb

@@ -0,0 +1,56 @@
+# common methods used for handling enum data
+module Xmlss
+  module Enum
+
+    module ClassMethods
+      def enum(name, map)
+        # TODO: validate name
+        unless map.kind_of?(::Hash)
+          raise ArguementError, "please specify the enum map as a Hash"
+        end
+
+        # define an anonymous Module to extend on
+        # defining a class level map reader
+        class_methods = Module.new do
+          define_method(name) do |key|
+            class_variable_get("@@#{name}")[key]
+          end
+        end
+
+        # set a class variable to store the enum map (used by above reader)
+        # extend the anonymous module to get tne above class
+        #   level reader for the map
+        class_eval do
+          class_variable_set("@@#{name}", map)
+          extend class_methods
+        end
+
+        # instance writer for the enum value
+        define_method("#{name}=") do |value|
+          map = self.class.send(:class_variable_get, "@@#{name}")
+          instance_variable_set("@#{name}", if value && map.has_key?(value)
+            # write by key
+            map[value]
+          elsif map.has_value?(value)
+            # write by value
+            value
+          else
+            nil
+          end)
+        end
+
+        # instance reader for the enum value
+        define_method(name) do
+          instance_variable_get("@#{name}")
+        end
+      end
+    end
+
+    class << self
+      def included(receiver)
+        receiver.send :extend, ClassMethods
+      end
+    end
+
+  end
+end

data/lib/xmlss/item_set.rb

@@ -0,0 +1,17 @@
+module Xmlss
+  class ItemSet < ::Array
+    include Xmlss::Xml
+    def xml
+      { :node => name,
+        :children => self }
+    end
+
+    attr_accessor :name
+
+    def initialize(name=nil, *args)
+      self.name = name
+      super *args
+    end
+
+  end
+end