axlsx 1.3.3 → 1.3.4

data/lib/axlsx/util/validators.rb

@@ -145,6 +145,7 @@ module Axlsx
     RestrictionValidator.validate "cell run style u", [:none, :single, :double, :singleAccounting, :doubleAccounting], v
   end
 
+  # validates cell style family which must be between 1 and 5 
   def self.validate_family(v)
     RestrictionValidator.validate "cell run style family", 1..5, v
   end

data/lib/axlsx/version.rb

@@ -1,5 +1,5 @@
 module Axlsx
 
   # The current version
-  VERSION = "1.3.3"
+  VERSION = "1.3.4"
 end

data/lib/axlsx/workbook/workbook.rb

@@ -9,6 +9,7 @@ require 'axlsx/workbook/worksheet/cell.rb'
 require 'axlsx/workbook/worksheet/page_margins.rb'
 require 'axlsx/workbook/worksheet/page_set_up_pr.rb'
 require 'axlsx/workbook/worksheet/page_setup.rb'
+require 'axlsx/workbook/worksheet/header_footer.rb'
 require 'axlsx/workbook/worksheet/print_options.rb'
 require 'axlsx/workbook/worksheet/cfvo.rb'
 require 'axlsx/workbook/worksheet/cfvos.rb'

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

@@ -398,8 +398,8 @@ module Axlsx
     end
 
     # assigns the owning row for this cell.
-    def row=(v) DataTypeValidator.validate "Cell.row", Row, v; @row=v end
-
+    def row=(v) @row=v end
+    
     # 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 Date, the type is set to :date
@@ -444,6 +444,9 @@ module Axlsx
         v ? 1 : 0
       else
         @type = :string
+        v.to_s
+        # TODO find a better way to do this as it accounts for 30% of
+        # processing time in benchmarking...
         ::CGI.escapeHTML(v.to_s)
       end
     end

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

@@ -6,9 +6,6 @@ module Axlsx
 
     def initialize
       super(Cfvo)
-      @list << Cfvo.new(:type => :min, :val => 0)
-      @list << Cfvo.new(:type => :max, :val => 0)
-      lock
     end
 
     def to_xml_string(str='')

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

@@ -7,6 +7,35 @@ module Axlsx
   # @see ConditionalFormattingRule#initialize
   class ColorScale
 
+    class << self
+
+      # These are the default conditional formatting value objects
+      # that define a two tone color gradient.
+      def default_cfvos
+        [{:type => :min, :val => 0, :color => 'FFFF7128'},
+         {:type => :max, :val => 0, :color => 'FFFFEF9C'}]
+      end
+
+      # A builder for two tone color gradient
+      # @example
+      #   # this creates a two tone color scale
+      #   color_scale = Axlsx::ColorScale.two_tone
+      # @see examples/example.rb conditional formatting examples.
+      def two_tone
+        self.new
+      end
+
+      # A builder for three tone color gradient
+      # @example
+      #   #this creates a three tone color scale
+      #   color_scale = Axlsx::ColorScale.three_tone 
+      # @see examples/example.rb conditional formatting examples.
+      def three_tone
+        self.new({:type => :min, :val => 0, :color => 'FFF8696B'},
+                 {:type => :percent, :val => '50', :color => 'FFFFEB84'},
+                 {:type => :max, :val => 0, :color => 'FF63BE7B'})
+      end
+    end
     # A simple typed list of cfvos
     # @return [SimpleTypedList]
     # @see Cfvo
@@ -17,25 +46,31 @@ module Axlsx
     # A simple types list of colors
     # @return [SimpleTypedList]
     # @see Color
-    attr_reader :colors
+    def colors
+      @colors ||= SimpleTypedList.new Color
+    end
 
     # 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_colors
+    # @example
+    #     color_scale = Axlsx::ColorScale.new({:type => :num, :val => 0.55, :color => 'fff7696c'})
+    def initialize(*cfvos)
+      initialize_default_cfvos(cfvos)
       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.
+    # @param [Hash] options options for the new cfvo and color objects
+    # @option [Symbol] type The type of cfvo you to add
+    # @option [Any] val The value of the cfvo to add
+    # @option [String] The rgb color for the cfvo
     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}
+      colors << Color.new(:rgb => options[:color] || "FF000000")
+      {:cfvo => value_objects.last, :color => colors.last}
     end
 
 
@@ -44,7 +79,7 @@ module Axlsx
     # @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
+      colors.delete_at index
     end
 
     # Serialize this color_scale object data to an xml string
@@ -53,18 +88,23 @@ module Axlsx
     def to_xml_string(str = '')
       str << '<colorScale>'
       value_objects.to_xml_string(str)
-      @colors.each { |color| color.to_xml_string(str) }
+      colors.each { |color| color.to_xml_string(str) }
       str << '</colorScale>'
     end
 
     private
-
-    # creates the initial color objects
-    def initialize_colors
-      @colors = SimpleTypedList.new Color
-      @colors.concat [Color.new(:rgb => "FFFF0000"), Color.new(:rgb => "FF0000FF")]
-      @colors.lock
+    # There has got to be cleaner way of merging these arrays.
+    def initialize_default_cfvos(user_cfvos)
+      defaults = self.class.default_cfvos
+      user_cfvos.each_with_index do |cfvo, index|
+        if index < defaults.size
+          cfvo = defaults[index].merge(cfvo)
+        end
+        add cfvo
+      end
+      while colors.size < defaults.size
+        add defaults[colors.size - 1]
+      end
     end
-
   end
 end

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

@@ -10,16 +10,27 @@ module Axlsx
     include Axlsx::OptionsParser
     include Axlsx::SerializedAttributes
 
+    class << self
+      # This differs from ColorScale. There must be exactly two cfvos one color
+      def default_cfvos
+        [{:type => :min, :val => "0"},
+         {:type => :max, :val => "0"}]
+      end
+    end
+
     # Creates a new data bar conditional formatting object
+    # @param [Hash] options
     # @option options [Integer] minLength
     # @option options [Integer] maxLength
     # @option options [Boolean] showValue
     # @option options [String] color - the rbg value used to color the bars
-    def initialize(options = {})
+    # @param [Array] cfvos hashes defining the gradient interpolation points for this formatting.
+    def initialize(options = {}, *cfvos)
       @min_length = 10
       @max_length = 90
       @show_value = true
       parse_options options
+      initialize_cfvos(cfvos)
       yield self if block_given?
     end
 
@@ -70,27 +81,27 @@ module Axlsx
     end
     alias :minLength= :min_length=
 
-    # @see maxLength
-    def max_length=(v)
-      Axlsx.validate_unsigned_int(v)
-      @max_length = v
-    end
+      # @see maxLength
+      def max_length=(v)
+        Axlsx.validate_unsigned_int(v)
+        @max_length = v
+      end
     alias :maxLength= :max_length=
 
-    # @see showValue
-    def show_value=(v)
-      Axlsx.validate_boolean(v)
-      @show_value = v
-    end
+      # @see showValue
+      def show_value=(v)
+        Axlsx.validate_boolean(v)
+        @show_value = v
+      end
     alias :showValue= :show_value=
 
-    # Sets the color for the data bars.
-    # @param [Color|String] v The color object, or rgb string value to apply
-    def color=(v)
-      @color = v if v.is_a? Color
-      self.color.rgb = v if v.is_a? String
-      @color
-    end
+      # Sets the color for the data bars.
+      # @param [Color|String] v The color object, or rgb string value to apply
+      def color=(v)
+        @color = v if v.is_a? Color
+        self.color.rgb = v if v.is_a? String
+        @color
+      end
 
     # Serialize this object to an xml string
     # @param [String] str
@@ -103,5 +114,18 @@ module Axlsx
       self.color.to_xml_string(str)
       str << '</dataBar>'
     end
+
+    private
+
+    def initialize_cfvos(cfvos)
+      self.class.default_cfvos.each_with_index.map do |default, index|
+        if index < cfvos.size
+          value_objects << Cfvo.new(default.merge(cfvos[index]))
+        else
+          value_objects << Cfvo.new(default)
+        end
+      end
+    end
+
   end
 end

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

@@ -0,0 +1,54 @@
+module Axlsx
+  # Header/Footer options for printing a worksheet. All settings are optional.
+  #
+  # Headers and footers are generated using a string which is a combination
+  # of plain text and control characters. A fairly comprehensive list of control
+  # characters can be found here:
+  # https://github.com/randym/axlsx/blob/master/notes_on_header_footer.md
+  #     
+  # @note The recommended way of managing header/footers is via Worksheet#header_footer
+  # @see Worksheet#initialize
+  class HeaderFooter
+
+    include Axlsx::OptionsParser
+    include Axlsx::SerializedAttributes
+    include Axlsx::Accessors
+
+    # Creates a new HeaderFooter object
+    # @option options [String] odd_header The content for headers on odd numbered pages.
+    # @option options [String] odd_footer The content for footers on odd numbered pages.
+    # @option options [String] even_header The content for headers on even numbered pages.
+    # @option options [String] even_footer The content for footers on even numbered pages.
+    # @option options [String] first_header The content for headers on even numbered pages.
+    # @option options [String] first_footer The content for footers on even numbered pages.
+    # @option options [Boolean] different_odd_even Setting this to true will show different headers/footers on odd and even pages. When false, the odd headers/footers are used on each page. (Default: false)
+    # @option options [Boolean] different_first If true, will use the first header/footer on page 1. Otherwise, the odd header/footer is used.
+    def initialize(options = {})
+      parse_options options
+    end
+
+    serializable_attributes :different_odd_even, :different_first
+    serializable_element_attributes :odd_header, :odd_footer, :even_header, :even_footer, :first_header, :first_footer
+    string_attr_accessor :odd_header, :odd_footer, :even_header, :even_footer, :first_header, :first_footer
+    boolean_attr_accessor :different_odd_even, :different_first
+
+    # Set some or all header/footers at once.
+    # @param [Hash] options The header/footer options to set (possible keys are :odd_header, :odd_footer, :even_header, :even_footer, :first_header, :first_footer, :different_odd_even, and :different_first).
+    def set(options)
+      parse_options options
+    end
+
+    # Serializes the header/footer object.
+    # @param [String] str
+    # @return [String]
+    def to_xml_string(str = '')
+      str << "<headerFooter "
+      serialized_attributes str
+      str << ">"
+      serialized_element_attributes(str) do |value|
+        value = ::CGI.escapeHTML(value)
+      end
+      str << "</headerFooter>"
+    end
+  end
+end

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

@@ -9,7 +9,8 @@ module Axlsx
     # This is used for autowidth calculations
     # @return [String]
     def self.thin_chars
-      @thin_chars ||= "^.acefijklrstxyzFIJL()-"
+      # removed 'e' and 'y' from this list - as a GUESS
+      @thin_chars ||= "^.acfijklrstxzFIJL()-"
     end
 
     # Creates a new worksheet.
@@ -18,6 +19,7 @@ module Axlsx
     # @option options [String] name The name of this worksheet.
     # @option options [Hash] page_margins A hash containing page margins for this worksheet. @see PageMargins
     # @option options [Hash] print_options A hash containing print options for this worksheet. @see PrintOptions
+    # @option options [Hash] header_footer A hash containing header/footer options for this worksheet. @see HeaderFooter
     # @option options [Boolean] show_gridlines indicates if gridlines should be shown for this sheet.
     def initialize(wb, options={})
       self.workbook = wb
@@ -34,6 +36,7 @@ module Axlsx
       @page_margins = PageMargins.new options[:page_margins] if options[:page_margins]
       @page_setup = PageSetup.new options[:page_setup]  if options[:page_setup]
       @print_options = PrintOptions.new options[:print_options] if options[:print_options]
+      @header_footer = HeaderFooter.new options[:header_footer] if options[:header_footer]
     end
 
     # The name of the worksheet
@@ -41,7 +44,7 @@ module Axlsx
     def name
       @name ||=  "Sheet" + (index+1).to_s
     end
- 
+
     # The sheet calculation properties
     # @return [SheetCalcPr]
     def sheet_calc_pr
@@ -104,7 +107,7 @@ module Axlsx
     # An range that excel will apply an autfilter to "A1:B3"
     # This will turn filtering on for the cells in the range.
     # The first row is considered the header, while subsequent rows are considerd to be data.
-    # @return String 
+    # @return String
     def auto_filter
       @auto_filter ||= AutoFilter.new self
     end
@@ -193,6 +196,21 @@ module Axlsx
       @print_options
     end
 
+    # Options for headers and footers.
+    # @example
+    #   wb = Axlsx::Package.new.workbook
+    #   # would generate something like: "file.xlsx : sheet_name 2 of 7 date with timestamp"
+    #   header = {:different_odd_ => false, :odd_header => "&L&F : &A&C&Pof%N%R%D %T"}
+    #   ws = wb.add_worksheet :header_footer => header
+    #
+    # @see HeaderFooter#initialize
+    # @return [HeaderFooter]
+    def header_footer
+      @header_footer ||= HeaderFooter.new
+      yield @header_footer if block_given?
+      @header_footer
+    end
+
     # convinience method to access all cells in this worksheet
     # @return [Array] cells
     def cells
@@ -280,7 +298,7 @@ module Axlsx
 
     # The name of the worksheet
     # The name of a worksheet must be unique in the workbook, and must not exceed 31 characters
-    # @param [String] name 
+    # @param [String] name
     def name=(name)
       validate_sheet_name name
       @name=Axlsx::coder.encode(name)
@@ -388,7 +406,7 @@ module Axlsx
       cf = ConditionalFormatting.new( :sqref => cells )
       cf.add_rules rules
       conditional_formattings << cf
-      conditional_formattings      
+      conditional_formattings
     end
 
     # Add data validation to this worksheet.
@@ -513,7 +531,7 @@ module Axlsx
     def sanitize(str)
       str.gsub(CONTROL_CHAR_REGEX, '')
     end
-    
+
     # The worksheet relationships. This is managed automatically by the worksheet
     # @return [Relationships]
     def relationships
@@ -570,12 +588,12 @@ module Axlsx
 
 
     private
-   
+
     def validate_sheet_name(name)
       DataTypeValidator.validate "Worksheet.name", String, name
       raise ArgumentError, (ERR_SHEET_NAME_TOO_LONG % name) if name.size > 31
       raise ArgumentError, (ERR_SHEET_NAME_COLON_FORBIDDEN % name) if name.include? ':'
-      name = Axlsx::coder.encode(name) 
+      name = Axlsx::coder.encode(name)
       sheet_names = @workbook.worksheets.map { |s| s.name }
       raise ArgumentError, (ERR_DUPLICATE_SHEET_NAME % name) if sheet_names.include?(name)
     end
@@ -586,7 +604,7 @@ module Axlsx
        sheet_data, sheet_calc_pr, @sheet_protection, protected_ranges,
        auto_filter, merged_cells, conditional_formattings,
        data_validations, hyperlinks, print_options, page_margins,
-       page_setup, worksheet_drawing, worksheet_comments,
+       page_setup, header_footer, worksheet_drawing, worksheet_comments,
        tables]
     end
 
@@ -606,7 +624,7 @@ module Axlsx
     # @see Worksheet#protect_range
     # @return [SimpleTypedList] The protected ranges for this worksheet
     def protected_ranges
-      @protected_ranges ||= ProtectedRanges.new self 
+      @protected_ranges ||= ProtectedRanges.new self
       # SimpleTypedList.new ProtectedRange
     end
 
@@ -619,7 +637,7 @@ module Axlsx
     # data validations array
     # @return [Array]
     def data_validations
-      @data_validations ||= DataValidations.new self 
+      @data_validations ||= DataValidations.new self
     end
 
     # merged cells array