wineole 0.1.0 → 0.2.0

data/lib/wineole/events.rb

@@ -0,0 +1,353 @@
+require_relative 'errors'
+
+module WineOLE
+  # COM events for one object, reached as `proxy.ole_events`.
+  #
+  # Registering a callback is the only thing a caller does. Everything under
+  # it is DERIVED from that. The bridge-side subscription and the COM Advise
+  # beneath it belong to THIS object: they are put up by its first callback
+  # and taken back down by the last one removed from it. The sink on the
+  # connection and the dispatcher thread belong to the CONNECTION, so they
+  # follow the same rule one level up -- up with the first callback anywhere
+  # on the client, down with the last one anywhere on it (see Dispatcher).
+  # Making any of them a separate control would allow the state where a
+  # callback is registered and the event never arrives, with nothing to show
+  # for it.
+  #
+  # That invariant is a claim about ORDER as much as about bookkeeping, so
+  # `on`, `off` and `close` hold @wire_mutex across "decide, then tell the
+  # bridge". Deciding under one lock and writing the wire outside it lets two
+  # threads reach the bridge in the opposite order to the one they decided
+  # in: a subscribe landing after the unsubscribe that was meant to follow it
+  # leaves a registered callback whose event can never arrive, and the mirror
+  # case leaves the bridge advised with nothing to deliver to. Measured, on
+  # the code before this lock existed: wire order subscribe, subscribe,
+  # unsubscribe with one callback still registered.
+  #
+  # Callbacks run on one dispatcher thread PER CONNECTION, in arrival order,
+  # one at a time -- so two objects on one client never run their callbacks
+  # concurrently, and a caller needs no lock between them. That thread is not
+  # here: it belongs to the connection, and this object attaches itself to it
+  # for as long as it has a registration (see Dispatcher). They may call COM
+  # freely -- that is the point -- because the client's reader thread is a
+  # different thread and stays free to read the response. A slow callback
+  # delays the events behind it, on every object on the connection.
+  #
+  # The dispatcher thread survives anything a callback or a malformed frame
+  # can throw; see Dispatcher.run.
+  class Events
+    # NOT a Struct, and not for tidiness: a Struct has value equality, so two
+    # subscriptions with the same name, block and flag are `==` without being
+    # the same registration -- registering one proc twice for an event is
+    # enough. `off(first)` would then remove the second one too (Array#delete
+    # removes every match), unsubscribe, and leave the caller with a
+    # Subscription that never fires again and nothing said about it. A
+    # registration is the thing itself, so identity is its equality.
+    #
+    # `args` is per callback, but the wire has one flag per event: what goes
+    # on it is the union (see `effective_args`).
+    class Subscription
+      attr_reader :name, :block, :args
+
+      def initialize(name, block, args)
+        @name = name
+        @block = block
+        @args = args
+      end
+    end
+
+    def initialize(client, handle)
+      @client = client
+      @handle = handle
+      # A plain Hash, deliberately not `Hash.new { |h, k| h[k] = [] }`: with a
+      # default block, merely LOOKING an event name up writes a permanent key
+      # -- an arriving event nobody subscribed to, or an `off` for a name that
+      # was never `on`, would grow this table for the life of the connection.
+      # A name is added when a callback is registered for it and removed when
+      # the last one goes.
+      @subs = {}
+      @mutex = Mutex.new
+      # Held across the whole of `on`/`off`/`close` -- the decision AND the
+      # call that carries it out -- and always acquired BEFORE @mutex, never
+      # while holding it. @mutex is therefore never held across a wire round
+      # trip, which is what keeps `deliver`'s brief acquisition of it off the
+      # bridge's response time. A callback calling `off` from the dispatcher
+      # waits for at most one round trip and cannot deadlock: the thread it
+      # waits for needs nothing from the dispatcher to finish.
+      #
+      # The connection's Dispatcher has a mutex of its own, and it is taken
+      # under this one and never under @mutex: the order is @wire_mutex ->
+      # Dispatcher#@mutex (in `arm`/`disarm`) and @wire_mutex -> @mutex
+      # (everywhere else), so those two are never held together. The
+      # Dispatcher takes none of these, and drops its own before it calls
+      # `deliver`, which is what lets a callback register on another object.
+      @wire_mutex = Mutex.new
+      @on_error = nil
+      # Whether this object currently has a place on the connection's
+      # dispatcher. It stands where @sink used to: the dispatcher and its
+      # sink are the connection's now, shared with every other object on it,
+      # so "is it up?" is no longer a question this object can answer by
+      # looking at what it owns. Read and written under @wire_mutex only --
+      # `arm` and `disarm` are both called with it held -- which is what
+      # keeps `disarm` idempotent, and it has to be: it is reached from
+      # `off`'s ensure, from `close`, and from `on`'s rescue, on an object
+      # that may never have been armed at all.
+      @attached = false
+    end
+
+    # `args: false` tells the bridge not to mint handles for this event's
+    # object arguments. The callback is then called with no arguments at all
+    # -- measured: a block written `|sheet, range|` gets nil for both. Worth
+    # it for a high-frequency event you only want to count.
+    #
+    # The bridge holds ONE flag per event, so what goes on the wire is the
+    # union: arguments are minted while any callback for that event wants
+    # them. Registering an `args: true` callback next to an `args: false` one
+    # therefore re-subscribes rather than leaving the first registration's
+    # flag standing -- measured on Excel before this was here: the second
+    # callback was handed nil, having asked for the objects, and nothing said
+    # so. A callback that asked for `args: false` and gets them anyway
+    # because a sibling wanted them is the harmless direction of the same
+    # trade; it can ignore them.
+    def on(name, args: true, &block)
+      raise ArgumentError, 'on needs a block -- there is nothing to call otherwise' unless block
+
+      sub = Subscription.new(name, block, args)
+      @wire_mutex.synchronize do
+        # Before the subscribe, never after: the bridge advises the COM
+        # source as the subscribe is handled, so an event can be on its way
+        # back before the call returns. Arming afterwards would drop it.
+        arm
+        wanted = @mutex.synchronize do
+          before = effective_args(name)
+          (@subs[name] ||= []) << sub
+          after = effective_args(name)
+          after == before ? nil : after
+        end
+        begin
+          @client.call('subscribe', {handle: @handle, event: name, args: wanted}) unless wanted.nil?
+        rescue StandardError
+          # A subscribe the bridge refused -- an object that is not an event
+          # source is the ordinary case -- must not leave the callback
+          # registered. Keeping it would produce exactly the state this class
+          # exists to make unreachable: a callback that is never called, with
+          # the error already raised and gone.
+          disarm if @mutex.synchronize { drop(name, sub); @subs.empty? }
+          raise
+        end
+      end
+      sub
+    end
+
+    # Takes either a name (every callback for it) or one Subscription.
+    def off(name_or_sub)
+      @wire_mutex.synchronize do
+        sub = name_or_sub.is_a?(Subscription) ? name_or_sub : nil
+        name = sub ? sub.name : name_or_sub.to_s
+        before, after, empty = @mutex.synchronize do
+          was = effective_args(name)
+          drop(name, sub)
+          [was, effective_args(name), @subs.empty?]
+        end
+        # Nothing was registered for this event, so nothing was derived from
+        # it either. `after.nil?` alone cannot tell "the last callback just
+        # went" from "there was never one", and an unsubscribe for a
+        # subscription that does not exist is a round trip that says nothing.
+        next if before.nil?
+
+        begin
+          if after.nil?
+            # The last callback for this event is gone, so the subscription
+            # that only existed to feed it goes too -- and with the last name
+            # for the object, the COM Advise underneath it.
+            @client.call('unsubscribe', {handle: @handle, event: name})
+          elsif after != before
+            # Callbacks remain, but the one that wanted arguments was among
+            # those removed: stop paying for handles nobody asked for.
+            @client.call('subscribe', {handle: @handle, event: name, args: after})
+          end
+        ensure
+          # In an ensure because the registry has already been emptied above:
+          # if the unsubscribe raised (a connection that has just gone is the
+          # ordinary case) the local half must still come down, or this
+          # object keeps a dispatcher thread and a sink entry on the client
+          # for the life of the connection with nothing left to deliver.
+          disarm if empty
+        end
+      end
+      self
+    end
+
+    # Every callback forgotten, every subscription and Advise released, the
+    # dispatcher stopped and the sink taken off the connection.
+    #
+    # `off`-ing the last callback does all of this already -- that is the
+    # derivation this class is built on, and it is why there is no `close`
+    # you are REQUIRED to call. This is the bulk form, for a caller who does
+    # not want to remember which names it registered. `on` afterwards works
+    # exactly as the first one did: the object arms itself again.
+    def close
+      @wire_mutex.synchronize do
+        @mutex.synchronize { @subs.keys }.each do |name|
+          @mutex.synchronize { drop(name, nil) }
+          begin
+            @client.call('unsubscribe', {handle: @handle, event: name})
+          rescue StandardError
+            # A connection that has already gone has already unadvised
+            # everything on it. Unlike `off`, this is not reported: `close`
+            # is what a caller reaches for when it is done, and the local
+            # half it exists to release comes down either way.
+            nil
+          end
+        end
+        disarm
+      end
+      self
+    end
+
+    # ONE error handler per object, last writer wins -- deliberately not
+    # `on`'s append. An error handler is not a subscription: it has no
+    # arguments to negotiate, nothing is derived from it, and there is
+    # nothing for a second one to add that the first cannot do. That it
+    # returns `self` rather than a Subscription is the same statement, and
+    # there is no `off_error` for the same reason -- `on_error { }` replaces
+    # it with one that does nothing.
+    def on_error(&block)
+      @mutex.synchronize { @on_error = block }
+      self
+    end
+
+    # Tests only. Production code never needs any of these, because callbacks
+    # are the delivery mechanism.
+    #
+    # The queue and the thread these two ask about belong to the connection
+    # now, so both are the Dispatcher's answers. Kept here as delegators
+    # because a test that has an `Events` and asks whether ITS callbacks are
+    # still being delivered is asking the right question of the right object
+    # -- and because the answer is the same one it always was.
+    def stopped_for_test?(seconds)
+      @client.dispatcher.stopped_for_test?(seconds)
+    end
+
+    def drain_for_test(seconds = 5)
+      @client.dispatcher.drain_for_test(seconds)
+      self
+    end
+
+    def registered_names_for_test
+      @mutex.synchronize { @subs.keys }
+    end
+
+    private
+
+    # Takes this object's place on the connection: the frames for its handle
+    # start being routed to it, and the connection's dispatcher thread and
+    # sink go up if this is the first object to ask for them. Derived from
+    # there being a callback at all, so an `ole_events` a caller merely
+    # touched costs nothing anywhere. Called from `on` under @wire_mutex,
+    # which is what serializes it against `disarm`.
+    def arm
+      return if @attached
+
+      @client.dispatcher.attach(@handle, self)
+      @attached = true
+    end
+
+    # The other half of `arm`, once the last callback is gone: a registered
+    # callback is the only reason for any of this to exist. Without it an
+    # Events that has had every callback removed still holds a place on the
+    # connection's dispatcher and an entry the reader walks for every frame
+    # on it -- measured: 50 proxies that registered one callback and removed
+    # it left 51 live threads and 50 sink entries, all of them until the
+    # connection closed. The thread and the sink themselves only go with the
+    # LAST object to leave; that decision belongs to the Dispatcher, which is
+    # the only thing that knows whether any other object still has callbacks.
+    def disarm
+      return unless @attached
+
+      @attached = false
+      # By identity: the Dispatcher removes this object's routing entry and
+      # nobody else's.
+      @client.dispatcher.detach(@handle, self)
+    end
+
+    # What the wire flag for `name` should be: nil when no callback is
+    # registered for it at all, otherwise true if any of them wants the
+    # event's object arguments minted. Call it under @mutex.
+    def effective_args(name)
+      subs = @subs[name]
+      return nil if subs.nil? || subs.empty?
+
+      subs.any? { |sub| sub.args }
+    end
+
+    # Removes one subscription, or every callback for `name` when `sub` is
+    # nil, and takes the name out of the table when nothing is left for it.
+    # Call it under @mutex.
+    #
+    # `equal?`, not `==`: `off` removes the registration it was handed and no
+    # other. See Subscription.
+    def drop(name, sub)
+      list = @subs[name]
+      return if list.nil?
+
+      sub.nil? ? list.clear : list.reject! { |s| s.equal?(sub) }
+      @subs.delete(name) if list.empty?
+    end
+
+    # One frame, to the callbacks registered for its name. Called by the
+    # connection's Dispatcher, which routed it here by handle, and private
+    # for the reason the whole class exists: a registered callback is the
+    # only way in, and a public `deliver` would say otherwise. The frame's
+    # argument handles are given back by the Dispatcher's `route`, in an
+    # ensure that covers a frame this raised on as well as one that reached
+    # nobody at all.
+    def deliver(frame)
+      subs = @mutex.synchronize { (@subs[frame['event']] || []).dup }
+      args = build_args(frame['args'])
+      subs.each do |sub|
+        begin
+          sub.block.call(*args)
+        rescue Exception => e # rubocop:disable Lint/RescueException
+          # Everything, for the reason Dispatcher.run catches everything: this
+          # thread is the whole delivery mechanism, and a callback raising
+          # something outside StandardError must not take the next callback,
+          # the next event and every later release down with it.
+          report(e, frame)
+        end
+      end
+    end
+
+    def build_args(raw)
+      return [] if raw.nil?
+
+      # The same decode an invoke's result goes through, so an event argument
+      # that is an object arrives as a Proxy and one that is a date arrives
+      # as a Time -- a second, private copy of that walk here is how those
+      # two answers drift apart.
+      raw.map { |v| Proxy.decode(@client, v) }
+    end
+
+    # Never raises. It is called from the dispatcher's own rescue, so an
+    # exception out of here is the one thing that could still end the thread.
+    def report(err, frame)
+      handler = @mutex.synchronize { @on_error }
+      event = frame.is_a?(Hash) ? frame['event'] : nil
+      begin
+        if handler
+          handler.call(err, frame)
+        else
+          warn "wineole: #{event} callback raised #{err.class}: #{err.message}"
+        end
+      rescue Exception => e # rubocop:disable Lint/RescueException
+        # An on_error that itself raises must not recurse, and must not be
+        # able to kill the dispatcher either -- its own rescue was
+        # StandardError once, and an on_error raising past that was a third
+        # way to lose every later event in silence.
+        warn "wineole: on_error raised #{e.class} while reporting #{err.class}"
+      end
+    rescue Exception # rubocop:disable Lint/RescueException
+      nil # even $stderr being gone must not end the dispatcher
+    end
+  end
+end

data/lib/wineole/msoffice/address.rb

@@ -0,0 +1,67 @@
+module WineOLE
+  module MSOffice
+    # Parses the addressing DSL this wrapper inherits from msoffice.rb:
+    #
+    #   "[Book1]Sheet1!A1:B2"   "[:new]"   ":new!"   ":first!A1"   "A1:B2"
+    #
+    # Touches no COM: it is a pure string parser, so it can be exercised
+    # without Excel running.
+    #
+    # The patterns come from msoffice.rb, which encodes Excel's actual grid
+    # limits (IV/65536 for Excel 11, XFD/1048576 for 12+). Both column
+    # patterns were checked against every column up to their limit and are
+    # exact -- and they are the harder half.
+    #
+    # The two row patterns needed a fix, carried here. Every nested digit
+    # range started at 1 where it should start at 0: the leading digit's
+    # "no leading zero" rule was carried down to positions the digits above
+    # had already constrained. That dropped row 65530 outright, and 11,111
+    # rows of the 1048576 grid. Both are exhaustively verified now, and
+    # test_every_row_in_the_grid_parses is what keeps them that way.
+    class Address
+      PTN_A_IV = /[A-H]?[A-Z]|I[A-V]/i
+      PTN_ABS_A_IV = /\$?#{PTN_A_IV}/
+      PTN_1_65536 = /[1-9]\d{,3}|[1-5]\d{4}|6(?:[0-4]\d{3}|5(?:[0-4]\d{2}|5(?:[0-2]\d|3[0-6])))/
+      PTN_ABS_1_65536 = /\$?#{PTN_1_65536}/
+      PTN_ABS_A1_IV65536 = /#{PTN_ABS_A_IV}#{PTN_ABS_1_65536}/
+      PTN_RANGE_LOCAL_XL11 = /(?<range>(?:#{PTN_ABS_A1_IV65536}:)?#{PTN_ABS_A1_IV65536}|#{PTN_ABS_A_IV}:#{PTN_ABS_A_IV}|#{PTN_ABS_1_65536}:#{PTN_ABS_1_65536})/
+      PTN_A_XFD = /[A-W]?[A-Z]{1,2}|X(?:[A-E][A-Z]|F[A-D])/i
+      PTN_ABS_A_XFD = /\$?#{PTN_A_XFD}/
+      PTN_1_1048576 = /[1-9]\d{,5}|10(?:[0-3]\d{4}|4(?:[0-7]\d{3}|8(?:[0-4]\d{2}|5(?:[0-6]\d|7[0-6]))))/
+      PTN_ABS_1_1048576 = /\$?#{PTN_1_1048576}/
+      PTN_ABS_A1_XFD1048576 = /#{PTN_ABS_A_XFD}#{PTN_ABS_1_1048576}/
+      PTN_RANGE_LOCAL_XL12 = /(?<range>(?:#{PTN_ABS_A1_XFD1048576}:)?#{PTN_ABS_A1_XFD1048576}|#{PTN_ABS_A_XFD}:#{PTN_ABS_A_XFD}|#{PTN_ABS_1_1048576}:#{PTN_ABS_1_1048576})/
+      PTN_WORKBOOK = /\[(?<workbook>(?i::new)|[^\[\]]*)\]/
+      PTN_WORKBOOK_WORKSHEET = /(?<worksheet_quote>'?)#{PTN_WORKBOOK}?(?<worksheet>(?i::(?:new|first|last))|(?:[^\[\]\\\:\*\'][^\[\]\\\:\*]*)?)\k<worksheet_quote>!/
+      PTN_XL11 = /\A(?:#{PTN_WORKBOOK}|#{PTN_WORKBOOK_WORKSHEET}?#{PTN_RANGE_LOCAL_XL11}?)\z/
+      PTN_XL12 = /\A(?:#{PTN_WORKBOOK}|#{PTN_WORKBOOK_WORKSHEET}?#{PTN_RANGE_LOCAL_XL12}?)\z/
+
+      attr_reader :workbook, :worksheet, :range
+
+      # Returns nil when the string is not an address at all, so a caller can
+      # fall back to treating it as a raw sheet name -- which is what
+      # msoffice.rb did.
+      def self.parse(str, excel_version)
+        pattern = excel_version.to_f >= 12 ? PTN_XL12 : PTN_XL11
+        m = pattern.match(str)
+        return nil if m.nil? || m.to_s.empty?
+
+        new(workbook: m[:workbook], worksheet: m[:worksheet], range: m[:range])
+      end
+
+      def initialize(workbook:, worksheet:, range:)
+        @workbook = workbook
+        @worksheet = worksheet
+        @range = range
+      end
+
+      # Whether this address names a range of cells. An address that stops at
+      # a sheet or a book is a lookup, not an assignment target -- see the
+      # spec on why `xl["Sheet1!"] = 0` filling a whole sheet is a hazard
+      # rather than a convenience.
+      def range?
+        !@range.nil?
+      end
+    end
+  end
+end

data/lib/wineole/msoffice/book.rb

@@ -0,0 +1,114 @@
+require 'tmpdir'
+require_relative '../proxy'
+require_relative 'passthrough'
+require_relative 'paths'
+require_relative 'sheet'
+require_relative 'vba_api'
+require_relative 'forms'
+
+module WineOLE
+  module MSOffice
+    # Wraps a COM Workbook.
+    #
+    # Name note (measured against a live Excel 11): `sheet`, `each_sheet`,
+    # `save_as` and `local_path` are all free -- COM answers
+    # DISP_E_UNKNOWNNAME for each. `close` is not: COM resolves member names
+    # case-insensitively, and `Workbook.Close` already exists. It is a
+    # deliberate shadow anyway (see #close below). `local_file` is free by
+    # the same construction as `save_as`: COM does not strip underscores
+    # when matching names, so it never collides with `Workbook.FullName`.
+    class Book
+      include Passthrough
+
+      # `convert_paths` is the caller's opt-out; whether converting is even
+      # meaningful is a separate question (a remote bridge's own filesystem
+      # means nothing to this machine). Combining them once here means a
+      # caller cannot talk a remote bridge into converting by passing
+      # `convert_paths: true` -- Paths.convertible? still says no.
+      def initialize(proxy, client:, version:, convert_paths: true)
+        @ole = proxy
+        @version = version
+        @convert_paths = convert_paths && Paths.convertible?(client: client)
+      end
+
+      # Worksheets, not Sheets: Sheets also includes chart sheets, which
+      # this wrapper's Sheet class does not model.
+      def sheet(name_or_index)
+        Sheet.new(@ole.Worksheets.Item(name_or_index), version: @version)
+      end
+
+      def each_sheet
+        return to_enum(:each_sheet) unless block_given?
+
+        worksheets = @ole.Worksheets
+        (1..worksheets.Count).each do |i|
+          yield Sheet.new(worksheets.Item(i), version: @version)
+        end
+      end
+
+      # Takes only the path. A caller needing FileFormat and the rest of
+      # COM's SaveAs arguments uses the passthrough `book.SaveAs(...)`.
+      def save_as(path)
+        target = @convert_paths ? Paths.to_wine(path) : path
+        @ole.SaveAs(target)
+      end
+
+      # COM's Workbook.Path is the *containing folder*, not the file --
+      # local_path deliberately names the same thing this wrapper's way, in
+      # Linux form. The file's own path is #local_file.
+      #
+      # An unsaved book's Path is "" -- Paths.to_local returns that
+      # unchanged without shelling out to winepath, so this never runs it
+      # for nothing.
+      def local_path
+        @convert_paths ? Paths.to_local(@ole.Path) : @ole.Path
+      end
+
+      # The file's own path, in Linux form -- what local_path is not.
+      # Gated by the same @convert_paths (loopback-only) rule as
+      # local_path; calling Paths.to_local(book.FullName) directly instead
+      # skips that gate and runs a local winepath over what may be a
+      # *remote* bridge's Wine path, silently producing a path that refers
+      # to a filesystem this machine does not have (Spec Sec 4.7: a wrong
+      # conversion that happens silently is worse than one that visibly
+      # does not happen).
+      #
+      # Measured against a live Excel 11: FullName is the file
+      # (`Z:\tmp\wineole_item_probe.xls` where Path is the folder,
+      # `Z:\tmp`); an unsaved book's FullName is the bare in-memory name
+      # ("Book1"), matching its Path of "".
+      def local_file
+        @convert_paths ? Paths.to_local(@ole.FullName) : @ole.FullName
+      end
+
+      # A deliberate shadow of COM's Workbook.Close. Close with no
+      # SaveChanges argument can raise a modal save-changes prompt, which
+      # under Wine is a hang; close(save: false) turns that hazard into an
+      # explicit parameter instead. The raw member stays reachable as
+      # `book.Close(...)` (exact PascalCase) and as `book.ole.Close(...)`.
+      def close(save: false)
+        @ole.Close(save)
+      end
+
+      # This workbook's VBA surface: blocks, components, import and export.
+      # `book.vba.write(code, name: 'helpers')` is the common call; see
+      # BookVBA for the block-vs-component split and for where code has to
+      # live to be callable at all.
+      #
+      # Name note: `vba` is a bare lowercase word, so it would shadow a COM
+      # member spelled the same. Workbook has none -- the member it has is
+      # `VBProject`, still reachable as `book.vba.project`.
+      def vba
+        @vba ||= BookVBA.new(@ole, convert_paths: @convert_paths)
+      end
+
+      # This workbook's UserForms: `forms.add('AppForm')`, `forms['AppForm']`.
+      #
+      # Name note (M0, measured against Excel 11): `forms` is free on
+      # Workbook.
+      def forms
+        @forms ||= Forms.new(self)
+      end
+    end
+  end
+end

data/lib/wineole/msoffice/color.rb

@@ -0,0 +1,87 @@
+module WineOLE
+  module MSOffice
+    # '#RRGGBB' <-> Excel's colour integer.
+    #
+    # Excel stores a colour as BGR, not RGB: measured by making Excel name
+    # the colour itself, `Interior.Color = 255` reports ColorIndex 3 (red)
+    # and `= 0xFF0000` reports ColorIndex 5 (blue). So the obvious
+    # `'#FF0000'.delete('#').to_i(16)` produces blue, silently.
+    #
+    # Public, and returning a plain Integer, on purpose. The wrapper's own
+    # keys are not the only place a colour is written -- the passthrough
+    # reaches Interior.Color, Font.Color, Borders.Color, Tab.Color and
+    # anything else COM has, and that surface is unbounded by design. One
+    # function that returns an Integer covers all of it without the protocol
+    # or Proxy#encode knowing anything about colours.
+    module Color
+      HEX = /\A#?(?:\h{3}|\h{6})\z/.freeze
+      private_constant :HEX
+
+      # '#RRGGBB' | '#RGB' | [r, g, b] -> Excel's integer.
+      def self.[](value)
+        r, g, b = rgb(value)
+        r | (g << 8) | (b << 16)
+      end
+
+      # Excel's integer (or the Float it actually hands back) -> '#RRGGBB'.
+      def self.to_hex(value)
+        unless value.is_a?(::Numeric)
+          raise ArgumentError, "expected a number from COM, got #{value.inspect}"
+        end
+
+        # Checked before converting: Float::INFINITY#to_i raises
+        # FloatDomainError and Complex#to_i raises RangeError, neither of
+        # which is this module's ArgumentError. Range#cover? (as
+        # Format.size uses via SIZE_RANGE) rather than #between?, because
+        # Complex does not include Comparable -- #between? raises
+        # NoMethodError on it outright, where #cover? just answers false.
+        unless (0..0xFFFFFF).cover?(value)
+          raise ArgumentError,
+            "expected a colour in 0..0xFFFFFF, got #{value.inspect}. " \
+            "Excel's ColorIndex is a different property from Color -- its " \
+            'values (-4105 automatic, -4142 none) are not colours and cannot ' \
+            'be converted here'
+        end
+        n = value.to_i
+        ::Kernel.format('#%02X%02X%02X', n & 0xFF, (n >> 8) & 0xFF, (n >> 16) & 0xFF)
+      end
+
+      def self.rgb(value)
+        case value
+        when ::String then from_hex(value)
+        when ::Array  then from_array(value)
+        else
+          raise ArgumentError,
+            "expected '#RRGGBB', '#RGB' or [r, g, b], got #{value.inspect}"
+        end
+      end
+      private_class_method :rgb
+
+      def self.from_hex(value)
+        # Checked before parsing: String#to_i(16) reads garbage as 0 rather
+        # than complaining, so '#GGGGGG' would silently become black.
+        unless value.match?(HEX)
+          raise ArgumentError,
+            "expected '#RRGGBB' or '#RGB', got #{value.inspect}"
+        end
+
+        s = value.delete_prefix('#')
+        s = s.chars.map { |c| c * 2 }.join if s.length == 3
+        [s[0, 2], s[2, 2], s[4, 2]].map { |h| h.to_i(16) }
+      end
+      private_class_method :from_hex
+
+      def self.from_array(value)
+        ok = value.length == 3 &&
+             value.all? { |c| c.is_a?(::Integer) && (0..255).cover?(c) }
+        unless ok
+          raise ArgumentError,
+            "expected [r, g, b] with three integers in 0..255, got #{value.inspect}"
+        end
+
+        value
+      end
+      private_class_method :from_array
+    end
+  end
+end