axlsx 1.0.16 → 1.0.18

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

@@ -1,53 +1,61 @@
-# -*- coding: utf-8 -*-
+# encoding: UTF-8
 module Axlsx
-  # A cell in a worksheet. 
+  # A cell in a worksheet.
   # Cell stores inforamation requried to serialize a single worksheet cell to xml. You must provde the Row that the cell belongs to and the cells value. The data type will automatically be determed if you do not specify the :type option. The default style will be applied if you do not supply the :style option. Changing the cell's type will recast the value to the type specified. Altering the cell's value via the property accessor will also automatically cast the provided value to the cell's type.
   # @example Manually creating and manipulating Cell objects
-  #   ws = Workbook.new.add_worksheet 
+  #   ws = Workbook.new.add_worksheet
   #   # This is the simple, and recommended way to create cells. Data types will automatically be determined for you.
   #   ws.add_row :values => [1,"fish",Time.now]
   #
   #   # but you can also do this
   #   r = ws.add_row
   #   r.add_cell 1
-  # 
+  #
   #   # or even this
   #   r = ws.add_row
   #   c = Cell.new row, 1, :value=>integer
   #
   #   # cells can also be accessed via Row#cells. The example here changes the cells type, which will automatically updated the value from 1 to 1.0
   #   r.cells.last.type = :float
-  # 
+  #
   # @note The recommended way to generate cells is via Worksheet#add_row
-  # 
+  #
   # @see Worksheet#add_row
   class Cell
 
+
+    # An array of available inline styes.
+    INLINE_STYLES = ['value', 'type', 'font_name', 'charset',
+                         'family', 'b', 'i', 'strike','outline',
+                         'shadow', 'condense', 'extend', 'u',
+                         'vertAlign', 'sz', 'color', 'scheme']
+
+
     # The index of the cellXfs item to be applied to this cell.
-    # @return [Integer] 
+    # @return [Integer]
     # @see Axlsx::Styles
     attr_reader :style
 
     # The row this cell belongs to.
     # @return [Row]
     attr_reader :row
-    
-    # The cell's data type. Currently only four types are supported, :time, :float, :integer and :string.
-    # Changing the type for a cell will recast the value into that type. If no type option is specified in the constructor, the type is 
+
+    # The cell's data type. Currently only six types are supported, :date, :time, :float, :integer, :string and :boolean.
+    # Changing the type for a cell will recast the value into that type. If no type option is specified in the constructor, the type is
     # automatically determed.
     # @see Cell#cell_type_from_value
-    # @return [Symbol] The type of data this cell's value is cast to. 
-    # @raise [ArgumentExeption] Cell.type must be one of [:time, :float, :integer, :string]
-    # @note 
+    # @return [Symbol] The type of data this cell's value is cast to.
+    # @raise [ArgumentExeption] Cell.type must be one of [:date, time, :float, :integer, :string, :boolean]
+    # @note
     #  If the value provided cannot be cast into the type specified, type is changed to :string and the following logic is applied.
-    #   :string to :integer or :float, type coversions always return 0 or 0.0    
+    #   :string to :integer or :float, type conversions always return 0 or 0.0
     #   :string, :integer, or :float to :time conversions always return the original value as a string and set the cells type to :string.
     #  No support is currently implemented for parsing time strings.
     attr_reader :type
     # @see type
-    def type=(v) 
-      RestrictionValidator.validate "Cell.type", [:time, :float, :integer, :string], v      
-      @type=v 
+    def type=(v)
+      RestrictionValidator.validate "Cell.type", [:date, :time, :float, :integer, :string, :boolean], v
+      @type=v
       self.value = @value unless @value.nil?
     end
 
@@ -60,7 +68,7 @@ module Axlsx
       #TODO: consider doing value based type determination first?
       @value = cast_value(v)
     end
-    
+
     # The inline font_name property for the cell
     # @return [String]
     attr_reader :font_name
@@ -131,7 +139,7 @@ module Axlsx
     # @return [Color]
     attr_reader :color
     # @param [String] The 8 character representation for an rgb color #FFFFFFFF"
-    def color=(v) 
+    def color=(v)
       @color = v.is_a?(Color) ? v : Color.new(:rgb=>v)
     end
 
@@ -156,7 +164,7 @@ module Axlsx
     def scheme=(v) RestrictionValidator.validate "Cell.schema", [:none, :major, :minor], v; @scheme = v; end
 
     # @param [Row] row The row this cell belongs to.
-    # @param [Any] value The value associated with this cell. 
+    # @param [Any] value The value associated with this cell.
     # @option options [Symbol] type The intended data type for this cell. If not specified the data type will be determined internally based on the vlue provided.
     # @option options [Integer] style The index of the cellXfs item to be applied to this cell. If not specified, the default style (0) will be applied.
     # @option options [String] font_name
@@ -175,9 +183,11 @@ module Axlsx
     # @option options [String] color an 8 letter rgb specification
     # @option options [Symbol] scheme must be one of :none, major, :minor
     def initialize(row, value="", options={})
-      self.row=row      
+      self.row=row
+      @font_name = @charset = @family = @b = @i = @strike = @outline = @shadow = nil
+      @condense = @u = @vertAlign = @sz = @color = @scheme = @extend = @ssti = nil
       @styles = row.worksheet.workbook.styles
-      @row.cells << self      
+      @row.cells << self
       options.each do |o|
         self.send("#{o[0]}=", o[1]) if self.respond_to? "#{o[0]}="
       end
@@ -186,6 +196,24 @@ module Axlsx
       @value = cast_value(value)
     end
 
+    # The Shared Strings Table index for this cell
+    # @return [Integer]
+    attr_reader :ssti
+
+    # equality comparison to test value, type and inline style attributes
+    # this is how we work out if the cell needs to be added or already exists in the shared strings table
+    def shareable(v)
+
+      #using reject becase 1.8.7 select returns an array...
+      v_hash = v.instance_values.reject { |key, val| !INLINE_STYLES.include?(key) }
+      self_hash = self.instance_values.reject { |key, val| !INLINE_STYLES.include?(key) }
+      # required as color is an object, and the comparison will fail even though both use the same color.
+      v_hash['color'] = v_hash['color'].instance_values if v_hash['color']
+      self_hash['color'] = self_hash['color'].instance_values if self_hash['color']
+
+      v_hash == self_hash
+    end
+
     # @return [Integer] The index of the cell in the containing row.
     def index
       @row.cells.index(self)
@@ -193,14 +221,14 @@ module Axlsx
 
     # @return [String] The alpha(column)numeric(row) reference for this sell.
     # @example Relative Cell Reference
-    #   ws.rows.first.cells.first.r #=> "A1" 
+    #   ws.rows.first.cells.first.r #=> "A1"
     def r
-      "#{col_ref}#{@row.index+1}"      
+      "#{col_ref}#{@row.index+1}"
     end
 
     # @return [String] The absolute alpha(column)numeric(row) reference for this sell.
     # @example Absolute Cell Reference
-    #   ws.rows.first.cells.first.r #=> "$A$1" 
+    #   ws.rows.first.cells.first.r #=> "$A$1"
     def r_abs
       "$#{r.split('').join('$')}"
     end
@@ -229,74 +257,88 @@ module Axlsx
                     target.r
                   end
       self.row.worksheet.merge_cells "#{self.r}:#{range_end}" unless range_end.nil?
-    end              
+    end
+
+    # builds an xml text run based on this cells attributes. This is extracted from to_xml so that shared strings can use it.
+    # @param [Nokogiri::XML::Builder] xml The document builder instance this output will be added to.
+    # @return [String] the xml for this cell's text run
+    def run_xml(xml)
+      if (self.instance_values.keys & INLINE_STYLES).size > 0
+        xml.r {
+          xml.rPr {
+            xml.rFont(:val=>@font_name) if @font_name
+            xml.charset(:val=>@charset) if @charset
+            xml.family(:val=>@family) if @family
+            xml.b(:val=>@b) if @b
+            xml.i(:val=>@i) if @i
+            xml.strike(:val=>@strike) if @strike
+            xml.outline(:val=>@outline) if @outline
+            xml.shadow(:val=>@shadow) if @shadow
+            xml.condense(:val=>@condense) if @condense
+            xml.extend(:val=>@extend) if @extend
+            @color.to_xml(xml) if @color
+            xml.sz(:val=>@sz) if @sz
+            xml.u(:val=>@u) if @u
+            # :baseline, :subscript, :superscript
+            xml.vertAlign(:val=>@vertAlign) if @vertAlign
+            # :none, major, :minor
+            xml.scheme(:val=>@scheme) if @scheme
+          }
+          xml.t @value.to_s
+        }
+      else
+        xml.t @value.to_s
+      end
+    end
 
     # Serializes the cell
     # @param [Nokogiri::XML::Builder] xml The document builder instance this objects xml will be added to.
     # @return [String] xml text for the cell
-    # @note
-    #   Shared Strings are not used in this library. All values are set directly in the each sheet.
     def to_xml(xml)
-      
-      # however nokogiri does a nice 'force_encoding' which we shall remove!
-      if @type == :string 
+      if @type == :string
         #parse formula
         if @value.start_with?('=')
           xml.c(:r => r, :t=>:str, :s=>style) {
             xml.f @value.to_s.gsub('=', '')
           }
         else
-          #parse standard string
-          #xml.c(:r => r, :t=>:inlineStr, :s=>style) {
-          #  xml.is { xml.t @value.to_s } 
-          #}
-          #parse styled string
-          xml.c(:r => r, :s=>style, :t => :inlineStr) {
-            xml.is {
-              xml.r {
-                xml.rPr {
-                  xml.rFont(:val=>@font_name) if @font_name
-                  xml.charset(:val=>@charset) if @charset
-                  xml.family(:val=>@family) if @family
-                  xml.b(:val=>@b) if @b
-                  xml.i(:val=>@i) if @i
-                  xml.strike(:val=>@strike) if @strike
-                  xml.outline(:val=>@outline) if @outline
-                  xml.shadow(:val=>@shadow) if @shadow
-                  xml.condense(:val=>@condense) if @condense
-                  xml.extend(:val=>@extend) if @extend
-                  @color.to_xml(xml) if @color
-                  xml.sz(:val=>@sz) if @sz
-                  xml.u(:val=>@u) if @u
-                  # :baseline, :subscript, :superscript
-                  xml.vertAlign(:val=>@vertAlign) if @verAlign
-                  # :none, major, :minor
-                  xml.scheme(:val=>@scheme) if @scheme
-                }
-                xml.t @value.to_s
+          #parse shared
+          if @ssti
+            xml.c(:r => r, :s=>style, :t => :s) { xml.v ssti }
+          else
+            #parse inline string
+            xml.c(:r => r, :s=>style, :t => :inlineStr) {
+              xml.is {
+                run_xml(xml)
               }
             }
-          }
+          end
         end
+      elsif @type == :date
+        # TODO: See if this is subject to the same restriction as Time below
+        v = DateTimeConverter::date_to_serial @value
+        xml.c(:r => r, :s => style) { xml.v v }
       elsif @type == :time
-        # Using hardcoded offsets here as some operating systems will not except a 'negative' offset from the ruby epoc.
-        # (1970)
-        epoc1900 = -2209021200 #Time.local(1900, 1, 1) 
-        epoc1904 = -2082877200 #Time.local(1904, 1, 1) 
-        epoc = Workbook.date1904 ? epoc1904 : epoc1900
-        v = ((@value.localtime.to_f - epoc) /60.0/60.0/24.0).to_f
+        v = DateTimeConverter::time_to_serial @value
         xml.c(:r => r, :s => style) { xml.v v }
+      elsif @type == :boolean
+        xml.c(:r => r, :s => style, :t => :b) { xml.v value }
       else
         xml.c(:r => r, :s => style) { xml.v value }
       end
     end
 
+    private
 
-    private 
+    # @see ssti
+    def ssti=(v)
+      Axlsx::validate_unsigned_int(v)
+      @ssti = v
+    end
 
     # assigns the owning row for this cell.
     def row=(v) DataTypeValidator.validate "Cell.row", Row, v; @row=v end
-    
+
     # converts the column index into alphabetical values.
     # @note This follows the standard spreadsheet convention of naming columns A to Z, followed by AA to AZ etc.
     # @return [String]
@@ -311,15 +353,21 @@ module Axlsx
       chars.reverse.join
     end
 
-    # Determines the cell type based on the cell value. 
+    # Determines the cell type based on the cell value.
     # @note This is only used when a cell is created but no :type option is specified, the following rules apply:
-    #   1. If the value is an instance of Time, the type is set to :time
-    #   2. :float and :integer types are determined by regular expression matching.
-    #   3. Anything that does not meet either of the above is determined to be :string.
+    #   1. If the value is an instance of Date, the type is set to :date
+    #   2. If the value is an instance of Time, the type is set to :time
+    #   3. If the value is an instance of TrueClass or FalseClass, the type is set to :boolean
+    #   4. :float and :integer types are determined by regular expression matching.
+    #   5. Anything that does not meet either of the above is determined to be :string.
     # @return [Symbol] The determined type
-    def cell_type_from_value(v)      
-      if v.is_a? Time
+    def cell_type_from_value(v)
+      if v.is_a?(Date)
+        :date
+      elsif v.is_a?(Time)
         :time
+      elsif v.is_a?(TrueClass) || v.is_a?(FalseClass)
+        :boolean
       elsif v.to_s.match(/\A[+-]?\d+?\Z/) #numeric
         :integer
       elsif v.to_s.match(/\A[+-]?\d+\.\d+?\Z/) #float
@@ -329,22 +377,27 @@ module Axlsx
       end
     end
 
-    # Cast the value into this cells data type. 
-    # @note 
+    # Cast the value into this cells data type.
+    # @note
     #   About Time - Time in OOXML is *different* from what you might expect. The history as to why is interesting,  but you can safely assume that if you are generating docs on a mac, you will want to specify Workbook.1904 as true when using time typed values.
     # @see Axlsx#date1904
     def cast_value(v)
-      if (@type == :time && v.is_a?(Time)) || (@type == :time && v.respond_to?(:to_time))
+      if @type == :date
+        self.style = STYLE_DATE if self.style == 0
+        v
+      elsif (@type == :time && v.is_a?(Time)) || (@type == :time && v.respond_to?(:to_time))
         self.style = STYLE_DATE if self.style == 0
         v.respond_to?(:to_time) ? v.to_time : v
       elsif @type == :float
         v.to_f
       elsif @type == :integer
         v.to_i
+      elsif @type == :boolean
+        v ? 1 : 0
       else
         @type = :string
         v.to_s
       end
-    end    
+    end
   end
 end

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

@@ -0,0 +1,29 @@
+# encoding: UTF-8
+require "date"
+
+module Axlsx
+  # The DateTimeConverter class converts both data and time types to their apprpriate excel serializations
+  class DateTimeConverter
+
+    # The date_to_serial method converts Date objects to the equivelant excel serialized forms
+    # @param [Date] date the date to be serialized
+    # @return [Numeric]
+    def self.date_to_serial(date)
+      epoch = Axlsx::Workbook::date1904 ? Date.new(1904) : Date.new(1899, 12, 30)
+      (date-epoch).to_f
+    end
+
+    # The time_to_serial methond converts a Time object its excel serialized form.
+    # @param [Time] time the time to be serialized
+    # @return [Numeric]
+    def self.time_to_serial(time)
+      # Using hardcoded offsets here as some operating systems will not except
+      # a 'negative' offset from the ruby epoch.
+      epoch1900 = -2209161600 # Time.utc(1899, 12, 30).to_i
+      epoch1904 = -2082844800 # Time.utc(1904, 1, 1).to_i
+      seconds_per_day = 86400 # 60*60*24
+      epoch = Axlsx::Workbook::date1904 ? epoch1904 : epoch1900
+      (time.to_f - epoch)/seconds_per_day
+    end
+  end
+end

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

@@ -0,0 +1,94 @@
+module Axlsx
+  # PageMargins specify the margins when printing a worksheet.
+  #
+  # For compatibility, PageMargins serialize to an empty string, unless at least one custom margin value
+  # has been specified. Otherwise, it serializes to a PageMargin element specifying all 6 margin values
+  # (using default values for margins that have not been specified explicitly).
+  #
+  # @note The recommended way to manage page margins is via Worksheet#page_margins
+  # @see Worksheet#page_margins
+  # @see Worksheet#initialize
+  class PageMargins
+
+    # Default left and right margin (in inches)
+    DEFAULT_LEFT_RIGHT = 0.75
+    
+    # Default top and bottom margins (in inches)
+    DEFAULT_TOP_BOTTOM = 1.00
+    
+    # Default header and footer margins (in inches)
+    DEFAULT_HEADER_FOOTER = 0.50
+    
+    # Left margin (in inches)
+    # @return [Float]
+    attr_reader :left
+
+    # Right margin (in inches)
+    # @return [Float]
+    attr_reader :right
+    
+    # Top margin (in inches)
+    # @return [Float]
+    attr_reader :top
+    
+    # Bottom margin (in inches)
+    # @return [Float]
+    attr_reader :bottom
+    
+    # Header margin (in inches)
+    # @return [Float]
+    attr_reader :header
+    
+    # Footer margin (in inches)
+    # @return [Float]
+    attr_reader :footer
+    
+    # Creates a new PageMargins object
+    # @option options [Numeric] left The left margin in inches
+    # @option options [Numeric] right The right margin in inches
+    # @option options [Numeric] bottom The bottom margin in inches
+    # @option options [Numeric] top The top margin in inches
+    # @option options [Numeric] header The header margin in inches
+    # @option options [Numeric] footer The footer margin in inches
+    def initialize(options={})
+      # Default values taken from MS Excel for Mac 2011
+      @left = @right = DEFAULT_LEFT_RIGHT
+      @top = @bottom = DEFAULT_TOP_BOTTOM
+      @header = @footer = DEFAULT_HEADER_FOOTER
+
+      options.each do |o|
+        self.send("#{o[0]}=", o[1]) if self.respond_to? "#{o[0]}="
+      end
+    end
+    
+    # Set some or all margins at once.
+    # @param [Hash] margins the margins to set (possible keys are :left, :right, :top, :bottom, :header and :footer).
+    def set(margins)
+      margins.select do |k, v|
+        next unless [:left, :right, :top, :bottom, :header, :footer].include? k
+        send("#{k}=", v)
+      end
+    end
+    
+    # @see left
+    def left=(v); Axlsx::validate_unsigned_numeric(v); @left = v end
+    # @see right
+    def right=(v); Axlsx::validate_unsigned_numeric(v); @right = v end
+    # @see top
+    def top=(v); Axlsx::validate_unsigned_numeric(v); @top = v end
+    # @see bottom
+    def bottom=(v); Axlsx::validate_unsigned_numeric(v); @bottom = v end
+    # @see header
+    def header=(v); Axlsx::validate_unsigned_numeric(v); @header = v end
+    # @see footer
+    def footer=(v); Axlsx::validate_unsigned_numeric(v); @footer = v end
+
+    # Serializes the page margins element
+    # @note For compatibility, this is a noop unless custom margins have been specified.
+    # @param [Nokogiri::XML::Builder] xml The document builder instance this objects xml will be added to.
+    # @see #custom_margins_specified?
+    def to_xml(xml)
+      xml.pageMargins :left => left, :right => right, :top => top, :bottom => bottom, :header => header, :footer => footer
+    end
+  end
+end

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

@@ -1,3 +1,4 @@
+# encoding: UTF-8
 module Axlsx
   # A Row is a single row in a worksheet.
   # @note The recommended way to manage rows and cells is to use Worksheet#add_row
@@ -12,6 +13,22 @@ module Axlsx
     # @return [SimpleTypedList]
     attr_reader :cells
 
+    # The height of this row in points, if set explicitly.
+    # @return [Float]
+    attr_reader :height
+
+    # TODO  18.3.1.73
+    # collapsed
+    # customFormat
+    # hidden
+    # outlineLevel
+    # ph
+    # s (style)
+    # spans
+    # thickTop
+    # thickBottom
+
+
     # Creates a new row. New Cell objects are created based on the values, types and style options.
     # A new cell is created for each item in the values array. style and types options are applied as follows:
     #   If the types option is defined and is a symbol it is applied to all the cells created.
@@ -22,28 +39,33 @@ module Axlsx
     #   If the style option is not defined, the default style (0) is applied to each cell.
     # @param [Worksheet] worksheet
     # @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 [Float] height the row's height (in points)
     # @see Row#array_to_cells
     # @see Cell
     def initialize(worksheet, values=[], options={})
+      @height = nil
       self.worksheet = worksheet
       @cells = SimpleTypedList.new Cell
       @worksheet.rows << self
+      self.height = options.delete(:height) if options[:height]
       array_to_cells(values, options)
     end
 
     # The index of this row in the worksheet
     # @return [Integer]
-    def index 
+    def index
       worksheet.rows.index(self)
     end
-    
+
     # Serializes the row
     # @param [Nokogiri::XML::Builder] xml The document builder instance this objects xml will be added to.
     # @return [String]
     def to_xml(xml)
-      xml.row(:r => index+1) { @cells.each { |cell| cell.to_xml(xml) } }
+      attrs = {:r => index+1}
+      attrs.merge!(:customHeight => 1, :ht => height) if custom_height?
+      xml.row(attrs) { |ixml| @cells.each { |cell| cell.to_xml(ixml) } }
     end
 
     # Adds a singel sell to the row based on the data provided and updates the worksheet's autofit data.
@@ -53,7 +75,7 @@ module Axlsx
       update_auto_fit_data
       c
     end
-    
+
     # sets the style for every cell in this row
     def style=(style)
       cells.each_with_index do | cell, index |
@@ -63,17 +85,27 @@ module Axlsx
     end
 
     # returns the cells in this row as an array
-    # This lets us transpose the rows into columns 
+    # This lets us transpose the rows into columns
     # @return [Array]
     def to_ary
       @cells.to_ary
     end
 
+    # @see height
+    def height=(v); Axlsx::validate_unsigned_numeric(v) unless v.nil?; @height = v end
+
+    # true if the row height has been manually set
+    # @return [Boolean]
+    # @see #height
+    def custom_height?
+      @height != nil
+    end
+
     private
 
     # assigns the owning worksheet for this row
     def worksheet=(v) DataTypeValidator.validate "Row.worksheet", Worksheet, v; @worksheet=v; end
-    
+
     # Tell the worksheet to update autofit data for the columns based on this row's cells.
     # @return [SimpleTypedList]
     def update_auto_fit_data
@@ -88,13 +120,13 @@ module Axlsx
     # If the style option is defined and is an Integer, it is applied to all cells created.
     # If the style option is an array, style is applied by index for each cell.
     # @option options [Array] values
-    # @option options [Array, Symbol] types 
-    # @option options [Array, Integer] style 
+    # @option options [Array, Symbol] types
+    # @option options [Array, Integer] style
     def array_to_cells(values, options={})
       values = values
       DataTypeValidator.validate 'Row.array_to_cells', Array, values
       types, style = options.delete(:types), options.delete(:style)
-      values.each_with_index do |value, index|        
+      values.each_with_index do |value, index|
         cell_style = style.is_a?(Array) ? style[index] : style
         options[:style] = cell_style if cell_style
         cell_type = types.is_a?(Array)? types[index] : types
@@ -103,5 +135,5 @@ module Axlsx
       end
     end
   end
-  
+
 end