wineole 0.1.0 → 0.2.0

data/lib/wineole/msoffice/excel.rb

@@ -0,0 +1,311 @@
+require_relative '../../wineole'
+require_relative '../proxy'
+require_relative 'passthrough'
+require_relative 'address'
+require_relative 'range'
+require_relative 'sheet'
+require_relative 'book'
+
+module WineOLE
+  module MSOffice
+    # Wraps a COM Excel.Application: the lifecycle (.create / .connect /
+    # .connect_or_create / .run) and the entry point of the addressing DSL
+    # that Address / Sheet / Book / Range build on.
+    #
+    # `version` is deliberately not defined -- see the comment on @version
+    # in #initialize.
+    #
+    # `run` here is a *class* method (Excel.run), never an instance one:
+    # COM's own Application.Run (the macro runner) is real -- measured on a
+    # live Excel 11, `xl.run` answers DISP_E_EXCEPTION, meaning COM tried
+    # to actually invoke it rather than reporting an unknown name. A class
+    # method lives in a completely separate namespace from an instance
+    # method of the same spelling, so `Excel.run` shadows nothing; adding
+    # an *instance* `run` would.
+    class Excel
+      include Passthrough
+
+      APPLICATION = 'Excel.Application'.freeze
+
+      # What the bridge runs on the way out of an auto-created instance,
+      # once its last user releases the root: suppress prompts, then quit.
+      # Declared here, once, and handed to the bridge at construction time
+      # (via Client#create/connect/connect_or_create's `cleanup:` kwarg)
+      # rather than run from Ruby -- the bridge is the only party that knows
+      # when the LAST user of a shared root has let go of it, so it is the
+      # only party that can decide whether these steps should run at all.
+      CLEANUP_STEPS = { steps: [['DisplayAlerts=', false], ['Quit']] }.freeze
+
+      def self.create(client: WineOLE.default_client, convert_paths: true)
+        new(client.create(APPLICATION, cleanup: CLEANUP_STEPS), client: client, convert_paths: convert_paths)
+      end
+
+      # Declares the same steps .create does. That is correct, not an
+      # oversight: the steps are a property of this instance, but they only
+      # ever RUN when the bridge's record is auto_created, which is false
+      # here unless connect_or_create's own fallback is what created it. A
+      # human's Excel reached via .connect is never auto_created, so Quit
+      # never fires for it -- this class used to enforce that with an
+      # `ole_created?` check of its own; the bridge enforces it now, one
+      # layer down.
+      def self.connect(client: WineOLE.default_client, convert_paths: true)
+        new(client.connect(APPLICATION, cleanup: CLEANUP_STEPS), client: client, convert_paths: convert_paths)
+      end
+
+      def self.connect_or_create(client: WineOLE.default_client, convert_paths: true)
+        new(client.connect_or_create(APPLICATION, cleanup: CLEANUP_STEPS), client: client, convert_paths: convert_paths)
+      end
+
+      # Runs the block with an Excel application, then releases it.
+      #
+      # Deciding whether that release actually quits Excel is no longer this
+      # method's job. create/connect/connect_or_create declare CLEANUP_STEPS
+      # at construction time, and the bridge is the one that knows when the
+      # LAST user of an auto-created root lets go of it -- that is when it
+      # runs those steps. Attaching to an Excel somebody already had open
+      # (.connect) is never auto-created, so those steps never fire for it;
+      # quitting it out from under them would throw away their unsaved work.
+      def self.run(mode = :connect_or_create, **options)
+        xl = case mode
+             when :create             then create(**options)
+             when :connect            then connect(**options)
+             when :connect_or_create  then connect_or_create(**options)
+             else raise ArgumentError, "unknown mode #{mode.inspect}"
+             end
+        begin
+          yield xl
+        ensure
+          xl.ole_release
+        end
+      end
+
+      def initialize(proxy, client:, convert_paths: true)
+        @ole = proxy
+        @client = client
+        @convert_paths = convert_paths
+        # COM resolves names case-insensitively, so `xl.version` already
+        # reaches COM's own Version and returns e.g. "11.0" -- measured.
+        # Defining a `version` method here would only shadow that with
+        # something that does the same thing, so this class deliberately
+        # does not have one. Captured once here, rather than read fresh
+        # per lookup, so every Sheet/Book this object builds sees one
+        # stable answer without a round trip each time.
+        @version = @ole.Version
+      end
+
+      # Release the underlying Application. On the last user of an auto-created
+      # instance this is what quits Excel (the bridge runs DisplayAlerts=false
+      # then Quit); on a connected instance it simply detaches. Public because
+      # `run` is not the only way to get one of these, and a caller managing
+      # the lifecycle by hand needs the same call available.
+      def ole_release
+        @ole.ole_release
+      end
+
+      # Keep this Excel running after this program leaves -- e.g. a report left
+      # on screen for a human. Revokes the bridge's permission to quit it.
+      def leave_open
+        @ole.ole_leave_open
+      end
+
+      def [](*keys)
+        lookup(keys)
+      end
+
+      # Resolves the same way #[] does; raises unless that resolves all the
+      # way to a Range. `xl["Sheet1!"] = 0` silently filling a whole sheet
+      # is exactly the hazard this guards against -- a typo that stops at a
+      # sheet or a book is otherwise indistinguishable from that "fill
+      # everything" request (Spec Sec 4.5).
+      def []=(*args)
+        value = args.pop
+        target = lookup(args)
+        unless target.is_a?(Range)
+          raise ArgumentError,
+            "#{args.inspect} does not resolve to a range -- assignment needs an address " \
+            'with an explicit range; a bare sheet or workbook lookup is get-only'
+        end
+        target.write(value)
+      end
+
+      # COM's Application has no Show/Hide (measured: both answer
+      # DISP_E_UNKNOWNNAME), so defining these does not shadow a working
+      # COM call the way a single-word name with a real COM counterpart
+      # would (Sec 4.6).
+      def show
+        @ole.Visible = true
+      end
+
+      def hide
+        @ole.Visible = false
+      end
+
+      # Suppresses Excel's save/overwrite/etc. modal prompts for the
+      # duration of the block, then restores whatever DisplayAlerts was
+      # set to beforehand -- not a hardcoded true. msoffice.rb's own
+      # version restores a hardcoded true in its ensure, which would
+      # silently turn a caller's own `DisplayAlerts = false` back on the
+      # moment this method returns; reading the value first instead means
+      # an outer caller who had already turned it off keeps it off.
+      #
+      # The underscore makes the name safe regardless of whether COM has a
+      # same-named member (Sec 4.6): `no_alert` would not resolve to
+      # anything on Application even as a single word, since COM does not
+      # strip underscores when matching names.
+      def no_alert
+        raise ArgumentError, 'no_alert needs a block -- the flag is restored when it returns' unless block_given?
+
+        previous = @ole.DisplayAlerts
+        begin
+          @ole.DisplayAlerts = false
+          yield
+        ensure
+          restore(:DisplayAlerts=, previous)
+        end
+      end
+
+      # Same restore-what-was-there discipline as #no_alert, for screen
+      # redraws instead of alert dialogs.
+      def no_update
+        raise ArgumentError, 'no_update needs a block -- the flag is restored when it returns' unless block_given?
+
+        previous = @ole.ScreenUpdating
+        begin
+          @ole.ScreenUpdating = false
+          yield
+        ensure
+          restore(:ScreenUpdating=, previous)
+        end
+      end
+
+      private
+
+      # Put a flag back, and never let failing to do so become the caller's
+      # problem.
+      #
+      # An exception raised inside `ensure` REPLACES whatever the block
+      # raised. A failed restore would therefore destroy the caller's own
+      # error and report the cleanup instead.
+      #
+      # And the ordinary reason a restore fails is that the block ended the
+      # very thing being restored: an Application that quits or disconnects
+      # mid-block (whether from a caller's own `no_alert { xl.Quit }`, or
+      # from underneath this process entirely) leaves nothing for `no_alert`'s
+      # ensure to put DisplayAlerts back on. There is no state left to
+      # restore, and nothing worth telling anyone.
+      #
+      # Swallowed unconditionally rather than only for a "the object is
+      # gone" error: over this bridge that arrives as a RemoteError wrapping
+      # an HRESULT string (0x800706BE is a normal transient right after
+      # Quit), so telling the two apart means matching on those strings --
+      # brittle, and beside the point, since raising out of `ensure` is
+      # wrong even when the failure really is transient.
+      def restore(setter, value)
+        @ole.public_send(setter, value)
+      rescue StandardError
+        nil
+      end
+
+      def lookup(keys)
+        return cell_range(*keys) if keys.length == 2 && keys.all? { |k| k.is_a?(::Integer) }
+
+        unless keys.length == 1 && keys.first.is_a?(::String)
+          raise ArgumentError, "unsupported index #{keys.inspect}"
+        end
+
+        str = keys.first
+        addr = Address.parse(str, @version)
+
+        # Not an address at all -- msoffice.rb's own fallback: treat the
+        # whole string as a raw worksheet name. This is exactly why
+        # Address.parse returns nil instead of raising.
+        return Sheet.new(@ole.Worksheets.Item(str), version: @version) if addr.nil?
+
+        resolve(addr, str)
+      end
+
+      # xl[row, col]: Cells on the active sheet. Goes through #resolve's
+      # same no-Select path (via the Sheet it builds), one Application
+      # round trip for ActiveSheet plus whatever Sheet#[] costs.
+      def cell_range(row, col)
+        Sheet.new(active_worksheet(@ole, "xl[#{row}, #{col}]"), version: @version)[row, col]
+      end
+
+      # Resolves a parsed Address against this Application.
+      #
+      # Deliberately never calls Select. msoffice.rb has to, because it
+      # reaches a range through Application.Range, which addresses
+      # whatever sheet happens to be active. Resolving against the
+      # worksheet object itself needs no active state, so a read here does
+      # not mutate the caller's selection as a side effect, and it costs
+      # one fewer round trip. Measured against a live Excel 11:
+      # `book.Worksheets.Item(1).Range('A1').Value` left ActiveSheet
+      # exactly where it was, both before and after.
+      def resolve(addr, str)
+        workbook_ole = addr.workbook.nil? ? nil : resolve_workbook(addr.workbook, str)
+
+        worksheet_part = addr.worksheet
+        # A bare range ("A1:B2", no "!") names no worksheet at all -- it
+        # still needs one to be looked up against, so it implicitly means
+        # the active sheet, the same way xl[row, col] does.
+        worksheet_part = '' if worksheet_part.nil? && addr.range?
+
+        if worksheet_part
+          worksheet_ole = resolve_worksheet(worksheet_part, workbook_ole || @ole, str)
+          sheet = Sheet.new(worksheet_ole, version: @version)
+          return addr.range? ? sheet[addr.range] : sheet
+        end
+
+        # The grammar only leaves worksheet_part nil when addr is the bare
+        # "[workbook]" form -- Address#worksheet is nil and Address#range?
+        # is false together only there -- so workbook_ole is always set by
+        # this point (Sec 4.5, get-only for a lookup with no range).
+        Book.new(workbook_ole, client: @client, version: @version, convert_paths: @convert_paths)
+      end
+
+      def resolve_workbook(part, str)
+        if part.empty?
+          active_workbook(str)
+        elsif part.casecmp?(':new')
+          @ole.Workbooks.Add
+        else
+          @ole.Workbooks.Item(part)
+        end
+      end
+
+      def resolve_worksheet(part, container, str)
+        if part.empty?
+          active_worksheet(container, str)
+        elsif part.casecmp?(':new')
+          worksheets = container.Worksheets
+          worksheets.Add(After: worksheets.Item(worksheets.Count))
+        elsif part.casecmp?(':first')
+          container.Worksheets.Item(1)
+        elsif part.casecmp?(':last')
+          worksheets = container.Worksheets
+          worksheets.Item(worksheets.Count)
+        elsif part.match?(/\A\d+\z/)
+          container.Worksheets.Item(part.to_i)
+        else
+          container.Worksheets.Item(part)
+        end
+      end
+
+      # ActiveWorkbook/ActiveSheet are nil on a fresh Excel with nothing
+      # open yet (measured: Workbooks.Count == 0 makes both nil). Without
+      # this check that turns into a NoMethodError raised from deep inside
+      # this class instead of something a caller can act on.
+      #
+      # RuntimeError rather than ArgumentError: the address string itself
+      # was fine -- it is the application's current state (no open
+      # workbook/sheet) that cannot satisfy it.
+      def active_workbook(str)
+        @ole.ActiveWorkbook or raise RuntimeError, "no active workbook -- #{str.inspect} needs one open"
+      end
+
+      def active_worksheet(container, str)
+        container.ActiveSheet or raise RuntimeError, "no active worksheet -- #{str.inspect} needs one open"
+      end
+    end
+  end
+end

data/lib/wineole/msoffice/format.rb

@@ -0,0 +1,362 @@
+require_relative 'color'
+
+module WineOLE
+  module MSOffice
+    # The one place that knows how a format key maps onto a COM property.
+    #
+    # Keyword arguments rather than a chain, because formatting needs three
+    # states and a chain has two: an absent key means "leave it alone", and
+    # `false` means "explicitly turn it off". Those are different operations
+    # and both are ordinary. The implementation therefore asks `key?` and
+    # never leans on `opts[:bold]` being nil.
+    #
+    # Every number here was measured against a live Excel 11 rather than
+    # recalled; see the spec's table.
+    module Format
+      UNDERLINE = {none: -4142, single: 2, double: -4119}.freeze
+      ALIGN = {general: 1, left: -4131, center: -4108, right: -4152, justify: -4130}.freeze
+      VALIGN = {top: -4160, center: -4108, bottom: -4107}.freeze
+      private_constant :UNDERLINE, :ALIGN, :VALIGN
+
+      XL_NONE = -4142
+      XL_AUTOMATIC = -4105
+      XL_GENERAL_FORMAT_NAME = 26
+      private_constant :XL_NONE, :XL_AUTOMATIC, :XL_GENERAL_FORMAT_NAME
+
+      FONT_KEYS = %i[bold italic underline size color].freeze
+      INTERIOR_KEYS = %i[background].freeze
+      RANGE_KEYS = %i[align valign wrap number_format].freeze
+      KEYS = (FONT_KEYS + INTERIOR_KEYS + RANGE_KEYS + %i[border]).freeze
+      private_constant :FONT_KEYS, :INTERIOR_KEYS, :RANGE_KEYS, :KEYS
+
+      # One knob for the caller, two properties for Excel. Excel keeps the
+      # line pattern (LineStyle) and its thickness (Weight) apart, which
+      # means `:thin` and `:dash` live in different properties even though a
+      # caller thinks of both as "what the line looks like". Measured pairs:
+      BORDER_STYLE = {
+        none:     {line: -4142, weight: nil},
+        hairline: {line: 1,     weight: 1},
+        thin:     {line: 1,     weight: 2},
+        medium:   {line: 1,     weight: -4138},
+        thick:    {line: 1,     weight: 4},
+        dash:     {line: -4115, weight: 2},
+        dot:      {line: -4118, weight: 2},
+      }.freeze
+      private_constant :BORDER_STYLE
+
+      EDGE = {left: 7, top: 8, bottom: 9, right: 10, inside_v: 11, inside_h: 12}.freeze
+      OUTLINE_EDGES = %i[left top bottom right].freeze
+      ALL_EDGES = %i[left top bottom right inside_v inside_h].freeze
+      BORDER_HASH_KEYS = %i[edges style color].freeze
+      private_constant :EDGE, :OUTLINE_EDGES, :ALL_EDGES, :BORDER_HASH_KEYS
+
+      # Two passes on purpose. Everything is validated and converted into the
+      # values COM wants *before* the first write, so a bad key or a bad
+      # value leaves the range exactly as it was. Validating as it went would
+      # mean `format(bold: true, align: :middle)` raises with the range
+      # already bold -- and a caller who sees an exception reasonably reads
+      # it as "nothing happened".
+      #
+      # `translate` may read from COM (`:general` asks the Application for
+      # the local name of the General format). A read changes nothing, so
+      # the invariant that matters -- no write before validation finishes --
+      # still holds.
+      def self.apply(ole, opts)
+        reject_unknown_keys(opts)
+        opts = opts.reject { |_k, v| v.nil? } # nil means "not specified"
+        font, interior, range, border = translate(ole, opts)
+
+        # Each `ole.Font` is its own round trip, so it is fetched once and
+        # only when there is something to write to it.
+        write_to(ole.Font, font) unless font.empty?
+        write_to(ole.Interior, interior) unless interior.empty?
+        write_to(ole, range)
+        write_border(ole, border) unless border.nil?
+        nil
+      end
+
+      def self.write_to(target, assignments)
+        assignments.each { |setter, value| target.public_send(setter, value) }
+      end
+      private_class_method :write_to
+
+      # Returns four values: three lists of [setter, value] -- for Font, for
+      # Interior and for the Range itself -- plus a border plan (or nil) for
+      # `write_border`, which does not fit the [setter, value] shape because
+      # it may need both a bulk assignment and a per-edge loop. Raises
+      # rather than returning anything partial.
+      def self.translate(ole, opts)
+        font = []
+        interior = []
+        range = []
+
+        font << [:Bold=, boolean(opts[:bold], :bold)] if opts.key?(:bold)
+        font << [:Italic=, boolean(opts[:italic], :italic)] if opts.key?(:italic)
+        font << [:Underline=, underline(opts[:underline])] if opts.key?(:underline)
+        font << [:Size=, size(opts[:size])] if opts.key?(:size)
+        if opts.key?(:color)
+          font << if opts[:color] == false
+                    [:ColorIndex=, XL_AUTOMATIC]
+                  else
+                    [:Color=, colour(opts[:color], :color)]
+                  end
+        end
+
+        if opts.key?(:background)
+          interior << if opts[:background] == false
+                        # Not `Color = white`: measured, a cleared cell and a
+                        # white-painted cell both report Color 16777215, but
+                        # the painted one keeps ColorIndex 2 and Pattern 1 --
+                        # it is still filled, prints as a fill, and hides
+                        # gridlines.
+                        [:ColorIndex=, XL_NONE]
+                      else
+                        [:Color=, colour(opts[:background], :background)]
+                      end
+        end
+
+        range << [:HorizontalAlignment=, fetch(ALIGN, opts[:align], :align)] if opts.key?(:align)
+        range << [:VerticalAlignment=, fetch(VALIGN, opts[:valign], :valign)] if opts.key?(:valign)
+        range << [:WrapText=, boolean(opts[:wrap], :wrap)] if opts.key?(:wrap)
+        if opts.key?(:number_format)
+          range << [:NumberFormat=, number_format(ole, opts[:number_format])]
+        end
+
+        border = opts.key?(:border) ? translate_border(opts[:border]) : nil
+
+        [font, interior, range, border]
+      end
+      private_class_method :translate
+
+      # Validates and resolves everything; touches no COM.
+      def self.translate_border(spec)
+        spec = normalize_border(spec)
+        style = fetch(BORDER_STYLE, spec[:style], 'border style')
+        # Named line_colour, not colour: a local called `colour` would shadow
+        # the method of that name for the rest of this body.
+        line_colour = spec.key?(:color) ? colour(spec[:color], 'border color') : nil
+
+        {indexes: expand_edges(spec[:edges]), line: style[:line],
+         weight: style[:weight], colour: line_colour}
+      end
+      private_class_method :translate_border
+
+      # `ole.Borders` is a round trip like Font and Interior: fetched once,
+      # with Item() called off it -- except when every edge is being set, in
+      # which case an assignment straight to the Borders collection replaces
+      # the whole per-edge loop.
+      #
+      # Measured against a live Excel on a multi-cell range, an assignment on
+      # Borders itself reaches all six edges -- including inside_v and
+      # inside_h -- in one COM call each: LineStyle, Weight and Color each
+      # touch all six for the price of one round trip. 2.3 ms against 10.0 ms
+      # for the per-edge Item() loop below. That is exactly why it must never
+      # be used for :outline: it would silently draw the inside edges too.
+      # Keyed off the resolved index set rather than the :all symbol, so an
+      # explicit list of all six edges gets the fast path as well.
+      ALL_EDGE_INDEXES = ALL_EDGES.map { |name| EDGE.fetch(name) }.sort.freeze
+      private_constant :ALL_EDGE_INDEXES
+
+      def self.write_border(ole, plan)
+        indexes = plan[:indexes].uniq
+        return if indexes.empty?
+
+        borders = ole.Borders
+
+        if indexes.sort == ALL_EDGE_INDEXES
+          borders.LineStyle = plan[:line]
+          return if plan[:weight].nil?
+
+          borders.Weight = plan[:weight]
+          borders.Color = plan[:colour] unless plan[:colour].nil?
+          return
+        end
+
+        indexes.each do |index|
+          edge = borders.Item(index)
+          edge.LineStyle = plan[:line]
+          # Nothing to weigh or colour when the line is being removed.
+          next if plan[:weight].nil?
+
+          edge.Weight = plan[:weight]
+          edge.Color = plan[:colour] unless plan[:colour].nil?
+        end
+      end
+      private_class_method :write_border
+
+      def self.normalize_border(spec)
+        hash = case spec
+               when false     then {edges: :all, style: :none}
+               when ::Symbol  then {edges: spec, style: :thin}
+               when ::Array   then {edges: spec, style: :thin}
+               when ::Hash    then spec
+               else
+                 raise ArgumentError,
+                   'border: expected :all, :outline, an edge name, an array of edge ' \
+                   "names, false, or a hash, got #{spec.inspect}"
+               end
+        # Checked against the hash as given, before nils are dropped -- same
+        # order as `apply`'s top-level keys, so a misspelled key with a nil
+        # value is still caught rather than silently absorbed.
+        unknown = hash.keys - BORDER_HASH_KEYS
+        unless unknown.empty?
+          raise ArgumentError,
+            "border: unknown key#{'s' if unknown.length > 1} " \
+            "#{unknown.map(&:inspect).join(', ')} -- known keys are #{BORDER_HASH_KEYS.join(', ')}"
+        end
+
+        # nil means "not specified" everywhere else in this module (`apply`
+        # drops nil top-level values before anything is validated); a caller
+        # writing `style: nil` explicitly is asking for the same thing as
+        # omitting `style`, not for an override that beats the default.
+        {style: :thin}.merge(hash.compact)
+      end
+      private_class_method :normalize_border
+
+      def self.expand_edges(edges)
+        names = case edges
+                # Only a hash form reaches here without edges: having been
+                # filled in -- the shorthands (:all, an edge name, an array,
+                # false) all set it themselves in normalize_border. Naming
+                # the missing key beats bad_edges_message's "got nil", which
+                # reads as a value the caller never wrote.
+                when nil
+                  raise ArgumentError,
+                    'border: a hash needs an edges: key, e.g. ' \
+                    'border: {edges: :all, style: :thick}'
+                when :all      then ALL_EDGES
+                when :outline  then OUTLINE_EDGES
+                when ::Symbol  then [edges]
+                # :all and :outline expand here too, not just on their own --
+                # the error message below promises "an array of those", and
+                # "those" includes the shorthands. This also makes something
+                # like [:outline, :inside_h] expressible.
+                when ::Array
+                  edges.flat_map do |edge|
+                    case edge
+                    when :all     then ALL_EDGES
+                    when :outline then OUTLINE_EDGES
+                    else [edge]
+                    end
+                  end
+                else raise ArgumentError, bad_edges_message(edges)
+                end
+        names.map do |name|
+          EDGE.fetch(name) { raise ArgumentError, bad_edges_message(name) }
+        end
+      end
+      private_class_method :expand_edges
+
+      # One message for both failures, and it names the shorthands as well as
+      # the edges -- someone who typed :diagonal needs to learn that :all and
+      # :outline exist, which a bare list of EDGE's keys would not tell them.
+      def self.bad_edges_message(value)
+        "border: expected :all, :outline, one of " \
+        "#{EDGE.keys.map(&:inspect).join(', ')}, or an array of those, " \
+        "got #{value.inspect}"
+      end
+      private_class_method :bad_edges_message
+
+      # Before any COM call, so a typo leaves the sheet exactly as it was
+      # rather than half-formatted.
+      def self.reject_unknown_keys(opts)
+        unknown = opts.keys - KEYS
+        return if unknown.empty?
+
+        raise ArgumentError,
+          "unknown format key#{'s' if unknown.length > 1} " \
+          "#{unknown.map(&:inspect).join(', ')} -- known keys are #{KEYS.join(', ')}"
+      end
+      private_class_method :reject_unknown_keys
+
+      # A nil never reaches here -- `apply` drops nil values first, because
+      # nil means "I have no value for this", which is the same thing as not
+      # passing the key. That matters: measured, assigning nil to a COM
+      # boolean property sets it to *false*, so a nil reaching COM would
+      # silently un-bold a range whose caller simply did not know.
+      def self.boolean(value, key)
+        return value if value == true || value == false
+
+        raise ArgumentError,
+          "#{key}: expected true or false, got #{value.inspect}. " \
+          'Omit the key entirely to leave this attribute alone'
+      end
+      private_class_method :boolean
+
+      # Excel's own font size range. Outside it, COM fails with a message
+      # about the Font class rather than about the number.
+      SIZE_RANGE = (1..409).freeze
+      private_constant :SIZE_RANGE
+
+      def self.size(value)
+        unless value.is_a?(::Numeric) && SIZE_RANGE.cover?(value)
+          raise ArgumentError,
+            "size: expected a number in 1..409 (Excel's own range), got #{value.inspect}"
+        end
+
+        value
+      end
+      private_class_method :size
+
+      def self.underline(value)
+        case value
+        when true  then UNDERLINE.fetch(:single)
+        when false then UNDERLINE.fetch(:none)
+        else fetch(UNDERLINE, value, :underline)
+        end
+      end
+      private_class_method :underline
+
+      # A raw COM colour integer is ambiguous here: 255 could mean the
+      # caller's #0000FF or Excel's own value for red. Refuse rather than
+      # guess -- the same stance `write` takes on a wrong-shaped array.
+      def self.colour(value, key)
+        if value.is_a?(::Numeric)
+          raise ArgumentError,
+            "#{key}: expected '#RRGGBB', got the number #{value.inspect}. " \
+            'A raw COM colour is ambiguous here -- pass a hex string, or use ' \
+            'WineOLE::MSOffice::Color[...] with .ole to reach COM directly'
+        end
+
+        begin
+          Color[value]
+        rescue ArgumentError => e
+          raise ArgumentError, "#{key}: #{e.message}"
+        end
+      end
+      private_class_method :colour
+
+      # 'General' is the one format code that cannot be written: measured, it
+      # fails outright on a localized Excel, where the format has a
+      # translated name instead -- and that translated spelling is not
+      # portable either. Application.International(26) returns whichever
+      # one this Excel wants.
+      def self.number_format(ole, value)
+        case value
+        when :general then ole.Application.International(XL_GENERAL_FORMAT_NAME)
+        when :text then '@'
+        when ::String
+          if value.casecmp?('General')
+            ole.Application.International(XL_GENERAL_FORMAT_NAME)
+          else
+            value
+          end
+        else
+          raise ArgumentError,
+            "number_format: expected a format code string, :general or :text, " \
+            "got #{value.inspect}"
+        end
+      end
+      private_class_method :number_format
+
+      def self.fetch(table, value, key)
+        table.fetch(value) do
+          raise ArgumentError,
+            "#{key}: expected one of #{table.keys.map(&:inspect).join(', ')}, " \
+            "got #{value.inspect}"
+        end
+      end
+      private_class_method :fetch
+    end
+  end
+end