axlsx 1.0.17 → 1.0.18

data/lib/axlsx/workbook/worksheet/worksheet.rb

@@ -1,9 +1,9 @@
 # encoding: UTF-8
 module Axlsx
-  
-  # The Worksheet class represents a worksheet in the workbook. 
+
+  # The Worksheet class represents a worksheet in the workbook.
   class Worksheet
-    
+
     # The name of the worksheet
     # @return [String]
     attr_reader :name
@@ -21,7 +21,7 @@ module Axlsx
 
     # An array of content based calculated column widths.
     # @note a single auto fit data item is a hash with :longest => [String] and :sz=> [Integer] members.
-    # @return [Array] of Hash 
+    # @return [Array] of Hash
     attr_reader :auto_fit_data
 
     # An array of merged cell ranges e.d "A1:B3"
@@ -34,21 +34,47 @@ module Axlsx
     # The first row is considered the header, while subsequent rows are considerd to be data.
     # @return Array
     attr_reader :auto_filter
-    
+
+    # Page margins for printing the worksheet.
+    # @example
+    #      wb = Axlsx::Package.new.workbook
+    #      # using options when creating the worksheet.
+    #      ws = wb.add_worksheet :page_margins => {:left => 1.9, :header => 0.1}
+    #
+    #      # use the set method of the page_margins object
+    #      ws.page_margins.set(:bottom => 3, :footer => 0.7)
+    #
+    #      # set page margins in a block
+    #      ws.page_margins do |margins|
+    #        margins.right = 6
+    #        margins.top = 0.2
+    #      end
+    # @see PageMargins#initialize
+    # @return [PageMargins]
+    def page_margins
+      @page_margins ||= PageMargins.new
+      yield @page_margins if block_given?
+      @page_margins
+    end
+
     # Creates a new worksheet.
     # @note the recommended way to manage worksheets is Workbook#add_worksheet
     # @see Workbook#add_worksheet
-    # @option options [String] name The name of this sheet.
+    # @option options [String] name The name of this worksheet.
+    # @option options [Hash] page_margins A hash containing page margins for this worksheet. @see PageMargins
     def initialize(wb, options={})
-      @drawing = nil
+      @drawing = @page_margins = @auto_filter = nil
       @rows = SimpleTypedList.new Row
       self.workbook = wb
       @workbook.worksheets << self
       @auto_fit_data = []
       self.name = options[:name] || "Sheet" + (index+1).to_s
+
       @magick_draw = Magick::Draw.new
       @cols = SimpleTypedList.new Cell
       @merged_cells = []
+
+      @page_margins = PageMargins.new options[:page_margins] if options[:page_margins]
     end
 
     # convinience method to access all cells in this worksheet
@@ -57,26 +83,26 @@ module Axlsx
       rows.flatten
     end
 
-    # Creates merge information for this worksheet. 
+    # Creates merge information for this worksheet.
     # Cells can be merged by calling the merge_cells method on a worksheet.
-    # @example This would merge the three cells C1..E1    #  
+    # @example This would merge the three cells C1..E1    #
     #        worksheet.merge_cells "C1:E1"
     #        # you can also provide an array of cells to be merged
     #        worksheet.merge_cells worksheet.rows.first.cells[(2..4)]
     #        #alternatively you can do it from a single cell
     #        worksheet["C1"].merge worksheet["E1"]
-    # @param [Array, string]    
+    # @param [Array, string]
     def merge_cells(cells)
       @merged_cells << if cells.is_a?(String)
                          cells
                        elsif cells.is_a?(Array)
                          cells = cells.sort { |x, y| x.r <=> y.r }
                          "#{cells.first.r}:#{cells.last.r}"
-                       end 
+                       end
     end
 
 
-    # The demensions of a worksheet. This is not actually a required element by the spec, 
+    # The demensions of a worksheet. This is not actually a required element by the spec,
     # but at least a few other document readers expect this for conversion
     # @return [String] the A1:B2 style reference for the first and last row column intersection in the workbook
     def dimension
@@ -85,9 +111,10 @@ module Axlsx
 
 
     # Returns the cell or cells defined using excel style A1:B3 references.
-    # @param [String] cell_def the string defining the cell or range of cells
+    # @param [String|Integer] cell_def the string defining the cell or range of cells, or the rownumber
     # @return [Cell, Array]
     def [](cell_def)
+      return rows[cell_def - 1] if cell_def.is_a? Integer
       parts = cell_def.split(':')
       first = name_to_cell parts[0]
 
@@ -115,18 +142,20 @@ module Axlsx
     end
 
     # The name of the worksheet
+    # The name of a worksheet must be unique in the workbook, and must not exceed 31 characters
     # @param [String] v
-    def name=(v) 
+    def name=(v)
       DataTypeValidator.validate "Worksheet.name", String, v
+      raise ArgumentError, (ERR_SHEET_NAME_TOO_LONG % v) if v.size > 31
       sheet_names = @workbook.worksheets.map { |s| s.name }
-      raise ArgumentError, (ERR_DUPLICATE_SHEET_NAME % v) if sheet_names.include?(v) 
-      @name=v 
+      raise ArgumentError, (ERR_DUPLICATE_SHEET_NAME % v) if sheet_names.include?(v)
+      @name=v
     end
 
     # The auto filter range for the worksheet
     # @param [String] v
     # @see auto_filter
-    def auto_filter=(v) 
+    def auto_filter=(v)
       DataTypeValidator.validate "Worksheet.auto_filter", String, v
       @auto_filter = v
     end
@@ -163,18 +192,54 @@ module Axlsx
       @drawing || @drawing = Axlsx::Drawing.new(self)
     end
 
-    # Adds a row to the worksheet and updates auto fit data
+    # Adds a row to the worksheet and updates auto fit data.
+    # @example - put a vanilla row in your spreadsheet
+    #     ws.add_row [1, 'fish on my pl', '8']
+    #
+    # @example - specify a fixed width for a column in your spreadsheet
+    #     # The first column will ignore the content of this cell when calculating column autowidth.
+    #     # The second column will include this text in calculating the columns autowidth
+    #     # The third cell will set a fixed with of 80 for the column.
+    #     # If you need to un-fix a column width, use :auto. That will recalculate the column width based on all content in the column
+    #
+    #     ws.add_row ['I wish', 'for a fish', 'on my fish wish dish'], :widths=>[:ignore, :auto, 80]
+    #
+    # @example - specify a fixed height for a row
+    #     ws.add_row ['I wish', 'for a fish', 'on my fish wish dish'], :height => 40
+    #
+    # @example - create and use a style for all cells in the row
+    #     blue = ws.styles.add_style :color => "#00FF00"
+    #     ws.add_row [1, 2, 3], :style=>blue
+    #
+    # @example - only style some cells
+    #     blue = ws.styles.add_style :color => "#00FF00"
+    #     red = ws.styles.add_style :color => "#FF0000"
+    #     big = ws.styles.add_style :sz => 40
+    #     ws.add_row ["red fish", "blue fish", "one fish", "two fish"], :style=>[red, blue, nil, big] # the last nil is optional
+    #
+    #
+    # @example - force the second cell to be a float value
+    #     ws.add_row [3, 4, 5], :types => [nil, :float]
+    #
+    # @example - use << alias
+    #     ws << [3, 4, 5], :types => [nil, :float]
+    #
+    # @see Worksheet#column_widths
     # @return [Row]
     # @option options [Array] values
-    # @option options [Array, Symbol] types 
-    # @option options [Array, Integer] style 
+    # @option options [Array, Symbol] types
+    # @option options [Array, Integer] style
+    # @option options [Array] widths each member of the widths array will affect how auto_fit behavies.
+    # @option options [Float] height the row's height (in points)
     def add_row(values=[], options={})
       Row.new(self, values, options)
-      update_auto_fit_data @rows.last.cells
+      update_auto_fit_data @rows.last.cells, options.delete(:widths) || []
       yield @rows.last if block_given?
       @rows.last
     end
 
+    alias :<< :add_row
+
     # Set the style for cells in a specific row
     # @param [Integer] index or range of indexes in the table
     # @param [Integer] the cellXfs index
@@ -207,7 +272,7 @@ module Axlsx
     # @see README.md for an example
     def col_style(index, style, options={})
       offset = options.delete(:row_offset) || 0
-      @rows[(offset..-1)].each do |r| 
+      @rows[(offset..-1)].each do |r|
         cells = r.cells[index]
         next unless cells
         if cells.is_a?(Array)
@@ -218,13 +283,13 @@ module Axlsx
       end
     end
 
-    # This is a helper method that Lets you specify a fixed width for multiple columns in a worksheet in one go.    
+    # This is a helper method that Lets you specify a fixed width for multiple columns in a worksheet in one go.
     # Axlsx is sparse, so if you have not set data for a column, you cannot set the width.
     # Setting a fixed column width to nil will revert the behaviour back to calculating the width for you.
     # @example This would set the first and third column widhts but leave the second column in autofit state.
     #      ws.column_widths 7.2, nil, 3
     # @note For updating only a single column it is probably easier to just set ws.auto_fit_data[col_index][:fixed] directly
-    # @param [Integer|Float|Fixnum|nil] values 
+    # @param [Integer|Float|Fixnum|nil] values
     def column_widths(*args)
       args.each_with_index do |value, index|
         raise ArgumentError, "Invalid column specification" unless index < @auto_fit_data.size
@@ -233,14 +298,14 @@ module Axlsx
       end
     end
 
-    # Adds a chart to this worksheets drawing. This is the recommended way to create charts for your worksheet. This method wraps the complexity of dealing with ooxml drawing, anchors, markers graphic frames chart objects and all the other dirty details. 
+    # Adds a chart to this worksheets drawing. This is the recommended way to create charts for your worksheet. This method wraps the complexity of dealing with ooxml drawing, anchors, markers graphic frames chart objects and all the other dirty details.
     # @param [Class] chart_type
     # @option options [Array] start_at
     # @option options [Array] end_at
     # @option options [Cell, String] title
     # @option options [Boolean] show_legend
-    # @option options [Integer] style 
-    # @note each chart type also specifies additional options 
+    # @option options [Integer] style
+    # @note each chart type also specifies additional options
     # @see Chart
     # @see Pie3DChart
     # @see Bar3DChart
@@ -265,9 +330,19 @@ module Axlsx
     # @return [String]
     def to_xml
       builder = Nokogiri::XML::Builder.new(:encoding => ENCODING) do |xml|
-        xml.worksheet(:xmlns => XML_NS, 
+        xml.worksheet(:xmlns => XML_NS,
                       :'xmlns:r' => XML_NS_R) {
+          # another patch for the folks at rubyXL as thier parser depends on this optional element.
           xml.dimension :ref=>dimension unless rows.size == 0
+          # this is required by rubyXL, spec says who cares - but it seems they didnt notice
+          # however, it also seems to be causing some odd [Grouped] stuff in excel 2011 - so
+          # removing until I understand it better.
+          # xml.sheetViews {
+          #  xml.sheetView(:tabSelected => 1, :workbookViewId => 0) {
+          #    xml.selection :activeCell=>"A1", :sqref => "A1"
+          #  }
+          # }
+
           if @auto_fit_data.size > 0
             xml.cols {
               @auto_fit_data.each_with_index do |col, index|
@@ -283,7 +358,8 @@ module Axlsx
           }
           xml.autoFilter :ref=>@auto_filter if @auto_filter
           xml.mergeCells(:count=>@merged_cells.size) { @merged_cells.each { | mc | xml.mergeCell(:ref=>mc) } } unless @merged_cells.empty?
-          xml.drawing :"r:id"=>"rId1" if @drawing          
+          page_margins.to_xml(xml) if @page_margins
+          xml.drawing :"r:id"=>"rId1" if @drawing
         }
       end
       builder.to_xml(:save_with => 0)
@@ -297,28 +373,35 @@ module Axlsx
         r
     end
 
-    private 
+    private
 
     # assigns the owner workbook for this worksheet
     def workbook=(v) DataTypeValidator.validate "Worksheet.workbook", Workbook, v; @workbook = v; end
 
-    # Updates auto fit data. 
-    # We store an auto_fit_data item for each column. when a row is added we multiple the font size by the length of the text to 
+    # Updates auto fit data.
+    # We store an auto_fit_data item for each column. when a row is added we multiple the font size by the length of the text to
     # attempt to identify the longest cell in the column. This is not 100% accurate as it needs to take into account
-    # any formatting that will be applied to the data, as well as the actual rendering size when the length and size is equal 
+    # any formatting that will be applied to the data, as well as the actual rendering size when the length and size is equal
     # for two cells.
+
     # @return [Array] of Cell objects
     # @param [Array] cells an array of cells
-    def update_auto_fit_data(cells)
+    # @param [Array] widths an array of cell widths @see Worksheet#add_row
+    def update_auto_fit_data(cells, widths=[])
       # TODO delay this until rendering. too much work when we dont know what they are going to do to the sheet.
       styles = self.workbook.styles
       cellXfs, fonts = styles.cellXfs, styles.fonts
       sz = 11
       cells.each_with_index do |item, index|
-        # ignore formula - there is no way for us to know the result
-        next if item.value.is_a?(String) && item.value.start_with?('=')
+        col = @auto_fit_data[index] ||= {:longest=>"", :sz=>sz, :fixed=>nil}
+        width = widths[index]
+        # set fixed width and skip if numeric width is given
+        col[:fixed] = width if [Integer, Float, Fixnum].include?(width.class)
+        # ignore default column widths and formula
+        next if width == :ignore || (item.value.is_a?(String) && item.value.start_with?('='))
+        # make sure we can turn that fixed with off!
+        col[:fixed] = nil if width == :auto
 
-        col = @auto_fit_data[index] || {:longest=>"", :sz=>sz, :fixed=>nil} 
         cell_xf = cellXfs[item.style]
         font = fonts[cell_xf.fontId || 0]
         sz = item.sz || font.sz || fonts[0].sz
@@ -326,16 +409,15 @@ module Axlsx
           col[:sz] =  sz
           col[:longest] = item.value.to_s
         end
-        @auto_fit_data[index] = col
       end
       cells
     end
-    
+
     # Determines the proper width for a column based on content.
-    # @note 
+    # @note
     #   width = Truncate([!{Number of Characters} * !{Maximum Digit Width} + !{5 pixel padding}]/!{Maximum Digit Width}*256)/256
     # @return [Float]
-    # @param [Hash] A hash of auto_fit_data 
+    # @param [Hash] A hash of auto_fit_data
     def auto_width(col)
       return col[:fixed] unless col[:fixed] == nil
 
@@ -348,21 +430,21 @@ module Axlsx
     end
 
     # Something to look into:
-    #  width calculation actually needs to be done agains the formatted value for items that apply a 
+    #  width calculation actually needs to be done agains the formatted value for items that apply a
     # format
     # def excel_format(cell)
     #   # The most common case.
     #   return time.value.to_s if cell.style == 0
     #
-    #   # The second most common case   
+    #   # The second most common case
     #   num_fmt = workbook.styles.cellXfs[items.style].numFmtId
     #   return value.to_s if num_fmt == 0
-    #   
+    #
     #   format_code = workbook.styles.numFmts[num_fmt]
     #   # need to find some exceptionally fast way of parsing value according to
     #   # an excel format_code
     #   item.value.to_s
-    # end      
+    # end
 
   end
 end

data/test/drawing/tc_chart.rb

@@ -41,9 +41,9 @@ class TestChart < Test::Unit::TestCase
 
   end
 
-  def end_at
+  def test_end_at
     @chart.end_at 25, 90
-    assert_equal(@chart.graphic_frame.anchor.from.col, 25)
+    assert_equal(@chart.graphic_frame.anchor.to.col, 25)
     assert_equal(@chart.graphic_frame.anchor.to.row, 90)
   end
 

data/test/stylesheet/tc_cell_alignment.rb

@@ -5,8 +5,7 @@ class TestCellAlignment < Test::Unit::TestCase
   def setup    
     @item = Axlsx::CellAlignment.new
   end
-  def teardown
-  end
+
   def test_initialiation
     assert_equal(@item.horizontal, nil)
     assert_equal(@item.vertical, nil)
@@ -17,7 +16,13 @@ class TestCellAlignment < Test::Unit::TestCase
     assert_equal(@item.justifyLastLine, nil)
     assert_equal(@item.shrinkToFit, nil)
     assert_equal(@item.readingOrder, nil)
-
+    options =  { :horizontal => :left, :vertical => :top, :textRotation => 3, 
+                 :wrapText => true, :indent => 2, :relativeIndent => 5, 
+      :justifyLastLine => true, :shrinkToFit => true, :readingOrder => 2 }
+    ca = Axlsx::CellAlignment.new options
+    options.each do |key, value|
+      assert_equal(ca.send(key.to_sym),value)
+    end
   end
 
   def test_horizontal

data/test/stylesheet/tc_font.rb

@@ -17,6 +17,7 @@ class TestFont < Test::Unit::TestCase
     assert_equal(@item.family, nil)
     assert_equal(@item.b, nil)
     assert_equal(@item.i, nil)
+    assert_equal(@item.u, nil)
     assert_equal(@item.strike, nil)
     assert_equal(@item.outline, nil)
     assert_equal(@item.shadow, nil)
@@ -61,6 +62,13 @@ class TestFont < Test::Unit::TestCase
     assert_nothing_raised { @item.i = true }
     assert_equal(@item.i, true)
   end
+  
+    # def u=(v) Axlsx::validate_boolean v; @u = v end
+  def test_u
+    assert_raise(ArgumentError) { @item.u = -7 }
+    assert_nothing_raised { @item.u = true }
+    assert_equal(@item.u, true)
+  end
 
     # def strike=(v) Axlsx::validate_boolean v; @strike = v end
   def test_strike

data/test/stylesheet/tc_styles.rb

@@ -42,10 +42,14 @@ class TestStyles < Test::Unit::TestCase
 
     assert(xf.alignment.is_a?(Axlsx::CellAlignment), "alignment was created")
     assert_equal(xf.alignment.horizontal, :left, "horizontal alignment applied")
-    assert_equal(xf.applyProtection, 1, "protection applied")
     assert_equal(xf.protection.hidden, true, "hidden protection set")
     assert_equal(xf.protection.locked, true, "cell locking set")
-    assert_raise(ArgumentError, "should reject invalid borderId") { @styles.add_style :border => 2 }
+    assert_raise(ArgumentError, "should reject invalid borderId") { @styles.add_style :border => 2 }    
+
+    
+    assert_equal(xf.applyProtection, 1, "protection applied")
+    assert_equal(xf.applyBorder, true, "border applied")
+    assert_equal(xf.applyNumberFormat, true, "border applied")
 
   end
 

data/test/workbook/worksheet/tc_cell.rb

@@ -10,7 +10,7 @@ class TestCell < Test::Unit::TestCase
     @row = @ws.add_row
     @c = @row.add_cell 1, :type=>:float, :style=>1
   end
-  
+
   def test_initialize
     assert_equal(@row.cells.last, @c, "the cell was added to the row")
     assert_equal(@c.type, :float, "type option is applied")
@@ -24,6 +24,10 @@ class TestCell < Test::Unit::TestCase
     assert_equal(Axlsx::STYLE_DATE, c.style)
   end
 
+  def test_row
+    assert_equal(@c.row, @row)
+  end
+
   def test_index
     assert_equal(@c.index, @row.cells.index(@c))
   end
@@ -42,20 +46,22 @@ class TestCell < Test::Unit::TestCase
 
   def test_style
     assert_raise(ArgumentError, "must reject invalid style indexes") { @c.style=@c.row.worksheet.workbook.styles.cellXfs.size }
-    assert_nothing_raised("must allow valid style index changes") {@c.style=1} 
+    assert_nothing_raised("must allow valid style index changes") {@c.style=1}
     assert_equal(@c.style, 1)
   end
 
   def test_type
-    assert_raise(ArgumentError, "type must be :string, :integer, :float, :time") { @c.type = :array }
+    assert_raise(ArgumentError, "type must be :string, :integer, :float, :date, :time, :boolean") { @c.type = :array }
     assert_nothing_raised("type can be changed") { @c.type = :string }
     assert_equal(@c.value, "1.0", "changing type casts the value")
-    
+
     assert_equal(@row.add_cell(Time.now).type, :time, 'time should be time')
+    assert_equal(@row.add_cell(Date.today).type, :date, 'date should be date')
+    assert_equal(@row.add_cell(true).type, :boolean, 'boolean should be boolean')
   end
 
   def test_value
-    assert_raise(ArgumentError, "type must be :string, :integer, :float, :time") { @c.type = :array }
+    assert_raise(ArgumentError, "type must be :string, :integer, :float, :date, :time, :boolean") { @c.type = :array }
     assert_nothing_raised("type can be changed") { @c.type = :string }
     assert_equal(@c.value, "1.0", "changing type casts the value")
   end
@@ -67,14 +73,17 @@ class TestCell < Test::Unit::TestCase
   def test_cell_type_from_value
     assert_equal(@c.send(:cell_type_from_value, 1.0), :float)
     assert_equal(@c.send(:cell_type_from_value, 1), :integer)
+    assert_equal(@c.send(:cell_type_from_value, Date.today), :date)
     assert_equal(@c.send(:cell_type_from_value, Time.now), :time)
     assert_equal(@c.send(:cell_type_from_value, []), :string)
     assert_equal(@c.send(:cell_type_from_value, "d"), :string)
     assert_equal(@c.send(:cell_type_from_value, nil), :string)
     assert_equal(@c.send(:cell_type_from_value, -1), :integer)
+    assert_equal(@c.send(:cell_type_from_value, true), :boolean)
+    assert_equal(@c.send(:cell_type_from_value, false), :boolean)
   end
 
-  def test_cast_value    
+  def test_cast_value
     @c.type = :string
     assert_equal(@c.send(:cast_value, 1.0), "1.0")
     @c.type = :integer
@@ -83,7 +92,9 @@ class TestCell < Test::Unit::TestCase
     assert_equal(@c.send(:cast_value, "1.0"), 1.0)
     @c.type = :string
     assert_equal(@c.send(:cast_value, nil), "")
-
+    @c.type = :boolean
+    assert_equal(@c.send(:cast_value, true), 1)
+    assert_equal(@c.send(:cast_value, false), 0)
   end
 
   def test_color
@@ -181,7 +192,7 @@ class TestCell < Test::Unit::TestCase
     @c.row.add_cell 2
     @c.row.add_cell 3
     @c.merge "A2"
-    assert_equal(@c.row.worksheet.merged_cells.last, "A1:A2")    
+    assert_equal(@c.row.worksheet.merged_cells.last, "A1:A2")
   end
 
   def test_merge_with_cell
@@ -189,7 +200,7 @@ class TestCell < Test::Unit::TestCase
     @c.row.add_cell 2
     @c.row.add_cell 3
     @c.merge @row.cells.last
-    assert_equal(@c.row.worksheet.merged_cells.last, "A1:C1")    
+    assert_equal(@c.row.worksheet.merged_cells.last, "A1:C1")
   end
 
   def test_equality
@@ -203,5 +214,24 @@ class TestCell < Test::Unit::TestCase
 
   end
 
+  def test_ssti
+    assert_raise(ArgumentError, "ssti must be an unsigned integer!") { @c.send(:ssti=, -1) }
+    @c.send :ssti=, 1
+    assert_equal(@c.ssti, 1)
+  end
+
+  def test_to_xml
+    # TODO This could use some much more stringent testing related to the xml content generated!
+    row = @ws.add_row [Time.now, Date.today, true, 1, 1.0, "text", "=sum(A1:A2)"]
+    schema = Nokogiri::XML::Schema(File.open(Axlsx::SML_XSD))
+    doc = Nokogiri::XML(@ws.to_xml)
+    errors = []
+    schema.validate(doc).each do |error|
+      errors.push error
+      puts error.message
+    end
+    assert(errors.empty?, "error free validation")
+
+  end
 
 end