wineole 0.1.0 → 0.2.0

data/lib/wineole/msoffice/vba_block.rb

@@ -0,0 +1,144 @@
+require_relative 'vba'
+
+module WineOLE
+  module MSOffice
+    # A named span of code inside a VBA module, delimited by comment markers.
+    #
+    # The wrapper owns the span, never the module. A module may be one the
+    # caller wrote in, or one that cannot be deleted at all (ThisWorkbook, a
+    # worksheet), so "replace the module" is not available and would be too
+    # blunt even where it is.
+    module VBABlock
+      NAME = /\A[A-Za-z0-9_-]+\z/.freeze
+
+      # Matches any wineole marker line, open or close, for any name -- not
+      # just the one being written. Used to refuse a payload that would be
+      # indistinguishable from the wrapper's own delimiters.
+      MARKER_LINE = /\A'<\/?wineole:[A-Za-z0-9_-]+>\z/.freeze
+
+      def self.open_marker(name)  = "'<wineole:#{name}>"
+      def self.close_marker(name) = "'</wineole:#{name}>"
+
+      # Replaces the block of this name if it is there, adds it if not.
+      def self.write(code_module, name, code)
+        check_name(name)
+        check_representable(code)
+        check_payload(code)
+        remove(code_module, name)
+        code_module.AddFromString(
+          "#{open_marker(name)}\n#{code.chomp}\n#{close_marker(name)}\n"
+        )
+        nil
+      end
+
+      # False when there was nothing of this name to remove. Otherwise the
+      # module's remaining lines, as an Array -- so a caller that needs to
+      # know whether the module is now blank does not have to fetch the
+      # whole body a second time to ask.
+      #
+      # Block names match case-insensitively, as VBA identifiers do: two
+      # blocks named `main` and `Main` would hold procedures that collide,
+      # and VBA answers "Ambiguous name detected" for the whole module from
+      # then on. So `Main` replaces (and removes) a block written as `main`.
+      def self.remove(code_module, name)
+        check_name(name)
+        lines = body(code_module)
+        return false if lines.empty?
+
+        first = lines.index { |l| l.strip.casecmp?(open_marker(name)) }
+        last = lines.index { |l| l.strip.casecmp?(close_marker(name)) }
+
+        if first.nil?
+          if last
+            raise ArgumentError,
+              "the #{name.inspect} block in this module has a closing marker " \
+              'with no matching opening one -- the module is already ' \
+              'corrupted; refusing to guess what to remove'
+          end
+          return false
+        end
+
+        if last.nil? || last < first
+          raise ArgumentError,
+            "the #{name.inspect} block in this module has no closing marker -- " \
+            'refusing to guess where it ends'
+        end
+
+        code_module.DeleteLines(first + 1, last - first + 1)
+        lines[0...first] + lines[(last + 1)..]
+      end
+
+      # Nothing but whitespace. Not CountOfLines == 0: a module emptied of
+      # its blocks still reports the newlines that held them.
+      def self.blank?(code_module)
+        blank_lines?(body(code_module))
+      end
+
+      # The same emptiness rule #blank? uses, applied to lines the caller
+      # already has (typically the Array #remove just handed back) instead
+      # of fetching the body again.
+      def self.blank_lines?(lines)
+        lines.all? { |l| l.strip.empty? }
+      end
+
+      # One round trip, whatever the module's length. Excel reports 0 lines
+      # for a module never written to, and Lines(1, 0) is not a legal call.
+      def self.body(code_module)
+        count = code_module.CountOfLines.to_i
+        return [] if count.zero?
+
+        code_module.Lines(1, count).split(/\r?\n/)
+      end
+      private_class_method :body
+
+      # A module's text is held in the system ANSI codepage, not Unicode --
+      # measured, not assumed: on a CP932 host `café` comes back `cafe`,
+      # `✓` comes back `?`, and simplified Chinese comes back part `?`.
+      # Japanese survives only because CP932 can represent it, which is why
+      # an earlier measurement using Japanese alone concluded, wrongly, that
+      # this path carried Unicode.
+      #
+      # So this path is bound by exactly the same codepage as import_vba,
+      # and gets the same rule: refuse rather than substitute. Silently
+      # dropping an accent is the failure this whole phase exists to remove.
+      #
+      # ASCII skips the check, which is almost every call -- resolving the
+      # codepage costs a `wine reg` invocation.
+      def self.check_representable(code)
+        return if code.ascii_only?
+
+        code.encode(VBA.codepage)
+      rescue ::Encoding::UndefinedConversionError => e
+        VBA.unrepresentable!(e.error_char, 'this code')
+      end
+      private_class_method :check_representable
+
+      def self.check_name(name)
+        return if name.is_a?(::String) && name.match?(NAME)
+
+        raise ArgumentError,
+          "a block name must match #{NAME.inspect} -- it goes inside a VBA " \
+          "comment marker, so it cannot contain spaces, '>' or newlines. " \
+          "Got #{name.inspect}"
+      end
+      private_class_method :check_name
+
+      # A code body containing a line that is itself a wineole marker would
+      # be indistinguishable from a real one once written: #remove would
+      # find the caller's accidental marker instead of its own, delete up to
+      # the wrong place, and leave the rest as permanent garbage. The
+      # wrapper controls what it writes, so refusing the payload up front is
+      # what keeps that state from ever existing.
+      def self.check_payload(code)
+        offending = code.split(/\r?\n/).find { |line| line.strip.match?(MARKER_LINE) }
+        return if offending.nil?
+
+        raise ArgumentError,
+          "the code being written contains a line that is itself a wineole " \
+          "marker (#{offending.strip.inspect}) -- this cannot be told apart " \
+          'from the wrapper\'s own markers, so it is refused'
+      end
+      private_class_method :check_payload
+    end
+  end
+end

data/lib/wineole/msoffice.rb

@@ -0,0 +1,28 @@
+# The bundled Microsoft Office wrapper: Address, Paths, Range, Sheet, Book,
+# Excel, and the Controls and Forms wrappers, all under WineOLE::MSOffice.
+#
+# Deliberately NOT required from lib/wineole.rb. The core layer is a
+# general-purpose COM bridge; this is Office-specific, and it is where a
+# Word and a PowerPoint wrapper will land too, so it will only grow.
+# Someone who wants the bridge should not have to carry an Excel wrapper to
+# get it.
+#
+# Defines no top-level constant. An earlier draft aliased WineOLE::MSOffice
+# to a root-level MSOffice for code written against the older msoffice.rb;
+# reaching into the root namespace from a library is intrusive enough that
+# the alias was not worth the two failure modes it brought with it (a
+# silent no-op when something else already defined MSOffice, and a test
+# whose result depended on process-wide load order).
+require_relative 'msoffice/address'
+require_relative 'msoffice/vba'
+require_relative 'msoffice/vba_block'
+require_relative 'msoffice/vba_api'
+require_relative 'msoffice/color'
+require_relative 'msoffice/format'
+require_relative 'msoffice/paths'
+require_relative 'msoffice/range'
+require_relative 'msoffice/sheet'
+require_relative 'msoffice/controls'
+require_relative 'msoffice/forms'
+require_relative 'msoffice/book'
+require_relative 'msoffice/excel'

data/lib/wineole/proxy.rb

@@ -1,21 +1,93 @@
 require 'time'
+require 'date'
 require_relative 'errors'
+# Stated here rather than left to wineole.rb: `ole_events` below names the
+# constant, so anything that loads this file alone -- proxy_test.rb does --
+# must get a working method rather than a NameError the first time it is
+# called. events.rb requires nothing from here (it reaches Proxy at call
+# time, not load time), so there is no cycle.
+require_relative 'events'
 
 module WineOLE
   class Proxy
-    def self.create(class_name, client)
-      handle = client.call('create', {class_name: class_name})['$ole_ref']
+    def self.create(class_name, client, cleanup: nil)
+      params = {class_name: class_name}
+      params[:cleanup] = build_cleanup(cleanup) if cleanup
+      handle = client.call('create', params)['$ole_ref']
+      register_cleanup(client, handle, cleanup)
       new(client, session_id: client.object_id, handle: handle, created: true)
     end
 
-    def self.connect(class_name, client)
-      handle = client.call('connect', {class_name: class_name})['$ole_ref']
+    def self.connect(class_name, client, cleanup: nil)
+      params = {class_name: class_name}
+      params[:cleanup] = build_cleanup(cleanup) if cleanup
+      handle = client.call('connect', params)['$ole_ref']
+      register_cleanup(client, handle, cleanup)
       new(client, session_id: client.object_id, handle: handle, created: false)
     end
 
-    def self.connect_or_create(class_name, client)
-      result = client.call('connect_or_create', {class_name: class_name})
-      new(client, session_id: client.object_id, handle: result['$ole_ref'], created: result['created'])
+    def self.connect_or_create(class_name, client, cleanup: nil)
+      params = {class_name: class_name}
+      params[:cleanup] = build_cleanup(cleanup) if cleanup
+      result = client.call('connect_or_create', params)
+      handle = result['$ole_ref']
+      register_cleanup(client, handle, cleanup)
+      new(client, session_id: client.object_id, handle: handle, created: result['created'])
+    end
+
+    # `cleanup` is `{ steps: [[name, *args], ...], on_cleanup: proc_or_nil }`
+    # in Ruby terms; the wire wants `{ steps: [{name:, args:}, ...], callback: bool }`.
+    # `callback` tells the bridge whether to hold the root open and emit a
+    # `$cleanup` event for a registered closure, or just run the steps and
+    # release outright -- so its value comes from whether `on_cleanup` is
+    # present, not from anything the caller states separately.
+    def self.build_cleanup(cleanup)
+      steps = (cleanup[:steps] || []).map do |name, *args|
+        {name: name, args: args}
+      end
+      {steps: steps, callback: !cleanup[:on_cleanup].nil?}
+    end
+    private_class_method :build_cleanup
+
+    # Register the client closure (if any) so the dispatcher can deliver
+    # $cleanup for this root handle. The real Dispatcher#register_cleanup
+    # lands in a later task; this only needs `client.dispatcher` to answer to
+    # it, which is exactly what the real Client already does.
+    def self.register_cleanup(client, handle, cleanup)
+      return unless cleanup && cleanup[:on_cleanup]
+
+      client.dispatcher.register_cleanup(handle, cleanup[:on_cleanup])
+    end
+    private_class_method :register_cleanup
+
+    # One wire value, in Ruby terms.
+    #
+    # On the class rather than private to an instance because two different
+    # holders of a client need it: an invoke's RESULT, and an event's
+    # ARGUMENTS (WineOLE::Events#build_args). A second copy of this walk over
+    # there is how the same tagged value ends up a Time when a call returns it
+    # and a raw {"$type" => "time"} Hash when an event carries it -- and how a
+    # nested $ole_ref reaches a callback unwrapped.
+    #
+    # Recursive, because a bulk range read comes back as an array of rows and
+    # the values needing conversion sit inside it, not at the top level. A
+    # non-recursive decode would hand back raw {"$type" => "time"} hashes for
+    # every date cell in the range.
+    def self.decode(client, value)
+      case value
+      when Array
+        value.map { |v| decode(client, v) }
+      when Hash
+        if value.key?('$ole_ref')
+          wrap(client, client.object_id, value['$ole_ref'])
+        elsif value['$type'] == 'time'
+          Time.iso8601(value['iso8601'])
+        else
+          value.transform_values { |v| decode(client, v) }
+        end
+      else
+        value
+      end
     end
 
     def self.wrap(client, session_id, ole_ref)
@@ -75,8 +147,38 @@ module WineOLE
       @created
     end
 
+    # Tells the bridge to leave this root instance running rather than
+    # closing it when the connection goes away -- the counterpart to a
+    # `cleanup:` closure a caller wants to run later, on its own terms,
+    # rather than as part of this process's teardown.
+    def ole_leave_open
+      @client.call('leave_open', {handle: @ole_handle})
+      nil
+    end
+
     def ole_release
-      @client.call('release', {handle: @ole_handle})
+      result = @client.call('release', {handle: @ole_handle})
+      # A client closure must run before this handle is actually gone: the
+      # bridge answers with the $cleanup sequence number instead of
+      # releasing outright, and this blocks until the dispatcher has
+      # delivered it and the release_event that follows. See
+      # Client#await_cleanup.
+      if result.is_a?(Hash) && (seq = result['cleanup'])
+        @client.await_cleanup(seq)
+      end
+      nil
+    end
+
+    # COM events for this object. Named with the `ole_` prefix like every
+    # other bookkeeping method here: a Proxy forwards unknown names straight
+    # to COM, so a bare `events` would shadow a real `Events` member.
+    #
+    # Memoized, because the Events owns a dispatcher thread and a bridge-side
+    # subscription set: a fresh one per call would mean `on` and the `off`
+    # that is meant to undo it talked to different objects.
+    def ole_events
+      check_live!
+      @ole_events ||= Events.new(@client, @ole_handle)
     end
 
     def ole_const_load
@@ -126,6 +228,21 @@ module WineOLE
             'passed as an argument here'
         end
         {'$ole_ref' => value.ole_handle}
+      when Time
+        # The same tag the receive side emits for VT_DATE. The wall clock is
+        # sent as-is: a VT_DATE carries no timezone, so converting here would
+        # silently move the value the caller wrote. Matching
+        # wineole/proxy.py's `_encode`.
+        {'$type' => 'time', 'iso8601' => value.strftime('%Y-%m-%dT%H:%M:%S')}
+      when Date
+        # `date` is already loaded transitively -- `time`'s own lib/time.rb
+        # requires it -- so this require costs nothing new; it just states
+        # the real dependency instead of relying on another library's
+        # internals. DateTime is a subclass of Date, and both answer
+        # strftime, so one branch covers them. (Date is not in Time's
+        # hierarchy, which is why the `when Time` branch above doesn't catch
+        # it.) Matching wineole/proxy.py's `_encode`.
+        {'$type' => 'time', 'iso8601' => value.strftime('%Y-%m-%dT%H:%M:%S')}
       when Hash
         value.transform_values { |v| encode(v) }
       when Array
@@ -136,13 +253,7 @@ module WineOLE
     end
 
     def decode(value)
-      if value.is_a?(Hash) && value.key?('$ole_ref')
-        Proxy.wrap(@client, @client.object_id, value['$ole_ref'])
-      elsif value.is_a?(Hash) && value['$type'] == 'time'
-        Time.iso8601(value['iso8601'])
-      else
-        value
-      end
+      Proxy.decode(@client, value)
     end
   end
 end

data/lib/wineole.rb

@@ -1,6 +1,8 @@
 require_relative 'wineole/errors'
 require_relative 'wineole/client'
 require_relative 'wineole/proxy'
+require_relative 'wineole/dispatcher'
+require_relative 'wineole/events'
 
 module WineOLE
   @default_client = nil
@@ -25,12 +27,19 @@ module WineOLE
   # racing on a nil default contend for the lock, and only the actual
   # winner calls Client.open -- everyone else sees it already set once they
   # acquire the lock, and the `||=` means they never call Client.open again.
+  #
+  # Public (a deliberate exception to "the core layer is not changed" --
+  # the same exception, and for the same reason, as Client#loopback?):
+  # bundled wrappers such as WineOLE::MSOffice::Excel need the Client their
+  # Proxy belongs to (Book needs it to answer #loopback?), and this module is
+  # already the layer holding that connection. Making the caller guess, or
+  # open a second connection just to answer that question, would be worse
+  # than letting the layer that already knows the answer say so.
   def self.default_client
     return @default_client if @default_client
 
     @mutex.synchronize { @default_client ||= Client.open }
   end
-  private_class_method :default_client
 
   def self.create(class_name)
     default_client.create(class_name)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: wineole
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - firelzrd
@@ -14,14 +14,33 @@ description: |
   that lets a Linux Ruby process drive Win32OLE/COM automation of
   Windows applications running under Wine, over a JSON Lines TCP
   protocol, without requiring a Windows build of Ruby.
-executables: []
+executables:
+- wineole-vba
 extensions: []
 extra_rdoc_files: []
 files:
 - LICENSE
+- bin/wineole-vba
 - lib/wineole.rb
 - lib/wineole/client.rb
+- lib/wineole/dispatcher.rb
 - lib/wineole/errors.rb
+- lib/wineole/events.rb
+- lib/wineole/msoffice.rb
+- lib/wineole/msoffice/address.rb
+- lib/wineole/msoffice/book.rb
+- lib/wineole/msoffice/color.rb
+- lib/wineole/msoffice/controls.rb
+- lib/wineole/msoffice/excel.rb
+- lib/wineole/msoffice/format.rb
+- lib/wineole/msoffice/forms.rb
+- lib/wineole/msoffice/passthrough.rb
+- lib/wineole/msoffice/paths.rb
+- lib/wineole/msoffice/range.rb
+- lib/wineole/msoffice/sheet.rb
+- lib/wineole/msoffice/vba.rb
+- lib/wineole/msoffice/vba_api.rb
+- lib/wineole/msoffice/vba_block.rb
 - lib/wineole/proxy.rb
 - wineole-bridge-dist/aarch64-pc-windows-gnullvm/wineole-bridge.exe
 - wineole-bridge-dist/i686-pc-windows-gnu/wineole-bridge.exe