write_xlsx 1.13.0 → 1.15.0

data/lib/write_xlsx/shape.rb

@@ -1,6 +1,8 @@
 # -*- coding: utf-8 -*-
 # frozen_string_literal: true
 
+require 'write_xlsx/utility/chart_formatting'
+
 module Writexlsx
   ###############################################################################
   #
@@ -12,7 +14,7 @@ module Writexlsx
   # Converted to ruby by Hideo NAKAMURA, nakamura.hideo@gmail.com
   #
   class Shape
-    include Writexlsx::Utility
+    include Writexlsx::Utility::ChartFormatting
 
     attr_reader :edit_as, :drawing
     attr_reader :tx_box, :fill, :line, :format
@@ -27,106 +29,11 @@ module Writexlsx
 
     def initialize(properties = {})
       @writer = Package::XMLWriterSimple.new
-      @name   = nil
-      @type   = 'rect'
-
-      # Is a Connector shape. 1/0 Value is a hash lookup from type.
-      @connect = 0
-
-      # Is a Drawing. Always 0, since a single shape never fills an entire sheet.
-      @drawing = 0
-
-      # OneCell or Absolute: options to move and/or size with cells.
-      @edit_as = nil
-
-      # Auto-incremented, unless supplied by user.
-      @id = 0
-
-      # Shape text (usually centered on shape geometry).
-      @text = 0
-
-      # Shape stencil mode.  A copy (child) is created when inserted.
-      # The link to parent is broken.
-      @stencil = 1
-
-      # Index to _shapes array when inserted.
-      @element = -1
-
-      # Shape ID of starting connection, if any.
-      @start = nil
-
-      # Shape vertex, starts at 0, numbered clockwise from 12 o'clock.
-      @start_index = nil
-
-      @end       = nil
-      @end_index = nil
-
-      # Number and size of adjustments for shapes (usually connectors).
-      @adjustments = []
-
-      # Start and end sides. t)op, b)ottom, l)eft, or r)ight.
-      @start_side = ''
-      @end_side   = ''
-
-      # Flip shape Horizontally. eg. arrow left to arrow right.
-      @flip_h = 0
 
-      # Flip shape Vertically. eg. up arrow to down arrow.
-      @flip_v = 0
-
-      # shape rotation (in degrees 0-360).
-      @rotation = 0
-
-      # An alternate way to create a text box, because Excel allows it.
-      # It is just a rectangle with text.
-      @tx_box = false
-
-      # Shape outline colour, or 0 for noFill (default black).
-      @line = '000000'
-
-      # Line type: dash, sysDot, dashDot, lgDash, lgDashDot, lgDashDotDot.
-      @line_type = ''
-
-      # Line weight (integer).
-      @line_weight = 1
-
-      # Shape fill colour, or 0 for noFill (default noFill).
-      @fill = 0
-
-      # Formatting for shape text, if any.
-      @format = {}
-
-      # copy of colour palette table from Workbook.pm.
-      @palette = []
-
-      # Vertical alignment: t, ctr, b.
-      @valign = 'ctr'
-
-      # Alignment: l, ctr, r, just
-      @align = 'ctr'
-
-      @x_offset = 0
-      @y_offset = 0
-
-      # Scale factors, which also may be set when the shape is inserted.
-      @scale_x = 1
-      @scale_y = 1
-
-      # Default size, which can be modified and/or scaled.
-      @width  = 50
-      @height = 50
-
-      # Initial assignment. May be modified when prepared.
-      @column_start = 0
-      @row_start    = 0
-      @x1           = 0
-      @y1           = 0
-      @column_end   = 0
-      @row_end      = 0
-      @x2           = 0
-      @y2           = 0
-      @x_abs        = 0
-      @y_abs        = 0
+      init_basic_attributes
+      init_connection_attributes
+      init_appearance_attributes
+      init_position_attributes
 
       set_properties(properties)
     end
@@ -298,5 +205,95 @@ module Writexlsx
         @width_emu,    @height_emu
       ]
     end
+
+    private
+
+    def init_basic_attributes
+      @name    = nil
+      @type    = 'rect'
+
+      # Is a Connector shape. 1/0 Value is a hash lookup from type.
+      @connect = 0
+      # Is a Drawing. Always 0, since a single shape never fills an entire sheet.
+      @drawing = 0
+      # OneCell or Absolute: options to move and/or size with cells.
+      @edit_as = nil
+      # Auto-incremented, unless supplied by user.
+      @id      = 0
+      # Shape text (usually centered on shape geometry).
+      @text    = 0
+      # Shape stencil mode.  A copy (child) is created when inserted.
+      # The link to parent is broken.
+      @stencil = 1
+      # Index to _shapes array when inserted.
+      @element = -1
+      # An alternate way to create a text box, because Excel allows it.
+      # It is just a rectangle with text.
+      @tx_box  = false
+      # copy of colour palette table from Workbook.pm.
+      @palette = []
+    end
+
+    def init_connection_attributes
+      # Shape ID of starting connection, if any.
+      @start       = nil
+      # Shape vertex, starts at 0, numbered clockwise from 12 o'clock.
+      @start_index = nil
+      @end         = nil
+      @end_index   = nil
+      # Number and size of adjustments for shapes (usually connectors).
+      @adjustments = []
+      # Start and end sides. t)op, b)ottom, l)eft, or r)ight.
+      @start_side  = ''
+      @end_side    = ''
+    end
+
+    def init_appearance_attributes
+      # Flip shape Horizontally. eg. arrow left to arrow right.
+      @flip_h      = 0
+      # Flip shape Vertically. eg. up arrow to down arrow.
+      @flip_v      = 0
+      # shape rotation (in degrees 0-360).
+      @rotation    = 0
+      # Shape outline colour, or 0 for noFill (default black).
+      @line        = '000000'
+      # Line type: dash, sysDot, dashDot, lgDash, lgDashDot, lgDashDotDot.
+      @line_type   = ''
+      # Line weight (integer).
+      @line_weight = 1
+      # Shape fill colour, or 0 for noFill (default noFill).
+      @fill        = 0
+      # Formatting for shape text, if any.
+      @format      = {}
+      # Vertical alignment: t, ctr, b.
+      @valign      = 'ctr'
+      # Alignment: l, ctr, r, just
+      @align       = 'ctr'
+    end
+
+    def init_position_attributes
+      @x_offset     = 0
+      @y_offset     = 0
+
+      # Scale factors, which also may be set when the shape is inserted.
+      @scale_x      = 1
+      @scale_y      = 1
+
+      # Default size, which can be modified and/or scaled.
+      @width        = 50
+      @height       = 50
+
+      # Initial assignment. May be modified when prepared.
+      @column_start = 0
+      @row_start    = 0
+      @x1           = 0
+      @y1           = 0
+      @column_end   = 0
+      @row_end      = 0
+      @x2           = 0
+      @y2           = 0
+      @x_abs        = 0
+      @y_abs        = 0
+    end
   end
 end

data/lib/write_xlsx/sheets.rb

@@ -2,11 +2,16 @@
 # frozen_string_literal: true
 
 require 'delegate'
+require 'write_xlsx/constants'
+require 'write_xlsx/utility/common'
+require 'write_xlsx/utility/xml_primitives'
 require 'write_xlsx/package/xml_writer_simple'
 
 module Writexlsx
   class Sheets < DelegateClass(Array)
-    include Writexlsx::Utility
+    include Constants
+    include Writexlsx::Utility::Common
+    include Writexlsx::Utility::XmlPrimitives
 
     BASE_NAME = { sheet: 'Sheet', chart: 'Chart' }  # :nodoc:
 

data/lib/write_xlsx/sparkline.rb

@@ -1,7 +1,7 @@
 # -*- coding: utf-8 -*-
 # frozen_string_literal: true
 
-require 'write_xlsx/utility'
+require 'write_xlsx/utility/common'
 
 module Writexlsx
   ###############################################################################
@@ -14,7 +14,7 @@ module Writexlsx
   # Converted to ruby by Hideo NAKAMURA, nakamura.hideo@gmail.com
   #
   class Sparkline
-    include Writexlsx::Utility
+    include Writexlsx::Utility::Common
 
     def initialize(ws, param, sheetname)
       @color = {}

data/lib/write_xlsx/utility/cell_reference.rb

@@ -0,0 +1,124 @@
+# -*- coding: utf-8 -*-
+# frozen_string_literal: true
+
+require 'write_xlsx/col_name'
+require 'write_xlsx/constants'
+
+module Writexlsx
+  module Utility
+    module CellReference
+      include Constants
+
+      #
+      # xl_rowcol_to_cell($row, col, row_absolute, col_absolute)
+      #
+      def xl_rowcol_to_cell(row_or_name, col, row_absolute = false, col_absolute = false)
+        if row_or_name.is_a?(Integer)
+          row_or_name += 1      # Change from 0-indexed to 1 indexed.
+        end
+        col_str = xl_col_to_name(col, col_absolute)
+        "#{col_str}#{absolute_char(row_absolute)}#{row_or_name}"
+      end
+
+      #
+      # Returns: [row, col, row_absolute, col_absolute]
+      #
+      # The row_absolute and col_absolute parameters aren't documented because they
+      # mainly used internally and aren't very useful to the user.
+      #
+      def xl_cell_to_rowcol(cell)
+        cell =~ /(\$?)([A-Z]{1,3})(\$?)(\d+)/
+
+        col_abs = ::Regexp.last_match(1) != ""
+        col     = ::Regexp.last_match(2)
+        row_abs = ::Regexp.last_match(3) != ""
+        row     = ::Regexp.last_match(4).to_i
+
+        # Convert base26 column string to number
+        # All your Base are belong to us.
+        chars = col.chars
+        expn = 0
+        col = 0
+
+        chars.reverse.each do |char|
+          col += (char.ord - 'A'.ord + 1) * (26**expn)
+          expn += 1
+        end
+
+        # Convert 1-index to zero-index
+        row -= 1
+        col -= 1
+
+        [row, col, row_abs, col_abs]
+      end
+
+      def xl_col_to_name(col, col_absolute)
+        col_str = ColName.instance.col_str(col)
+        if col_absolute
+          "#{absolute_char(col_absolute)}#{col_str}"
+        else
+          # Do not allocate new string
+          col_str
+        end
+      end
+
+      def xl_range(row_1, row_2, col_1, col_2,
+                   row_abs_1 = false, row_abs_2 = false, col_abs_1 = false, col_abs_2 = false)
+        range1 = xl_rowcol_to_cell(row_1, col_1, row_abs_1, col_abs_1)
+        range2 = xl_rowcol_to_cell(row_2, col_2, row_abs_2, col_abs_2)
+
+        if range1 == range2
+          range1
+        else
+          "#{range1}:#{range2}"
+        end
+      end
+
+      def xl_range_formula(sheetname, row_1, row_2, col_1, col_2)
+        # Use Excel's conventions and quote the sheet name if it contains any
+        # non-word character or if it isn't already quoted.
+        sheetname = quote_sheetname(sheetname)
+
+        range1 = xl_rowcol_to_cell(row_1, col_1, 1, 1)
+        range2 = xl_rowcol_to_cell(row_2, col_2, 1, 1)
+
+        "=#{sheetname}!#{range1}:#{range2}"
+      end
+
+      # Check for a cell reference in A1 notation and substitute row and column
+      def row_col_notation(row_or_a1)   # :nodoc:
+        substitute_cellref(row_or_a1) if row_or_a1.respond_to?(:match) && row_or_a1.to_s =~ /^\D/
+      end
+
+      #
+      # Substitute an Excel cell reference in A1 notation for  zero based row and
+      # column values in an argument list.
+      #
+      # Ex: ("A4", "Hello") is converted to (3, 0, "Hello").
+      #
+      def substitute_cellref(cell, *args)       # :nodoc:
+        normalized_cell = cell.upcase
+
+        case normalized_cell
+        # Convert a column range: 'A:A' or 'B:G'.
+        # A range such as A:A is equivalent to A1:65536, so add rows as required
+        when /\$?([A-Z]{1,3}):\$?([A-Z]{1,3})/
+          row1, col1 =  xl_cell_to_rowcol(::Regexp.last_match(1) + '1')
+          row2, col2 =  xl_cell_to_rowcol(::Regexp.last_match(2) + ROW_MAX.to_s)
+          [row1, col1, row2, col2, *args]
+        # Convert a cell range: 'A1:B7'
+        when /\$?([A-Z]{1,3}\$?\d+):\$?([A-Z]{1,3}\$?\d+)/
+          row1, col1 =  xl_cell_to_rowcol(::Regexp.last_match(1))
+          row2, col2 =  xl_cell_to_rowcol(::Regexp.last_match(2))
+          [row1, col1, row2, col2, *args]
+        # Convert a cell reference: 'A1' or 'AD2000'
+        when /\$?([A-Z]{1,3}\$?\d+)/
+          row1, col1 = xl_cell_to_rowcol(::Regexp.last_match(1))
+          [row1, col1, *args]
+        else
+          raise("Unknown cell reference #{normalized_cell}")
+        end
+      end
+    end
+  end
+end

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