axlsx 1.1.0 → 1.2.0

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

@@ -3,22 +3,6 @@ require 'cgi'
 module Axlsx
   # 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
-  #   # 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
@@ -74,13 +58,20 @@ module Axlsx
       @value = cast_value(v)
     end
 
-
     # Indicates that the cell has one or more of the custom cell styles applied.
     # @return [Boolean]
     def is_text_run?
       @is_text_run ||= false
     end
 
+    # Indicates if the cell is good for shared string table
+    def plain_string?
+      @type == :string &&         # String typed
+        !is_text_run? &&          # No inline styles
+        !@value.nil? &&           # Not nil
+        !@value.empty? &&         # Not empty
+        !@value.start_with?('=')  # Not a formula
+    end
 
     # The inline font_name property for the cell
     # @return [String]
@@ -151,10 +142,10 @@ module Axlsx
     # The inline color property for the cell
     # @return [Color]
     attr_reader :color
-    # @param [String] The 8 character representation for an rgb color #FFFFFFFF"
+    # @param [String] v The 8 character representation for an rgb color #FFFFFFFF"
     def color=(v)
       @color = v.is_a?(Color) ? v : Color.new(:rgb=>v)
-      @has_run_style = true
+      @is_text_run = true
     end
 
     # The inline sz property for the cell
@@ -204,7 +195,7 @@ module Axlsx
     # @option options [Symbol] scheme must be one of :none, major, :minor
     def initialize(row, value="", options={})
       self.row=row
-      @font_name = @charset = @family = @b = @i = @strike = @outline = @shadow = nil
+      @value = @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
@@ -220,15 +211,6 @@ module Axlsx
     # @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_hash
-      self_hash = {}
-      INLINE_STYLES.each { |style| self_hash[style] = self.instance_variable_get("@" + style) }
-      self_hash['color'] = self_hash['color'].instance_values if self_hash['color']
-      self_hash
-    end
-
     # @return [Integer] The index of the cell in the containing row.
     def index
       @row.cells.index(self)
@@ -237,9 +219,8 @@ module Axlsx
     # @return [String] The alpha(column)numeric(row) reference for this sell.
     # @example Relative Cell Reference
     #   ws.rows.first.cells.first.r #=> "A1"
-    # @note this will be discontinued in 1.1.0 -  prefer Axlsx.cell_r
     def r
-      "#{Axlsx::col_ref(index)}#{@row.index+1}"
+      Axlsx::cell_r index, @row.index
     end
 
     # @return [String] The absolute alpha(column)numeric(row) reference for this sell.
@@ -280,9 +261,8 @@ module Axlsx
     # @return [String]
     def run_xml_string(str = '')
       if is_text_run?
-        data = self.instance_values.reject{|key, value| value == nil }
+        data = instance_values.reject{|key, value| value == nil || key == 'value' || key == 'type' }
         keys = data.keys & INLINE_STYLES
-        keys.delete ['value', 'type']
         str << "<r><rPr>"
         keys.each do |key|
           case key
@@ -291,7 +271,7 @@ module Axlsx
           when 'color'
             str << data[key].to_xml_string
           else
-            "<" << key.to_s << " val='" << data[key].to_s << "'/>"
+            str << "<" << key.to_s << " val='" << data[key].to_s << "'/>"
           end
         end
         str << "</rPr>" << "<t>" << value.to_s << "</t></r>"
@@ -307,13 +287,15 @@ module Axlsx
     # @param [String] str The string index the cell content will be appended to. Defaults to empty string.
     # @return [String] xml text for the cell
     def to_xml_string(r_index, c_index, str = '')
-      return str if @value.nil?
       str << '<c r="' << Axlsx::cell_r(c_index, r_index) << '" s="' << @style.to_s << '" '
+      return str << '/>' if @value.nil?
+
       case @type
+
       when :string
         #parse formula
         if @value.start_with?('=')
-          str  << 't="str"><f>' << @value.to_s.gsub('=', '') << '</f>'
+          str  << 't="str"><f>' << @value.to_s.sub('=', '') << '</f>'
         else
           #parse shared
           if @ssti
@@ -335,8 +317,35 @@ module Axlsx
       str << '</c>'
     end
 
+    def is_formula?
+      @type == :string && @value.to_s.start_with?('=')
+    end
+
+    # This is still not perfect...
+    #  - scaling is not linear as font sizes increst
+    #  - different fonts have different mdw and char widths
+    def autowidth
+      return if is_formula? || value == nil
+      mdw = 1.78 #This is the widest width of 0..9 in arial@10px)
+      font_scale = (font_size/10.0).to_f
+      ((value.to_s.count(Worksheet.thin_chars) * mdw + 5) / mdw * 256) / 256.0 * font_scale
+    end
+   
+    # returns the absolute or relative string style reference for
+    # this cell. 
+    # @param [Boolean] absolute -when false a relative reference will be
+    # returned. 
+    # @return [String]
+    def reference(absolute=true)
+      absolute ? r_abs : r
+    end 
+    
     private
 
+    def font_size
+        sz || @styles.fonts[@styles.cellXfs[style].fontId].sz
+    end
+
     # Utility method for setting inline style attributes
     def set_run_style( validator, attr, value)
       return unless INLINE_STYLES.include?(attr.to_s)

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

@@ -0,0 +1,62 @@
+module Axlsx
+  # Conditional Format Value Object
+  # Describes the values of the interpolation points in a gradient scale. This object is used by ColorScale, DataBar and IconSet classes
+  #
+  # @note The recommended way to manage these rules is via Worksheet#add_conditional_formatting
+  # @see Worksheet#add_conditional_formatting
+  # @see ConditionalFormattingRule#initialize
+  #
+  class Cfvo
+
+    # Type (ST_CfvoType)
+    # The type of this conditional formatting value object. options are num, percent, max, min, formula and percentile
+    # @return [Symbol]
+    attr_reader :type
+
+
+    # Type (xsd:boolean)
+    # For icon sets, determines whether this threshold value uses the greater than or equal to operator. 0 indicates 'greater than' is used instead of 'greater than or equal to'.
+    # The default value is true
+    # @return [Boolean]
+    attr_reader :gte
+
+
+    # Type (ST_Xstring)
+    # The value of the conditional formatting object
+    # This library will accept any value so long as it supports to_s
+    attr_reader :val
+
+    # Creates a new Cfvo object
+    # @option options [Symbol] type The type of conditional formatting value object
+    # @option options [Boolean]  gte threshold value usage indicator
+    # @option options [String] val The value of the conditional formatting object
+    def initialize(options={})
+      @gte = true
+      options.each do |o|
+        self.send("#{o[0]}=", o[1]) if self.respond_to? "#{o[0]}="
+      end
+    end
+
+    # @see type
+    def type=(v); Axlsx::validate_conditional_formatting_value_object_type(v); @type = v end
+
+    # @see gte
+    def gte=(v); Axlsx::validate_boolean(v); @gte = v end
+
+    # @see val
+    def val=(v)
+      raise ArgumentError, "#{v.inspect} must respond to to_s" unless v.respond_to?(:to_s)
+      @val = v.to_s
+    end
+
+    # serialize the Csvo object
+    # @param [String] str
+    # @return [String]
+    def to_xml_string(str = '')
+      str << '<cfvo '
+      str << instance_values.map { |key, value| '' << key << '="' << value.to_s << '"' }.join(' ')
+      str << ' />'
+    end
+
+  end
+end

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

@@ -60,7 +60,8 @@ module Axlsx
 
     # @see Col#outline
     def outlineLevel=(v)
-      Axlsx.validate_boolean(v)
+      Axlsx.validate_unsigned_numeric(v)
+      raise ArgumentError, 'outlineLevel must be between 0 and 7' unless 0 <= v && v <= 7
       @outlineLevel = v
     end
 
@@ -101,6 +102,21 @@ module Axlsx
         self.send("#{o[0]}=", o[1]) if self.respond_to? "#{o[0]}="
       end
     end
+    
+    # updates the width for this col based on the cells autowidth and 
+    # an optionally specified fixed width
+    # @param [Cell] cell The cell to use in updating this col's width
+    # @param [Integer] fixed_width If this is specified the width is set
+    # to this value and the cell's attributes are ignored.
+    # @param [Boolean] use_autowidth If this is false, the cell's
+    # autowidth value will be ignored.
+    def update_width(cell, fixed_width=nil, use_autowidth=true)
+       if fixed_width.is_a? Numeric
+         self.width = fixed_width
+       elsif use_autowidth
+        self.width = [width || 0, cell.autowidth || 0].max
+       end 
+    end 
 
     # Serialize this columns data to an xml string
     # @param [String] str

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

@@ -0,0 +1,76 @@
+module Axlsx
+  # Conditional Format Rule color scale object
+  # Describes a gradated color scale in this conditional formatting rule.
+
+  # @note The recommended way to manage these rules is via Worksheet#add_conditional_formatting
+  # @see Worksheet#add_conditional_formatting
+  # @see ConditionalFormattingRule#initialize
+  class ColorScale
+
+    # A simple typed list of cfvos
+    # @return [SimpleTypedList]
+    # @see Cfvo
+    attr_reader :value_objects
+
+    # A simple types list of colors
+    # @return [SimpleTypedList]
+    # @see Color
+    attr_reader :colors
+
+    # creates a new ColorScale object.
+    # This method will yield it self so you can alter the properites of the defauls conditional formating value object (cfvo and colors
+    # Two value objects and two colors are created on initialization and cannot be deleted.
+    # @see Cfvo
+    # @see Color
+    def initialize
+      initialize_value_objects
+      initialize_colors
+      yield self if block_given?
+    end
+
+    # adds a new cfvo / color pair to the color scale and returns a hash containing
+    # a reference to the newly created cfvo and color objects so you can alter the default properties.
+    # @return [Hash] a hash with :cfvo and :color keys referencing the newly added objects.
+    def add(options={})
+      @value_objects << Cfvo.new(:type => options[:type] || :min, :val => options[:val] || 0)
+      @colors << Color.new(:rgb => options[:color] || "FF000000")
+      {:cfvo => @value_objects.last, :color => @colors.last}
+    end
+
+
+    # removes the cfvo and color pair at the index specified.
+    # @param [Integer] index The index of the cfvo and color object to delete
+    # @note you cannot remove the first two cfvo and color pairs
+    def delete_at(index=2)
+      @value_objects.delete_at index
+      @colors.delete_at index
+    end
+
+    # Serialize this color_scale object data to an xml string
+    # @param [String] str
+    # @return [String]
+    def to_xml_string(str = '')
+      str << '<colorScale>'
+      @value_objects.each { |cfvo| cfvo.to_xml_string(str) }
+      @colors.each { |color| color.to_xml_string(str) }
+      str << '</colorScale>'
+    end
+
+    private
+
+    # creates the initial cfvo objects
+    def initialize_value_objects
+      @value_objects = SimpleTypedList.new Cfvo
+      @value_objects.concat [Cfvo.new(:type => :min, :val => 0), Cfvo.new(:type => :max, :val => 0)]
+      @value_objects.lock
+    end
+
+    # creates the initial color objects
+    def initialize_colors
+      @colors = SimpleTypedList.new Color
+      @colors.concat [Color.new(:rgb => "FFFF0000"), Color.new(:rgb => "FF0000FF")]
+      @colors.lock
+    end
+
+  end
+end

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

@@ -0,0 +1,20 @@
+module Axlsx
+
+  # The cols class manages the col object used to manage column widths. 
+  # This is where the magic happens with autowidth
+  class Cols < SimpleTypedList
+
+    def initialize(worksheet)
+      raise ArgumentError, "you must provide a worksheet" unless worksheet.is_a?(Worksheet)
+      super Col
+      @worksheet = worksheet
+    end
+
+    def to_xml_string(str = '')
+     return if empty?
+     str << '<cols>'
+     each { |item| item.to_xml_string(str) }
+     str << '</cols>' 
+    end
+  end
+end

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

@@ -0,0 +1,101 @@
+module Axlsx
+
+  # A comment is the text data for a comment
+  class Comment
+
+    # The text to render
+    # @return [String]
+    attr_reader :text
+
+    # The author of this comment
+    # @see Comments
+    # @return [String]
+    attr_reader :author
+
+    # The owning Comments object
+    # @return [Comments]
+    attr_reader :comments
+
+
+    # The string based cell position reference (e.g. 'A1') that determines the positioning of this comment
+    # @return [String]
+    attr_reader :ref
+
+    # TODO
+    # r (Rich Text Run)
+    # rPh (Phonetic Text Run)
+    # phoneticPr (Phonetic Properties)
+
+    def initialize(comments, options={})
+      raise ArgumentError, "A comment needs a parent comments object" unless comments.is_a?(Comments)
+      @comments = comments
+      options.each do |o|
+        self.send("#{o[0]}=", o[1]) if self.respond_to? "#{o[0]}="
+      end
+      yield self if block_given?
+    end
+
+    # The vml shape that will render this comment
+    # @return [VmlShape]
+    def vml_shape
+      @vml_shape ||= initialize_vml_shape
+    end
+
+    #
+    # The index of this author in a unique sorted list of all authors in
+    # the comment.
+    # @return [Integer]
+    def author_index
+      @comments.authors.index(author)
+    end
+
+    # @see ref
+    def ref=(v)
+      Axlsx::DataTypeValidator.validate "Comment.ref", [String, Cell], v
+      @ref = v if v.is_a?(String)
+      @ref = v.r if v.is_a?(Cell)
+    end
+
+    # @see text
+    def text=(v)
+      Axlsx::validate_string(v)
+      @text = v
+    end
+
+    # @see author
+    def author=(v)
+      @author = v
+    end
+
+    # serialize the object
+    # @param [String] str
+    # @return [String]
+    def to_xml_string(str = "")
+      author = @comments.authors[author_index]
+      str << '<comment ref="' << ref << '" authorId="' << author_index.to_s << '">'
+      str << '<text><r>'
+      str << '<rPr> <b/><color indexed="81"/></rPr>'
+      str << '<t>' << author.to_s << ':
+</t></r>'
+      str << '<r>'
+      str << '<rPr><color indexed="81"/></rPr>'
+      str << '<t>' << text << '</t></r></text>'
+      str << '</comment>'
+    end
+
+    private
+
+    # initialize the vml shape based on this comment's ref/position in the worksheet.
+    # by default, all columns are 5 columns wide and 5 rows high
+    def initialize_vml_shape
+      pos = Axlsx::name_to_indices(ref)
+      @vml_shape = VmlShape.new(:row => pos[1], :column => pos[0]) do |vml|
+        vml.left_column = vml.column
+        vml.right_column = vml.column + 2 
+        vml.top_row = vml.row
+         vml.bottom_row = vml.row + 4
+      end
+    end
+
+  end
+end

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

@@ -0,0 +1,85 @@
+# -*- coding: utf-8 -*-
+module Axlsx
+
+  # Comments is a collection of Comment objects for a worksheet
+  class Comments < SimpleTypedList
+
+    # the vml_drawing that holds the shapes for comments
+    # @return [VmlDrawing]
+    attr_reader :vml_drawing
+
+    # The worksheet that these comments belong to
+    # @return [Worksheet]
+    attr_reader :worksheet
+
+    # The index of this collection in the workbook. Effectively the index of the worksheet.
+    # @return [Integer]
+    def index
+      @worksheet.index
+    end
+
+    # The part name for this object
+    # @return [String]
+    def pn
+      "#{COMMENT_PN % (index+1)}"
+    end
+
+    # Creates a new Comments object
+    # @param [Worksheet] worksheet The sheet that these comments belong to.
+    def initialize(worksheet)
+      raise ArgumentError, "you must provide a worksheet" unless worksheet.is_a?(Worksheet)
+      super(Comment)
+      @worksheet = worksheet
+      @vml_drawing = VmlDrawing.new(self)
+    end
+
+    # Adds a new comment to the worksheet that owns these comments.
+    # @note the author, text and ref options are required
+    # @option options [String] author The name of the author for this comment
+    # @option options [String] text The text for this comment
+    # @option options [Stirng|Cell] ref The cell that this comment is attached to.
+    def add_comment(options={})
+      raise ArgumentError, "Comment require an author" unless options[:author]
+      raise ArgumentError, "Comment requires text" unless options[:text]
+      raise ArgumentError, "Comment requires ref" unless options[:ref]
+      @list << Comment.new(self, options)
+      yield @list.last if block_given?
+      @list.last
+    end
+
+    # A sorted list of the unique authors in the contained comments
+    # @return [Array]
+    def authors
+      @list.map { |comment| comment.author.to_s }.uniq.sort
+    end
+
+    # The relationships required by this object
+    # @return [Array]
+    def relationships
+      [Relationship.new(VML_DRAWING_R, "../#{vml_drawing.pn}"),
+       Relationship.new(COMMENT_R, "../#{pn}"),
+       Relationship.new(COMMENT_R_NULL, "NULL")]
+    end
+
+    # serialize the object
+    # @param [String] str
+    # @return [String]
+    def to_xml_string(str="")
+      str << '<?xml version="1.0" encoding="UTF-8"?>'
+      str << '<comments xmlns="' << XML_NS << '">'
+      str << '<authors>'
+      authors.each do  |author|
+        str << '<author>' << author.to_s << '</author>'
+      end
+      str << '</authors>'
+      str << '<commentList>'
+      @list.each do |comment|
+        comment.to_xml_string str
+      end
+      str << '</commentList></comments>'
+
+    end
+
+  end
+
+end

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

@@ -0,0 +1,82 @@
+module Axlsx
+  # Conditional formatting allows styling of ranges based on functions
+  #
+  # @note The recommended way to manage conditional formatting is via Worksheet#add_conditional_formatting
+  # @see Worksheet#add_conditional_formatting
+  # @see ConditionalFormattingRule
+  class ConditionalFormatting
+
+    # Range over which the formatting is applied, in "A1:B2" format
+    # @return [String]
+    attr_reader :sqref
+
+    # Rules to apply the formatting to. Can be either a hash of
+    # options to create a {ConditionalFormattingRule}, an array of hashes
+    # for multiple ConditionalFormattingRules, or an array of already
+    # created ConditionalFormattingRules.
+    # @see ConditionalFormattingRule#initialize
+    # @return [Array]
+    attr_reader :rules
+
+    # Creates a new {ConditionalFormatting} object
+    # @option options [Array] rules The rules to apply
+    # @option options [String] sqref The range to apply the rules to
+    def initialize(options={})
+      @rules = []
+      options.each do |o|
+        self.send("#{o[0]}=", o[1]) if self.respond_to? "#{o[0]}="
+      end
+    end
+
+    # Add Conditional Formatting Rules to this object. Rules can either
+    # be already created {ConditionalFormattingRule} elements or
+    # hashes of options for automatic creation.  If rules is a hash
+    # instead of an array, assume only one rule being added.
+    #
+    # @example This would apply formatting "1" to cells > 20, and formatting "2" to cells < 1
+    #        conditional_formatting.add_rules [
+    #            { :type => :cellIs, :operator => :greaterThan, :formula => "20", :dxfId => 1, :priority=> 1 },
+    #            { :type => :cellIs, :operator => :lessThan, :formula => "10", :dxfId => 2, :priority=> 2 } ]
+    #
+    # @param [Array|Hash] rules the rules to apply, can be just one in hash form
+    # @see ConditionalFormattingRule#initialize
+    def add_rules(rules)
+      rules = [rules] if rules.is_a? Hash
+      rules.each do |rule|
+        add_rule rule
+      end
+    end
+
+    # Add a ConditionalFormattingRule. If a hash of options is passed
+    # in create a rule on the fly.
+    # @param [ConditionalFormattingRule|Hash] rule A rule to use, or the options necessary to create one.
+    # @see ConditionalFormattingRule#initialize
+    def add_rule(rule)
+      if rule.is_a? Axlsx::ConditionalFormattingRule
+        @rules << rule
+      elsif rule.is_a? Hash
+        @rules << ConditionalFormattingRule.new(rule)
+      end
+    end
+
+    # @see rules
+    def rules=(v); @rules = v end
+    # @see sqref
+    def sqref=(v); Axlsx::validate_string(v); @sqref = v end
+
+    # Serializes the conditional formatting element
+    # @example Conditional Formatting XML looks like:
+    #    <conditionalFormatting sqref="E3:E9">
+    #        <cfRule type="cellIs" dxfId="0" priority="1" operator="greaterThan">
+    #             <formula>0.5</formula>
+    #        </cfRule>
+    #    </conditionalFormatting>
+    # @param [String] str
+    # @return [String]
+    def to_xml_string(str = '')
+      str << '<conditionalFormatting sqref="' << sqref << '">'
+      str << rules.collect{ |rule| rule.to_xml_string }.join(' ')
+      str << '</conditionalFormatting>'
+    end
+  end
+end