wineole 0.1.0 → 0.2.0

data/lib/wineole/msoffice/forms.rb

@@ -0,0 +1,163 @@
+require_relative '../proxy'
+require_relative '../errors'
+require_relative 'passthrough'
+require_relative 'vba_api'
+require_relative 'controls'
+
+module WineOLE
+  module MSOffice
+    # `book.forms`: the UserForms of a workbook. A UserForm is a VBComponent
+    # of type 3 with a Designer; the form itself exists only while VBA has
+    # it loaded, as its default instance. The wrapper reaches that instance
+    # through four generated procedures in its own module, because a
+    # UserForm's default instance has no COM name a client can ask for.
+    #
+    # Name note (M0): `forms` is free on Workbook.
+    class Forms
+      USERFORM_TYPE = 3
+
+      def initialize(book)
+        @book = book
+      end
+
+      # The name is checked here as well as in add_component, because it
+      # also becomes part of four procedure names.
+      def add(name)
+        Controls.check_name!(name)
+        component = @book.vba.add_component(name, kind: :form)
+        begin
+          Form.new(name, component, @book)
+        rescue StandardError
+          # Form.new's helper write failed after the component was already
+          # created; take the component back out rather than leaving it
+          # behind with no helper to show or unload it.
+          @book.vba.remove_component(name)
+          raise
+        end
+      end
+
+      # Re-bind an existing UserForm (one made earlier, or one in a workbook
+      # that was opened). nil for a missing name or a component that is not
+      # a UserForm. AccessDenied from `project` passes through.
+      #
+      # Only the lookup is rescued, deliberately: Form.new writes the helper
+      # block, and that write can be refused (a locked project, a refused
+      # AddFromString). Reporting a real failure as "not found" would send
+      # the caller looking for a form that is right there.
+      def [](name)
+        component = begin
+          found = @book.vba.project.VBComponents.Item(name)
+          found if found.Type == USERFORM_TYPE
+        rescue WineOLE::RemoteError
+          nil
+        end
+        return nil if component.nil?
+
+        Form.new(name, component, @book)
+      end
+
+      # The helper block. `Show 0` is modeless, and it is the only form the
+      # wrapper offers: a modal Show blocks Excel's message loop, and with
+      # it the bridge -- measured, the bridge freezes until the form closes.
+      def self.helper(name)
+        <<~VBA
+          Function WineOLE_Form_#{name}() As Object
+              Set WineOLE_Form_#{name} = #{name}
+          End Function
+          Sub WineOLE_Show_#{name}()
+              #{name}.Show 0
+          End Sub
+          Sub WineOLE_Hide_#{name}()
+              #{name}.Hide
+          End Sub
+          Sub WineOLE_Unload_#{name}()
+              Unload #{name}
+          End Sub
+        VBA
+      end
+    end
+
+    # One UserForm. `ole` is the Designer (the design-time form: Caption,
+    # Width, Height, and the Controls that `controls` wraps). `instance` is
+    # the loaded form -- the object that shows, hides and fires events.
+    #
+    # Name note (M0): `name`, `component`, `ole`, `instance`, `show`,
+    # `hide`, `unload` measured free on the Designer; `controls` is the
+    # deliberate shadow.
+    class Form
+      include Passthrough
+
+      attr_reader :name, :component
+
+      # Writing the helper on every construction (add and re-bind alike) is
+      # what makes a form in a reopened workbook showable without the
+      # caller remembering to do anything; write is an upsert.
+      def initialize(name, component, book)
+        @name = name
+        @component = component
+        @book = book
+        @ole = component.Designer
+        @runtime = {}
+        @instance = nil
+        @book.vba.write(Forms.helper(name), name: "form_#{name}")
+      end
+
+      def controls
+        @controls ||= UserFormControls.new(self, @book.vba)
+      end
+
+      # The default instance. Referencing it loads the form if it is not
+      # loaded (VBA auto-instantiation), so `shown?` before `show` answers
+      # false and leaves the form loaded but hidden. Cached until `unload`.
+      def instance
+        @instance ||= run('Form')
+      end
+
+      # The live counterpart of a design-time control, by name. Cached so
+      # that `on` and the `off` that undoes it meet the same Events.
+      def runtime_control(control_name)
+        @runtime[control_name] ||= instance.Controls.Item(control_name)
+      end
+
+      # Modeless, always. Returns as soon as the form is on screen; the
+      # bridge stays responsive, which is what lets events reach Ruby.
+      def show
+        run('Show')
+        self
+      end
+
+      # Through VBA, like show and unload: the extender's Hide answers
+      # GetIDsOfNames but refuses every out-of-process Invoke (measured,
+      # DISP_E_MEMBERNOTFOUND whatever the flags), while Visible reads fine.
+      def hide
+        run('Hide')
+        self
+      end
+
+      def shown?
+        instance.Visible ? true : false
+      end
+
+      # Unloading destroys the runtime controls, and with them every event
+      # connection Ruby holds on them, so those are closed first -- on our
+      # side, deliberately, rather than left to fail when the object is
+      # gone. The next `instance` loads a fresh form.
+      def unload
+        @runtime.each_value { |control| control.ole_events.close }
+        @instance&.ole_events&.close
+        @runtime.clear
+        @instance = nil
+        run('Unload')
+        self
+      end
+
+      private
+
+      # Qualified with the workbook name so the right book's procedure runs
+      # when several are open (M2 measured this form working on Excel 11).
+      def run(verb)
+        @book.ole.Application.Run("'#{@book.ole.Name}'!WineOLE_#{verb}_#{@name}")
+      end
+    end
+  end
+end

data/lib/wineole/msoffice/passthrough.rb

@@ -0,0 +1,46 @@
+require_relative '../proxy'
+
+module WineOLE
+  module MSOffice
+    # Shared by every wrapper around a COM object that otherwise passes
+    # unknown methods straight through to it: the `ole` reader, plus
+    # `method_missing`/`respond_to_missing?`. `Range`, `Sheet`, `Book`,
+    # `Control` and `Form` each need exactly these three members; `Control`
+    # overrides `passthrough_target`; extracted here so they are written
+    # once instead of copied three times.
+    #
+    # Deliberately does not define `initialize` -- the including classes
+    # take different constructor arguments (`Range.new(proxy)` vs.
+    # `Sheet.new(proxy, version:)` vs. `Book.new(proxy, client:, version:,
+    # convert_paths:)`), so each sets `@ole` itself.
+    module Passthrough
+      # The underlying Proxy, for reaching COM explicitly.
+      attr_reader :ole
+
+      def method_missing(name, *args, &block)
+        return super if Proxy::IMPLICIT_CONVERSIONS.include?(name)
+
+        passthrough_target.public_send(name, *args, &block)
+      end
+
+      def respond_to_missing?(name, include_private = false)
+        # Anything not named here is a COM member as far as this class is
+        # concerned -- the same stance Proxy takes, and for the same reason:
+        # Ruby probes to_ary, to_str, coerce and friends behind the scenes,
+        # and answering `true` to those makes e.g. `puts obj` try a
+        # conversion that ends in NoMethodError from inside the interpreter.
+        # Reuse Proxy's list rather than keeping a second copy of it.
+        !Proxy::IMPLICIT_CONVERSIONS.include?(name)
+      end
+
+      private
+
+      # Where unknown methods go. `@ole` for every wrapper except `Control`,
+      # which forwards to the object that has Caption and Value rather than
+      # to the OLEObject host around it (see Control's class comment).
+      def passthrough_target
+        @ole
+      end
+    end
+  end
+end

data/lib/wineole/msoffice/paths.rb

@@ -0,0 +1,62 @@
+require 'English'
+require_relative '../client'
+
+module WineOLE
+  module MSOffice
+    # Linux <-> Wine path conversion, and the question of whether converting
+    # is meaningful at all.
+    #
+    # It is meaningful only when the client and the bridge are on one machine
+    # looking at one Wine prefix. Convert when that is not true and you get a
+    # path that silently refers to some other machine's filesystem.
+    module Paths
+      # Z:\..., C:/..., \\server\share\...
+      WINDOWS_SHAPED = %r{\A(?:[A-Za-z]:[\\/]|\\\\)}.freeze
+
+      # Deliberately keyed off the same loopback test the bridge uses to
+      # decide whether a token is required. If the two definitions of "local"
+      # drifted apart, a connection could be remote for authentication and
+      # local for paths at once.
+      #
+      # A host's own NIC address counts as remote. Enumerating local
+      # interfaces to notice otherwise would be more code, more edge cases
+      # (containers, NAT, temporary IPv6 addresses), and would reintroduce
+      # exactly that split.
+      def self.convertible?(client:, windows: Client::WINDOWS)
+        return false if windows # already Windows paths, and no winepath here
+
+        client.loopback?
+      end
+
+      # Linux path -> Wine path. Returns the argument unchanged when it
+      # already looks like a Windows path, and when winepath is unavailable
+      # or fails.
+      #
+      # Failing to convert is not fatal -- the caller can write a Windows
+      # path themselves, and will see that they need to. Raising here would
+      # turn a recoverable inconvenience into a stopped script.
+      def self.to_wine(path)
+        return path if path.to_s.match?(WINDOWS_SHAPED)
+
+        run_winepath('-w', path) || path
+      end
+
+      # Wine path -> Linux path. Same failure stance.
+      def self.to_local(path)
+        return path unless path.to_s.match?(WINDOWS_SHAPED)
+
+        run_winepath('-u', path) || path
+      end
+
+      def self.run_winepath(flag, path)
+        out = IO.popen(['winepath', flag, path.to_s], err: File::NULL, &:read)
+        return nil unless $CHILD_STATUS&.success?
+
+        out.strip.empty? ? nil : out.strip
+      rescue SystemCallError, IOError
+        nil
+      end
+      private_class_method :run_winepath
+    end
+  end
+end

data/lib/wineole/msoffice/range.rb

@@ -0,0 +1,149 @@
+require_relative '../proxy'
+require_relative 'passthrough'
+require_relative 'format'
+
+module WineOLE
+  module MSOffice
+    # Wraps a COM Range. Adds exactly four methods plus `ole`; everything
+    # else falls through to COM.
+    #
+    # The restraint is deliberate. COM's Range already exposes Rows, Columns,
+    # Cells, Item, Areas, Find, Sort, Merge, Table and many more, and COM
+    # resolves names case-insensitively -- so every lowercase single word this
+    # class defines covers a COM call that already worked. `to_a`, `write`,
+    # `fill`, `format` and `ole` were each checked against a live Range and
+    # found absent.
+    class Range
+      include Passthrough
+
+      def initialize(proxy)
+        @ole = proxy
+      end
+
+      # Always a two-dimensional Array, whatever the range's size.
+      #
+      # Excel's own `Value` returns a bare scalar for a one-cell range --
+      # consistently, whether it was addressed as "A1" or "A1:A1" -- so
+      # generic code that does not know the size has to branch. This is that
+      # branch, written once.
+      #
+      # Returns a plain Array on purpose: Ruby's own vocabulary then covers
+      # the rest (`rows.transpose` for columns, `rows.flatten` for values),
+      # so this class does not have to grow `each_row`, `each_column` or
+      # `flatten` and risk shadowing more COM members.
+      def to_a
+        v = @ole.Value
+        v.is_a?(::Array) ? v : [[v]]
+      end
+
+      # Write, refusing anything that does not fit.
+      #
+      # Excel's own assignment corrupts silently in three ways (all measured):
+      # a flat array written to a column replicates its first element down
+      # every cell, too few values leave #N/A behind, and too many are
+      # truncated. None of those raise, and none are visible without looking
+      # at the sheet.
+      def write(value)
+        @ole.Value = shaped(value)
+      end
+
+      # Write, adapting the value to the range: replicate along a dimension
+      # the argument does not have, truncate or pad along one it does.
+      #
+      # Total -- every input has a defined result, no exceptions -- but note
+      # that it reproduces Excel's own column trap by construction: a flat
+      # array is a row, so filling an Nx1 column with [1,2,3] puts 1 in every
+      # cell. That is why `write` and not `fill` is what `sheet[addr] = x`
+      # uses; reach for this one deliberately.
+      def fill(value)
+        nrows = row_count
+        ncols = column_count
+        @ole.Value =
+          case value
+          when ::Array
+            if value.first.is_a?(::Array)
+              (0...nrows).map { |r| row = value[r] || []; (0...ncols).map { |c| row[c] } }
+            else
+              one = (0...ncols).map { |c| value[c] }
+              ::Array.new(nrows) { one.dup }
+            end
+          else
+            ::Array.new(nrows) { ::Array.new(ncols) { value } }
+          end
+      end
+
+      # Apply formatting. Keys are documented on WineOLE::MSOffice::Format.
+      #
+      # An absent key leaves that attribute alone; `false` turns it off.
+      # That third state is why this takes keyword arguments rather than
+      # being a chain of verbs -- and it keeps this class's additions to one
+      # name, which matters because COM resolves names case-insensitively
+      # and every lowercase word here covers a COM member of the same
+      # spelling. `format` was measured free on a live Range.
+      #
+      # Note for anyone editing this class: defining `format` shadows
+      # Kernel#format inside these instance methods, so string formatting
+      # here must be written as `::Kernel.format(...)`.
+      def format(**opts)
+        Format.apply(@ole, opts)
+        self
+      end
+
+      private
+
+      def row_count
+        @ole.Rows.Count
+      end
+
+      def column_count
+        @ole.Columns.Count
+      end
+
+      def shaped(value)
+        return value unless value.is_a?(::Array)
+
+        nrows = row_count
+        ncols = column_count
+
+        if value.first.is_a?(::Array)
+          unless value.all? { |r| r.is_a?(::Array) }
+            raise ArgumentError,
+              "range is #{nrows}x#{ncols}, but the value mixes rows and scalars"
+          end
+          widths = value.map(&:length).uniq
+          if widths.length > 1
+            raise ArgumentError,
+              "range is #{nrows}x#{ncols}, but the value has ragged rows " \
+              "(#{widths.join(', ')} elements)"
+          end
+          if value.any? { |r| r.any? { |c| c.is_a?(::Array) } }
+            raise ArgumentError,
+              "range is #{nrows}x#{ncols}, but the value nests more than two deep"
+          end
+          unless value.length == nrows && widths.first == ncols
+            raise ArgumentError,
+              "range is #{nrows}x#{ncols}, but the value is " \
+              "#{value.length}x#{widths.first}"
+          end
+          value
+        else
+          if value.any? { |v| v.is_a?(::Array) } # rubocop:disable Style/IfInsideElse
+            raise ArgumentError,
+              "range is #{nrows}x#{ncols}, but the value mixes scalars and rows"
+          end
+          if nrows > 1 && ncols > 1
+            raise ArgumentError,
+              "range is #{nrows}x#{ncols}; a flat array only fits a single " \
+              'row or column -- pass rows, or use fill'
+          end
+          expected = nrows > 1 ? nrows : ncols
+          unless value.length == expected
+            raise ArgumentError,
+              "range is #{nrows}x#{ncols}, but the value has #{value.length} elements"
+          end
+          nrows > 1 ? value.map { |v| [v] } : [value]
+        end
+      end
+    end
+  end
+end

data/lib/wineole/msoffice/sheet.rb

@@ -0,0 +1,101 @@
+require_relative '../proxy'
+require_relative 'passthrough'
+require_relative 'address'
+require_relative 'range'
+require_relative 'vba_api'
+require_relative 'controls'
+
+module WineOLE
+  module MSOffice
+    # Wraps a COM Worksheet. `[]`/`[]=` address it through the same `Address`
+    # parser the whole wrapper uses, so `sheet['A1:B2']` and
+    # `sheet[row, col]` both hand back a `Range`; everything else falls
+    # through to COM.
+    class Sheet
+      include Passthrough
+
+      def initialize(proxy, version:)
+        @ole = proxy
+        @version = version
+      end
+
+      def [](*keys)
+        range_for(keys)
+      end
+
+      # Delegates to Range#write, never #fill: write raises on a value that
+      # does not fit the range rather than replicating or padding it, which
+      # is the behaviour an assignment through []= should have.
+      def []=(*args)
+        value = args.pop
+        range_for(args).write(value)
+      end
+
+      # This worksheet's VBA surface. Blocks only -- a worksheet's module
+      # cannot be created or deleted, so SheetVBA has no component methods
+      # rather than having ones that always fail.
+      def vba
+        @vba ||= SheetVBA.new(@ole)
+      end
+
+      # The Forms-toolbar controls on this sheet: `form_controls.add(:button,
+      # name: 'Go', at: 'B2')`. See FormControls for what they can and
+      # cannot do; `activex` is the family whose events reach Ruby.
+      #
+      # Name note (M0, measured against Excel 11): `form_controls` and
+      # `activex` are both free on Worksheet.
+      def form_controls
+        @form_controls ||= FormControls.new(self)
+      end
+
+      # The ActiveX controls on this sheet, MSForms or any registered
+      # ProgID: `activex.add(:command_button, name: 'Go', at: 'B2')`.
+      def activex
+        @activex ||= ActiveXControls.new(self)
+      end
+
+      private
+
+      def range_for(keys)
+        return Range.new(@ole.Cells(*keys)) if cell_reference?(keys)
+
+        unless keys.length == 1 && keys.first.is_a?(::String)
+          raise ArgumentError, "unsupported sheet index #{keys.inspect}"
+        end
+
+        str = keys.first
+        addr = Address.parse(str, @version)
+
+        # An address that parses but stops at a sheet or a book (or does
+        # not parse at all) is a lookup, not something with cells to read
+        # or write -- see the spec on why `xl["Sheet1!"] = 0` filling a
+        # whole sheet is a hazard rather than a convenience (Spec §4.5).
+        if addr.nil? || !addr.range?
+          raise ArgumentError, "#{str.inspect} has no range"
+        end
+
+        # This object is one sheet. An address that names a different
+        # workbook or worksheet would silently reach past it -- writing to
+        # the sheet the caller *named* instead of the one they *have* is
+        # exactly the class of silent wrong-target write this wrapper
+        # exists to prevent.
+        if named?(addr.workbook) || named?(addr.worksheet)
+          raise ArgumentError,
+            "#{str.inspect} names another workbook or worksheet; a Sheet " \
+            'addresses its own cells only -- reach another sheet through ' \
+            'the Excel object that owns it'
+        end
+
+        Range.new(@ole.Range(addr.range))
+      end
+
+      def cell_reference?(keys)
+        keys.length == 2 && keys.all? { |k| k.is_a?(::Integer) }
+      end
+
+      def named?(part)
+        !part.nil? && !part.empty?
+      end
+    end
+  end
+end