axlsx 1.2.0 → 2.0.0

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

@@ -0,0 +1,246 @@
+module Axlsx
+
+  # When multiple values are chosen to filter by, or when a group of date values are chosen to filter by, 
+  # this object groups those criteria together.
+  class Filters
+    include Axlsx::OptionsParser
+    include Axlsx::SerializedAttributes
+
+    # Creates a new Filters object
+    # @param [Hash] options Options used to set this objects attributes and
+    #                       create filter and/or date group items
+    # @option [Boolean] blank @see blank
+    # @option [String] calendar_type @see calendar_type
+    # @option [Array] filter_items An array of values that will be used to create filter objects.
+    # @option [Array] date_group_items An array of hases defining date group item filters to apply.
+    # @note The recommended way to interact with filter objects is via AutoFilter#add_column
+    # @example
+    #   ws.auto_filter.add_column(0, :filters, :blank => true, :calendar_type => 'japan', :filter_items => [100, 'a'])
+    def initialize(options={})
+      parse_options options
+    end
+
+    serializable_attributes :blank, :calendar_type
+
+    # Allowed calendar types
+    CALENDAR_TYPES = %w(gregorian gregorianUs gregorianMeFrench gregorianArabic hijri hebrew taiwan japan thai korea saka gregorianXlitEnglish gregorianXlitFrench none)
+
+    # Flag indicating whether to filter by blank.
+    # @return [Boolean]
+    attr_reader :blank
+
+    # Calendar type for date grouped items. 
+    # Used to interpret the values in dateGroupItem.
+    # This is the calendar type used to evaluate all dates in the filter column,
+    # even when those dates are not using the same calendar system / date formatting.
+    attr_reader :calendar_type
+
+    # Tells us if the row of the cell provided should be filterd as it
+    # does not meet any of the specified filter_items or
+    # date_group_items restrictions.
+    # @param [Cell] cell The cell to test against items
+    # TODO implement this for date filters as well!
+    def apply(cell)
+      return false unless cell
+      filter_items.each do |filter|
+        return false if cell.value == filter.val
+      end
+      true
+    end
+
+    # The filter values in this filters object
+    def filter_items
+      @filter_items ||= []
+    end
+
+    # the date group values in this filters object
+    def date_group_items
+      @date_group_items ||= []
+    end
+
+    # @see calendar_type
+    # @param [String] calendar The calendar type to use. This must be one of the types defined in CALENDAR_TYPES
+    # @return [String]
+    def calendar_type=(calendar)
+      RestrictionValidator.validate 'Filters.calendar_type', CALENDAR_TYPES, calendar
+      @calendar_type = calendar
+    end
+
+    # Set the value for blank
+    # @see blank
+    def blank=(use_blank)
+      Axlsx.validate_boolean use_blank
+      @blank = use_blank
+    end
+
+    # Serialize the object to xml
+    def to_xml_string(str = '')
+      str << "<filters #{serialized_attributes}>"
+      filter_items.each {  |filter| filter.to_xml_string(str) }
+      date_group_items.each { |date_group_item| date_group_item.to_xml_string(str) }
+      str << '</filters>'
+    end
+
+    # not entirely happy with this. 
+    # filter_items should be a simple typed list that overrides << etc
+    # to create Filter objects from the inserted values. However this
+    # is most likely so rarely used...(really? do you know that?)
+    def filter_items=(values)
+      values.each do |value|
+        filter_items << Filter.new(value)
+      end
+    end
+
+    # Date group items are date group filter items where you specify the
+    # date_group and a value for that option as part of the auto_filter
+    # @note This can be specified, but will not be applied to the date
+    # values in your workbook at this time.
+    def date_group_items=(options)
+      options.each do |date_group|
+        raise ArgumentError, "date_group_items should be an array of hashes specifying the options for each date_group_item" unless date_group.is_a?(Hash)
+        date_group_items << DateGroupItem.new(date_group)
+      end
+    end
+
+    # This class expresses a filter criteria value.
+    class Filter
+
+      # Creates a new filter value object
+      # @param [Any] value   The value of the filter. This is not restricted, but
+      #                       will be serialized via to_s so if you are passing an object
+      #                       be careful.
+      def initialize(value)
+        @val = value
+      end
+
+
+      #Filter value used in the criteria.
+      attr_accessor :val
+
+      # Serializes the filter value object
+      # @param [String] str The string to concact the serialization information to.
+      def to_xml_string(str = '')
+        str << "<filter val='#{@val.to_s}' />"
+      end
+    end
+
+
+    # This collection is used to express a group of dates or times which are
+    # used in an AutoFilter criteria. Values are always written in the calendar
+    # type of the first date encountered in the filter range, so that all
+    # subsequent dates, even when formatted or represented by other calendar
+    # types, can be correctly compared for the purposes of filtering.
+    class DateGroupItem
+      include Axlsx::OptionsParser
+include Axlsx::SerializedAttributes
+
+      # Creates a new DateGroupItem
+      # @param [Hash] options A hash of options to use when
+      # instanciating the object
+      # @option [String] date_time_grouping the part of the date this
+      # filter should apply for grouping
+      # @option [Integer|String] year @see year
+      # @option [Integer] month @see month
+      # @option [Integer] day @see day
+      # @option [Integer] hour @see hour
+      # @option [Integer] minute @see minute
+      # @option [Integer] second @see second
+      def initialize(options={})
+        raise ArgumentError,  "You must specify a year for date time grouping" unless options[:year]
+        raise ArgumentError, "You must specify a date_time_grouping when creating a DateGroupItem for auto filter" unless options[:date_time_grouping]
+        parse_options options
+      end
+
+      serializable_attributes :date_time_grouping, :year, :month, :day, :hour, :minute, :second
+
+      # Allowed date time groupings
+      DATE_TIME_GROUPING = %w(year month day hour minute second)
+
+      # Grouping level
+      # This must be one of year, month, day, hour, minute or second.
+      # @return [String]
+      attr_reader :date_time_grouping
+
+      # Year (4 digits)
+      # @return [Integer|String]
+      attr_reader :year
+
+      # Month (1..12)
+      # @return [Integer]
+      attr_reader :month
+
+      # Day (1-31)
+      # @return [Integer]
+      attr_reader :day
+
+      # Hour (0..23)
+      # @return [Integer]
+      attr_reader :hour
+
+      # Minute (0..59(
+      # @return [Integer]
+      attr_reader :minute
+
+      # Second (0..59)
+      # @return [Integer]
+      attr_reader :second
+
+      # The year value for the date group item
+      # This must be a four digit value
+      def year=(value)
+        RegexValidator.validate "DateGroupItem.year", /\d{4}/, value
+        @year = value
+      end
+
+      # The month value for the date group item
+      # This must be between 1 and 12
+      def month=(value)
+        RangeValidator.validate "DateGroupItem.month", 0, 12, value
+        @month = value
+      end
+
+      # The day value for the date group item
+      # This must be between 1 and 31 
+      # @note no attempt is made to ensure the date value is valid for any given month
+      def day=(value)
+        RangeValidator.validate "DateGroupItem.day", 0, 31, value
+        @day = value
+      end
+
+      # The hour value for the date group item
+      # # this must be between 0 and 23
+      def hour=(value)
+        RangeValidator.validate "DateGroupItem.hour", 0, 23, value
+        @hour = value
+      end
+
+      # The minute value for the date group item
+      # This must be between 0 and 59
+      def minute=(value)
+        RangeValidator.validate "DateGroupItem.minute", 0, 59, value
+        @minute = value
+      end
+
+      # The second value for the date group item
+      # This must be between 0 and 59
+      def second=(value)
+        RangeValidator.validate "DateGroupItem.second", 0, 59, value
+        @second = value
+      end
+
+      # The date time grouping for this filter.
+      def date_time_grouping=(grouping)
+        RestrictionValidator.validate 'DateGroupItem.date_time_grouping', DATE_TIME_GROUPING, grouping.to_s
+        @date_time_grouping = grouping.to_s
+      end
+
+      # Serialize the object to xml
+      # @param [String] str The string object this serialization will be concatenated to.
+      def to_xml_string(str = '')
+        str << '<dateGroupItem '
+        serialized_attributes str
+        str << '/>'
+      end
+    end
+  end
+end

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

@@ -0,0 +1,37 @@
+module Axlsx
+
+  # The Break class stores the details for row and column page breaks.
+  # @see RowBreaks, ColBreaks
+  class Break
+
+    include Axlsx::OptionsParser
+    include Axlsx::Accessors
+    include Axlsx::SerializedAttributes
+
+    # Creates a new Break object
+    # @param options A hash of attribute options for this break.
+    # @option options [Integer] id Zero-based row or column Id of the page break. Breaks occur above the specified row and left of the specified column.
+    # @option options [Integer] min Zero-based index of start row or column of the break. For row breaks, specifies column index; for column breaks, specifies row index.
+    # @option options [Integer] max Zero-based index of end row or column of the break. For row breaks, specifies column index; for column breaks, specifies row index.
+    # @option options [Boolean] man Manual Break flag. 1 means the break is a manually inserted break.
+    # @option option [Boolean] pt Flag indicating that a PivotTable created this break.
+    def initialize(options={})
+      parse_options options
+      yield self if block_given?
+    end
+
+    unsigned_int_attr_accessor :id, :min, :max
+
+    boolean_attr_accessor :man, :pt
+
+    serializable_attributes :id, :min, :max, :man, :pt
+
+    # serializes the break to xml
+    def to_xml_string(str='')
+      str << '<brk '
+      serialized_attributes str
+      str << '></brk>'
+    end
+  end
+end
+

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

@@ -8,6 +8,44 @@ module Axlsx
   # @see Worksheet#add_row
   class Cell
 
+    include Axlsx::OptionsParser
+
+    # @param [Row] row The row this cell belongs to.
+    # @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
+    # @option options [Integer] charset
+    # @option options [String] family
+    # @option options [Boolean] b
+    # @option options [Boolean] i
+    # @option options [Boolean] strike
+    # @option options [Boolean] outline
+    # @option options [Boolean] shadow
+    # @option options [Boolean] condense
+    # @option options [Boolean] extend
+    # @option options [Boolean] u
+    # @option options [Symbol] vertAlign must be one of :baseline, :subscript, :superscript
+    # @option options [Integer] sz
+    # @option options [String] color an 8 letter rgb specification
+    # @option options [Number] formula_value The value to cache for a formula cell.
+    # @option options [Symbol] scheme must be one of :none, major, :minor
+    def initialize(row, value="", options={})
+      self.row=row
+      @value = nil
+      #@value = @font_name = @charset = @family = @b = @i = @strike = @outline = @shadow = nil
+      #@formula_value = @condense = @u = @vertAlign = @sz = @color = @scheme = @extend = @ssti = nil
+      @styles = row.worksheet.workbook.styles
+      @row.cells << self
+      parse_options options
+      @style ||= 0
+      @type ||= cell_type_from_value(value)
+      @value = cast_value(value)
+    end
+
+    # this is the cached value for formula cells. If you want the values to render in iOS/Mac OSX preview
+    # you need to set this.
+    attr_accessor :formula_value
 
     # An array of available inline styes.
     # TODO change this to a hash where each key defines attr name and validator (and any info the validator requires)
@@ -16,9 +54,9 @@ module Axlsx
     # set_attr method that kicks the suplied validator and updates the instance_variable
     # for the key
     INLINE_STYLES = ['value', 'type', 'font_name', 'charset',
-                         'family', 'b', 'i', 'strike','outline',
-                         'shadow', 'condense', 'extend', 'u',
-                         'vertAlign', 'sz', 'color', 'scheme']
+                     '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]
@@ -43,14 +81,14 @@ module Axlsx
     attr_reader :type
     # @see type
     def type=(v)
-      RestrictionValidator.validate "Cell.type", [:date, :time, :float, :integer, :string, :boolean], v
+      RestrictionValidator.validate "Cell.type", [:date, :time, :float, :integer, :string, :boolean, :iso_8601], v
       @type=v
       self.value = @value unless @value.nil?
     end
 
 
     # The value of this cell.
-    # @return [String, Integer, Float, Time] casted value based on cell's type attribute.
+    # @return [String, Integer, Float, Time, Boolean] casted value based on cell's type attribute.
     attr_reader :value
     # @see value
     def value=(v)
@@ -80,16 +118,43 @@ module Axlsx
     def font_name=(v) set_run_style :validate_string, :font_name, v; end
 
     # The inline charset property for the cell
+    # As far as I can tell, this is pretty much ignored. However, based on the spec it should be one of the following:
+    # 0  ANSI_CHARSET
+    # 1 DEFAULT_CHARSET
+    # 2 SYMBOL_CHARSET
+    # 77 MAC_CHARSET
+    # 128 SHIFTJIS_CHARSET
+    # 129  HANGUL_CHARSET
+    # 130  JOHAB_CHARSET
+    # 134  GB2312_CHARSET
+    # 136  CHINESEBIG5_CHARSET
+    # 161  GREEK_CHARSET
+    # 162  TURKISH_CHARSET
+    # 163  VIETNAMESE_CHARSET
+    # 177  HEBREW_CHARSET
+    # 178  ARABIC_CHARSET
+    # 186  BALTIC_CHARSET
+    # 204  RUSSIAN_CHARSET
+    # 222  THAI_CHARSET
+    # 238  EASTEUROPE_CHARSET
+    # 255  OEM_CHARSET
     # @return [String]
     attr_reader :charset
     # @see charset
     def charset=(v) set_run_style :validate_unsigned_int, :charset, v; end
 
     # The inline family property for the cell
-    # @return [String]
+    # @return [Integer]
+    # 1 Roman
+    # 2 Swiss
+    # 3 Modern
+    # 4 Script
+    # 5 Decorative
     attr_reader :family
     # @see family
-    def family=(v) set_run_style :validate_string, :family, v; end
+    def family=(v)
+      set_run_style :validate_family, :family, v.to_i
+    end
 
     # The inline bold property for the cell
     # @return [Boolean]
@@ -133,11 +198,17 @@ module Axlsx
     # @see extend
     def extend=(v) set_run_style :validate_boolean, :extend, v; end
 
-    # The inline underline property for the cell
+    # The inline underline property for the cell.
+    # It must be one of :none, :single, :double, :singleAccounting, :doubleAccounting, true
     # @return [Boolean]
+    # @return [String]
+    # @note true is for backwards compatability and is reassigned to :single
     attr_reader :u
     # @see u
-    def u=(v) set_run_style :validate_boolean, :u, v; end
+    def u=(v)
+      v = :single if (v == true || v == 1 || v == :true || v == 'true')
+      set_run_style :validate_cell_u, :u, v
+    end
 
     # The inline color property for the cell
     # @return [Color]
@@ -149,7 +220,7 @@ module Axlsx
     end
 
     # The inline sz property for the cell
-    # @return [Boolean]
+    # @return [Inteter]
     attr_reader :sz
     # @see sz
     def sz=(v) set_run_style :validate_unsigned_int, :sz, v; end
@@ -174,39 +245,6 @@ module Axlsx
       set_run_style nil, :scheme, v
     end
 
-    # @param [Row] row The row this cell belongs to.
-    # @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
-    # @option options [Integer] charset
-    # @option options [String] family
-    # @option options [Boolean] b
-    # @option options [Boolean] i
-    # @option options [Boolean] strike
-    # @option options [Boolean] outline
-    # @option options [Boolean] shadow
-    # @option options [Boolean] condense
-    # @option options [Boolean] extend
-    # @option options [Boolean] u
-    # @option options [Symbol] vertAlign must be one of :baseline, :subscript, :superscript
-    # @option options [Integer] sz
-    # @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
-      @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
-      options.each do |o|
-        self.send("#{o[0]}=", o[1]) if self.respond_to? "#{o[0]}="
-      end
-      @style ||= 0
-      @type ||= cell_type_from_value(value)
-      @value = cast_value(value)
-    end
-
     # The Shared Strings Table index for this cell
     # @return [Integer]
     attr_reader :ssti
@@ -256,65 +294,13 @@ module Axlsx
       self.row.worksheet.merge_cells "#{self.r}:#{range_end}" unless range_end.nil?
     end
 
-    # builds an xml text run based on this cells attributes.
-    # @param [String] str The string instance this run will be concated to.
-    # @return [String]
-    def run_xml_string(str = '')
-      if is_text_run?
-        data = instance_values.reject{|key, value| value == nil || key == 'value' || key == 'type' }
-        keys = data.keys & INLINE_STYLES
-        str << "<r><rPr>"
-        keys.each do |key|
-          case key
-          when 'font_name'
-            str << "<rFont val='"<< @font_name << "'/>"
-          when 'color'
-            str << data[key].to_xml_string
-          else
-            str << "<" << key.to_s << " val='" << data[key].to_s << "'/>"
-          end
-        end
-        str << "</rPr>" << "<t>" << value.to_s << "</t></r>"
-      else
-        str << "<t>" << value.to_s << "</t>"
-      end
-      str
-    end
-
     # Serializes the cell
     # @param [Integer] r_index The row index for the cell
     # @param [Integer] c_index The cell index in the row.
     # @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 = '')
-      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.sub('=', '') << '</f>'
-        else
-          #parse shared
-          if @ssti
-            str << 't="s"><v>' << @ssti.to_s << '</v>'
-          else
-            str << 't="inlineStr"><is>' << run_xml_string << '</is>'
-          end
-        end
-      when :date
-        # TODO: See if this is subject to the same restriction as Time below
-        str << '><v>' << DateTimeConverter::date_to_serial(@value).to_s << '</v>'
-      when :time
-        str << '><v>' << DateTimeConverter::time_to_serial(@value).to_s << '</v>'
-      when :boolean
-        str << 't="b"><v>' << @value.to_s << '</v>'
-      else
-        str << '><v>' << @value.to_s << '</v>'
-      end
-      str << '</c>'
+      CellSerializer.to_xml_string r_index, c_index, self, str
     end
 
     def is_formula?
@@ -330,20 +316,25 @@ module Axlsx
       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. 
+    # this cell.
     # @param [Boolean] absolute -when false a relative reference will be
-    # returned. 
+    # returned.
     # @return [String]
     def reference(absolute=true)
       absolute ? r_abs : r
-    end 
-    
+    end
+
     private
 
+    # we scale the font size if bold style is applied to either the style font or
+    # the cell itself. Yes, it is a bit of a hack, but it is much better than using
+    # imagemagick and loading metrics for every character.
     def font_size
-        sz || @styles.fonts[@styles.cellXfs[style].fontId].sz
+      font = @styles.fonts[@styles.cellXfs[style].fontId] || @styles.fonts[0]
+      size_from_styles = (font.b || b) ? font.sz * 1.5 : font.sz
+      sz || size_from_styles
     end
 
     # Utility method for setting inline style attributes
@@ -361,7 +352,7 @@ 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:
@@ -378,10 +369,15 @@ module Axlsx
         :time
       elsif v.is_a?(TrueClass) || v.is_a?(FalseClass)
         :boolean
-      elsif v.to_s.match(/\A[+-]?\d+?\Z/) #numeric
+      elsif v.to_s =~ /\A[+-]?\d+?\Z/ #numeric
         :integer
-      elsif v.to_s.match(/\A[+-]?\d+\.\d+?\Z/) #float
+      elsif v.to_s =~ /\A[-+]?[0-9]*\.?[0-9]+([eE][-+]?[0-9]+)?\Z/ #float
         :float
+        # \A(-?(?:[1-9][0-9]*)?[0-9]{4})-(1[0-2]|0[1-9])-(3[0-1]|0[1-9]|[1-2][0-9])
+        # T(2[0-3]|[0-1][0-9]):([0-5][0-9]):([0-5][0-9])(\.[0-9]+)?
+        # (Z|[+-](?:2[0-3]|[0-1][0-9]):[0-5][0-9])?\Z
+      elsif v.to_s =~/\A(-?(?:[1-9][0-9]*)?[0-9]{4})-(1[0-2]|0[1-9])-(3[0-1]|0[1-9]|[1-2][0-9])T(2[0-3]|[0-1][0-9]):([0-5][0-9]):([0-5][0-9])(\.[0-9]+)?(Z|[+-](?:2[0-3]|[0-1][0-9]):[0-5][0-9])?\Z/
+        :iso_8601
       else
         :string
       end
@@ -389,7 +385,7 @@ module Axlsx
 
     # 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.
+    #   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)
       return nil if v.nil?
@@ -405,10 +401,16 @@ module Axlsx
         v.to_i
       elsif @type == :boolean
         v ? 1 : 0
+      elsif @type == :iso_8601
+        #consumer is responsible for ensuring the iso_8601 format when specifying this type
+        v
       else
         @type = :string
-        ::CGI.escapeHTML(v.to_s)
+        # TODO find a better way to do this as it accounts for 30% of
+        # processing time in benchmarking...
+        Axlsx::trust_input ? v.to_s : ::CGI.escapeHTML(v.to_s)
       end
     end
+
   end
 end