write_xlsx 1.12.3 → 1.15.0

data/lib/write_xlsx/utility/chart_formatting.rb

@@ -0,0 +1,262 @@
+# -*- coding: utf-8 -*-
+# frozen_string_literal: true
+
+module Writexlsx
+  module Utility
+    module ChartFormatting
+      PATTERN_TYPES = {
+        'percent_5'                => 'pct5',
+        'percent_10'               => 'pct10',
+        'percent_20'               => 'pct20',
+        'percent_25'               => 'pct25',
+        'percent_30'               => 'pct30',
+        'percent_40'               => 'pct40',
+
+        'percent_50'               => 'pct50',
+        'percent_60'               => 'pct60',
+        'percent_70'               => 'pct70',
+        'percent_75'               => 'pct75',
+        'percent_80'               => 'pct80',
+        'percent_90'               => 'pct90',
+
+        'light_downward_diagonal'  => 'ltDnDiag',
+        'light_upward_diagonal'    => 'ltUpDiag',
+        'dark_downward_diagonal'   => 'dkDnDiag',
+        'dark_upward_diagonal'     => 'dkUpDiag',
+        'wide_downward_diagonal'   => 'wdDnDiag',
+        'wide_upward_diagonal'     => 'wdUpDiag',
+
+        'light_vertical'           => 'ltVert',
+        'light_horizontal'         => 'ltHorz',
+        'narrow_vertical'          => 'narVert',
+        'narrow_horizontal'        => 'narHorz',
+        'dark_vertical'            => 'dkVert',
+        'dark_horizontal'          => 'dkHorz',
+
+        'dashed_downward_diagonal' => 'dashDnDiag',
+        'dashed_upward_diagonal'   => 'dashUpDiag',
+        'dashed_horizontal'        => 'dashHorz',
+        'dashed_vertical'          => 'dashVert',
+        'small_confetti'           => 'smConfetti',
+        'large_confetti'           => 'lgConfetti',
+
+        'zigzag'                   => 'zigZag',
+        'wave'                     => 'wave',
+        'diagonal_brick'           => 'diagBrick',
+        'horizontal_brick'         => 'horzBrick',
+        'weave'                    => 'weave',
+        'plaid'                    => 'plaid',
+
+        'divot'                    => 'divot',
+        'dotted_grid'              => 'dotGrid',
+        'dotted_diamond'           => 'dotDmnd',
+        'shingle'                  => 'shingle',
+        'trellis'                  => 'trellis',
+        'sphere'                   => 'sphere',
+
+        'small_grid'               => 'smGrid',
+        'large_grid'               => 'lgGrid',
+        'small_check'              => 'smCheck',
+        'large_check'              => 'lgCheck',
+        'outlined_diamond'         => 'openDmnd',
+        'solid_diamond'            => 'solidDmnd'
+      }.freeze
+
+      #
+      # Convert user defined legend properties to the structure required internally.
+      #
+      def legend_properties(params)
+        legend = Writexlsx::Chart::Legend.new
+
+        legend.position      = params[:position] || 'right'
+        legend.delete_series = params[:delete_series]
+        legend.font          = convert_font_args(params[:font])
+
+        # Set the legend layout.
+        legend.layout = layout_properties(params[:layout])
+
+        # Turn off the legend.
+        legend.position = 'none' if params[:none]
+
+        # Set the line properties for the legend.
+        line = line_properties(params[:line])
+
+        # Allow 'border' as a synonym for 'line'.
+        line = line_properties(params[:border]) if params[:border]
+
+        # Set the fill properties for the legend.
+        fill = fill_properties(params[:fill])
+
+        # Set the pattern properties for the legend.
+        pattern = pattern_properties(params[:pattern])
+
+        # Set the gradient fill properties for the legend.
+        gradient = gradient_properties(params[:gradient])
+
+        # Pattern fill overrides solid fill.
+        fill = nil if pattern
+
+        # Gradient fill overrides solid and pattern fills.
+        if gradient
+          pattern = nil
+          fill    = nil
+        end
+
+        # Set the legend layout.
+        layout = layout_properties(params[:layout])
+
+        legend.line     = line
+        legend.fill     = fill
+        legend.pattern  = pattern
+        legend.gradient = gradient
+        legend.layout   = layout
+
+        @legend = legend
+      end
+
+      #
+      # Convert user defined layout properties to the format required internally.
+      #
+      def layout_properties(args, is_text = false)
+        return unless ptrue?(args)
+
+        properties = is_text ? %i[x y] : %i[x y width height]
+
+        # Check for valid properties.
+        args.each_key do |key|
+          raise "Property '#{key}' not allowed in layout options\n" unless properties.include?(key.to_sym)
+        end
+
+        # Set the layout properties
+        layout = {}
+        properties.each do |property|
+          value = args[property]
+          # Convert to the format used by Excel for easier testing.
+          layout[property] = sprintf("%.17g", value)
+        end
+
+        layout
+      end
+
+      #
+      # Convert user defined line properties to the structure required internally.
+      #
+      def line_properties(line) # :nodoc:
+        line_fill_properties(line) do
+          value_or_raise(dash_types, line[:dash_type], 'dash type')
+        end
+      end
+
+      #
+      # Convert user defined fill properties to the structure required internally.
+      #
+      def fill_properties(fill) # :nodoc:
+        line_fill_properties(fill)
+      end
+
+      #
+      # Convert user defined pattern properties to the structure required internally.
+      #
+      def pattern_properties(args) # :nodoc:
+        return nil unless args
+        # Check the pattern type is present.
+        return nil unless args.has_key?(:pattern)
+        # Check the foreground color is present.
+        return nil unless args.has_key?(:fg_color)
+
+        pattern = {}
+
+        type = PATTERN_TYPES[args[:pattern]]
+        raise "Unknown pattern type '#{args[:pattern]}'" unless type
+
+        pattern[:pattern] = type
+        pattern[:bg_color] = args[:bg_color] || '#FFFFFF'
+        pattern[:fg_color] = args[:fg_color]
+
+        pattern
+      end
+
+      def line_fill_properties(params)
+        return { _defined: 0 } unless params
+
+        ret = params.dup
+        ret[:dash_type] = yield if block_given? && ret[:dash_type]
+        ret[:_defined] = 1
+        ret
+      end
+
+      def dash_types
+        {
+          solid:               'solid',
+          round_dot:           'sysDot',
+          square_dot:          'sysDash',
+          dash:                'dash',
+          dash_dot:            'dashDot',
+          long_dash:           'lgDash',
+          long_dash_dot:       'lgDashDot',
+          long_dash_dot_dot:   'lgDashDotDot',
+          dot:                 'dot',
+          system_dash_dot:     'sysDashDot',
+          system_dash_dot_dot: 'sysDashDotDot'
+        }
+      end
+
+      def value_or_raise(hash, key, msg)
+        raise "Unknown #{msg} '#{key}'" if hash[key.to_sym].nil?
+
+        hash[key.to_sym]
+      end
+
+      def palette_color_from_index(index)
+        # Adjust the colour index.
+        idx = index - 8
+
+        r, g, b = @palette[idx]
+        sprintf("%02X%02X%02X", r, g, b)
+      end
+
+      #
+      # Convert the user specified colour index or string to a rgb colour.
+      #
+      def color(color_code) # :nodoc:
+        if color_code && color_code =~ /^#[0-9a-fA-F]{6}$/
+          # Convert a HTML style #RRGGBB color.
+          color_code.sub(/^#/, '').upcase
+        else
+          index = Format.color(color_code)
+          raise "Unknown color '#{color_code}' used in chart formatting." unless index
+
+          palette_color_from_index(index)
+        end
+      end
+
+      #
+      # Write the <a:solidFill> element.
+      #
+      def write_a_solid_fill(fill) # :nodoc:
+        @writer.tag_elements('a:solidFill') do
+          if fill[:color]
+            # Write the a:srgbClr element.
+            write_a_srgb_clr(color(fill[:color]), fill[:transparency])
+          end
+        end
+      end
+
+      #
+      # Write the <a:srgbClr> element.
+      #
+      def write_a_srgb_clr(color, transparency = nil) # :nodoc:
+        tag        = 'a:srgbClr'
+        attributes = [['val', color]]
+
+        if ptrue?(transparency)
+          @writer.tag_elements(tag, attributes) do
+            write_a_alpha(transparency)
+          end
+        else
+          @writer.empty_tag(tag, attributes)
+        end
+      end
+    end
+  end
+end

data/lib/write_xlsx/utility/common.rb

@@ -0,0 +1,44 @@
+# -*- coding: utf-8 -*-
+# frozen_string_literal: true
+
+module Writexlsx
+  module Utility
+    module Common
+      PERL_TRUE_VALUES   = [false, nil, 0, "0", "", [], {}].freeze
+
+      #
+      # return perl's boolean result
+      #
+      def ptrue?(value)
+        !PERL_TRUE_VALUES.include?(value)
+      end
+
+      def check_parameter(params, valid_keys, method)
+        invalids = params.keys - valid_keys
+        unless invalids.empty?
+          raise WriteXLSXOptionParameterError,
+                "Unknown parameter '#{invalids.join(", ")}' in #{method}."
+        end
+        true
+      end
+
+      def absolute_char(absolute)
+        absolute ? '$' : ''
+      end
+
+      def float_to_str(float)
+        return '' unless float
+
+        if float == float.to_i
+          float.to_i.to_s
+        else
+          float.to_s
+        end
+      end
+
+      def put_deprecate_message(method)
+        warn("Warning: calling deprecated method #{method}. This method will be removed in a future release.")
+      end
+    end
+  end
+end

data/lib/write_xlsx/utility/date_time.rb

@@ -0,0 +1,113 @@
+# -*- coding: utf-8 -*-
+# frozen_string_literal: true
+
+module Writexlsx
+  module Utility
+    module DateTime
+      #
+      # convert_date_time(date_time_string)
+      #
+      # The function takes a date and time in ISO8601 "yyyy-mm-ddThh:mm:ss.ss" format
+      # and converts it to a decimal number representing a valid Excel date.
+      #
+      def convert_date_time(date_time_string)       # :nodoc:
+        date_time = date_time_string.to_s.sub(/^\s+/, '').sub(/\s+$/, '').sub(/Z$/, '')
+
+        # Check for invalid date char.
+        return nil if date_time =~ /[^0-9T:\-.Z]/
+
+        # Check for "T" after date or before time.
+        return nil unless date_time =~ /\dT|T\d/
+
+        days      = 0 # Number of days since epoch
+        seconds   = 0 # Time expressed as fraction of 24h hours in seconds
+
+        # Split into date and time.
+        date, time = date_time.split("T")
+
+        # We allow the time portion of the input DateTime to be optional.
+        if time
+          # Match hh:mm:ss.sss+ where the seconds are optional
+          if time =~ /^(\d\d):(\d\d)(:(\d\d(\.\d+)?))?/
+            hour   = ::Regexp.last_match(1).to_i
+            min    = ::Regexp.last_match(2).to_i
+            sec    = ::Regexp.last_match(4).to_f
+          else
+            return nil # Not a valid time format.
+          end
+
+          # Some boundary checks
+          return nil if hour >= 24
+          return nil if min  >= 60
+          return nil if sec  >= 60
+
+          # Excel expresses seconds as a fraction of the number in 24 hours.
+          seconds = ((hour * 60 * 60) + (min * 60) + sec) / (24.0 * 60 * 60)
+        end
+
+        # We allow the date portion of the input DateTime to be optional.
+        return seconds if date == ''
+
+        # Match date as yyyy-mm-dd.
+        if date =~ /^(\d\d\d\d)-(\d\d)-(\d\d)$/
+          year   = ::Regexp.last_match(1).to_i
+          month  = ::Regexp.last_match(2).to_i
+          day    = ::Regexp.last_match(3).to_i
+        else
+          return nil  # Not a valid date format.
+        end
+
+        # Set the epoch as 1900 or 1904. Defaults to 1900.
+        # Special cases for Excel.
+        unless date_1904?
+          return      seconds if date == '1899-12-31' # Excel 1900 epoch
+          return      seconds if date == '1900-01-00' # Excel 1900 epoch
+          return 60 + seconds if date == '1900-02-29' # Excel false leapday
+        end
+
+        # We calculate the date by calculating the number of days since the epoch
+        # and adjust for the number of leap days. We calculate the number of leap
+        # days by normalising the year in relation to the epoch. Thus the year 2000
+        # becomes 100 for 4 and 100 year leapdays and 400 for 400 year leapdays.
+        #
+        epoch   = date_1904? ? 1904 : 1900
+        offset  = date_1904? ? 4 : 0
+        norm    = 300
+        range   = year - epoch
+
+        # Set month days and check for leap year.
+        mdays   = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31]
+        leap    = 0
+        leap    = 1  if (year % 4 == 0 && year % 100 != 0) || year % 400 == 0
+        mdays[1] = 29 if leap != 0
+
+        # Some boundary checks
+        return nil if year  < epoch || year  > 9999
+        return nil if month < 1     || month > 12
+        return nil if day   < 1     || day   > mdays[month - 1]
+
+        # Accumulate the number of days since the epoch.
+        days = day                               # Add days for current month
+        (0..(month - 2)).each do |m|
+          days += mdays[m]                      # Add days for past months
+        end
+        days += range * 365                      # Add days for past years
+        days += (range / 4)                      # Add leapdays
+        days -= ((range + offset) / 100)         # Subtract 100 year leapdays
+        days += ((range + offset + norm) / 400)  # Add 400 year leapdays
+        days -= leap                             # Already counted above
+
+        # Adjust for Excel erroneously treating 1900 as a leap year.
+        days += 1 if !date_1904? && days > 59
+
+        date_time = sprintf("%0.10f", days + seconds)
+        date_time = date_time.sub(/\.?0+$/, '') if date_time =~ /\./
+        if date_time =~ /\./
+          date_time.to_f
+        else
+          date_time.to_i
+        end
+      end
+    end
+  end
+end

data/lib/write_xlsx/utility/dimensions.rb

@@ -0,0 +1,40 @@
+# -*- coding: utf-8 -*-
+# frozen_string_literal: true
+
+require 'write_xlsx/constants'
+
+module Writexlsx
+  module Utility
+    module Dimensions
+      include Constants
+
+      def check_dimensions(row, col)
+        raise WriteXLSXDimensionError if !row || row >= ROW_MAX || !col || col >= COL_MAX
+
+        0
+      end
+
+      #
+      # Check that row and col are valid and store max and min values for use in
+      # other methods/elements.
+      #
+      def check_dimensions_and_update_max_min_values(row, col, ignore_row = 0, ignore_col = 0)       # :nodoc:
+        check_dimensions(row, col)
+        store_row_max_min_values(row) if ignore_row == 0
+        store_col_max_min_values(col) if ignore_col == 0
+
+        0
+      end
+
+      def store_row_max_min_values(row)
+        @dim_rowmin = row if !@dim_rowmin || (row < @dim_rowmin)
+        @dim_rowmax = row if !@dim_rowmax || (row > @dim_rowmax)
+      end
+
+      def store_col_max_min_values(col)
+        @dim_colmin = col if !@dim_colmin || (col < @dim_colmin)
+        @dim_colmax = col if !@dim_colmax || (col > @dim_colmax)
+      end
+    end
+  end
+end

data/lib/write_xlsx/utility/drawing.rb

@@ -0,0 +1,136 @@
+# -*- coding: utf-8 -*-
+# frozen_string_literal: true
+
+module Writexlsx
+  module Utility
+    module Drawing
+      #
+      # Convert vertices from pixels to points.
+      #
+      def pixels_to_points(vertices)
+        _col_start, _row_start, _x1,    _y1,
+        _col_end,   _row_end,   _x2,    _y2,
+        left,      top,       width, height  = vertices.flatten
+
+        left   *= 0.75
+        top    *= 0.75
+        width  *= 0.75
+        height *= 0.75
+
+        [left, top, width, height]
+      end
+
+      def v_shape_attributes_base(id)
+        [
+          ['id',    "_x0000_s#{id}"],
+          ['type',  type]
+        ]
+      end
+
+      def v_shape_style_base(z_index, vertices)
+        left, top, width, height = pixels_to_points(vertices)
+
+        left_str    = float_to_str(left)
+        top_str     = float_to_str(top)
+        width_str   = float_to_str(width)
+        height_str  = float_to_str(height)
+        z_index_str = float_to_str(z_index)
+
+        shape_style_base(left_str, top_str, width_str, height_str, z_index_str)
+      end
+
+      def shape_style_base(left_str, top_str, width_str, height_str, z_index_str)
+        [
+          'position:absolute;',
+          'margin-left:',
+          left_str, 'pt;',
+          'margin-top:',
+          top_str, 'pt;',
+          'width:',
+          width_str, 'pt;',
+          'height:',
+          height_str, 'pt;',
+          'z-index:',
+          z_index_str, ';'
+        ]
+      end
+
+      #
+      # Write the <v:fill> element.
+      #
+      def write_fill
+        @writer.empty_tag('v:fill', fill_attributes)
+      end
+
+      #
+      # Write the <v:path> element.
+      #
+      def write_comment_path(gradientshapeok, connecttype)
+        attributes = []
+
+        attributes << %w[gradientshapeok t] if gradientshapeok
+        attributes << ['o:connecttype', connecttype]
+
+        @writer.empty_tag('v:path', attributes)
+      end
+
+      #
+      # Write the <x:Anchor> element.
+      #
+      def write_anchor
+        col_start, row_start, x1, y1, col_end, row_end, x2, y2 = @vertices
+        data = [col_start, x1, row_start, y1, col_end, x2, row_end, y2].join(', ')
+
+        @writer.data_element('x:Anchor', data)
+      end
+
+      #
+      # Write the <x:AutoFill> element.
+      #
+      def write_auto_fill
+        @writer.data_element('x:AutoFill', 'False')
+      end
+
+      #
+      # Write the <div> element.
+      #
+      def write_div(align, font = nil)
+        style = "text-align:#{align}"
+        attributes = [['style', style]]
+
+        @writer.tag_elements('div', attributes) do
+          if font
+            # Write the font element.
+            write_font(font)
+          end
+        end
+      end
+
+      #
+      # Write the <font> element.
+      #
+      def write_font(font)
+        caption = font[:_caption]
+        face    = 'Calibri'
+        size    = 220
+        color   = '#000000'
+
+        attributes = [
+          ['face',  face],
+          ['size',  size],
+          ['color', color]
+        ]
+        @writer.data_element('font', caption, attributes)
+      end
+
+      #
+      # Write the <v:stroke> element.
+      #
+      def write_stroke
+        attributes = [%w[joinstyle miter]]
+
+        @writer.empty_tag('v:stroke', attributes)
+      end
+    end
+  end
+end