com 0.3.0

data/README

@@ -0,0 +1,225 @@
+# COM #
+
+COM is an object-oriented wrapper around WIN32OLE.  COM makes it easy to add
+behavior to WIN32OLE objects, making them easier to work with from Ruby.
+
+
+## Usage ##
+
+Using COM is rather straightforward.  There’s basically four concepts to keep
+track of:
+
+  1. COM objects
+  2. Instantiable COM objects
+  3. COM events
+  4. COM errors
+
+Let’s look at each concept separately, using the following example as a base.
+
+    module Word end
+
+    class Word::Application < COM::Instantiable
+      def without_interaction
+        with_properties('displayalerts' => Word::WdAlertsNone){ yield }
+      end
+
+      def documents
+        Word::Documents.new(com.documents)
+      end
+
+      def quit(saving = Word::WdDoNotSaveChanges, *args)
+        com.quit saving, *args
+      end
+    end
+
+### COM Objects ###
+
+A COM::Object is a wrapper around a COM object.  It provides error
+specialization, which is discussed later and a few utility methods.  You
+typically use it to wrap COM objects that are returned by COM methods.  If we
+take the example given in the introduction, Word::Documents is a good
+candidate:
+
+    class Word::Documents < COM::Object
+      DefaultOpenOptions = {
+        'confirmconversions' => false,
+        'readonly' => true,
+        'addtorecentfiles' => false,
+        'visible' => false
+      }.freeze
+      def open(path, options = {})
+        options = DefaultOpenOptions.merge(options)
+        options['filename'] = Pathname(path).to_com
+        Word::Document.new(com.open(options))
+      end
+    end
+
+Here we override the #open method to be a bit easier to use, providing sane
+defaults for COM interaction.  Worth noting is the use of the #com method to
+access the actual COM object to invoke the #open method on it.  Also note that
+Word::Document is also a COM::Object.
+
+COM::Object provides a convenience method called #with_properties, which is
+used in the #without_interaction method above.  It lets you set properties on
+the COM::Object during the duration of a block, restoring them after it exits
+(successfully or with an error).
+
+
+### Instantiable COM Objects ###
+
+Instantiable COM objects are COM objects that we can connect to and that can be
+created.  The Word::Application object can, for example, be created.
+Instantiable COM objects should inherit from COM::Instantiable.  Instantiable
+COM objects can be told what program ID to use, whether or not to allow
+connecting to an already running object, and to load its associated constants
+upon creation.
+
+The program ID is used to determine what instantiable COM object to connect to.
+By default the name of the COM::Instantiable class’ name is used, taking the
+last two double-colon-separated components and joining them with a dot.  For
+Word::Application, the program ID is “Word.Application”.  The program ID can be
+set by using the .program_id method:
+
+    class IDontCare::ForConventions < COM::Instantiable
+      program_id 'Word.Application'
+    end
+
+The program ID can be accessed with the same method:
+
+    Word::Application.program_id # ⇒ 'Word.Application'
+
+Connecting to an already running COM object is not done by default, but is
+sometimes desirable: the COM object might take a long time to create, or some
+common state needs to be accessed.  If the default for a certain instantiable
+COM object should be to connect, this can be done using the .connect method:
+
+    class Word::Application < COM::Instantiable
+      connect
+    end
+
+If no running COM object is available, then a new COM object will be created in
+its stead.  Whether or not a class uses the connection method can be queried
+with the .connect? method:
+
+    Word::Application.connect? # ⇒ true
+
+Whether or not to load constants associated with an instantiable COM object is
+set with the .constants method:
+
+    class Word::Application < COM::Instantiable
+      constants true
+    end
+
+and can similarly be checked:
+
+    Word::Application.constants? # ⇒ true
+
+Constants are loaded by default.
+
+When an instance of the instantiable COM object is created, a check is run to
+see if constants should be loaded and whether or not they already have been
+loaded.  If they should be loaded and they haven’t already been loaded,
+they’re, you guessed it, loaded.  The constants are added to the module
+containing the COM::Instantiable.  Thus, for Word::Application, the Word module
+will contain all the constants.  Whether or not the constants have already been
+loaded can be checked with .constants_loaded?:
+
+    Word::Application.constants_loaded # ⇒ false
+
+That concludes the class-level methods.
+
+Let’s begin with the #connected? method among the instance-level methods.  This
+method queries whether or not this instance connected to an already running COM
+object:
+
+    Word::Application.new.connected? # ⇒ false
+
+This can be very important in determining how shutdown of a COM object should
+be done.  If you connected to an already COM object it might be foolish to shut
+it down if someone else is using it.
+
+The #initialize method takes a couple of options:
+
+  * connect: whether or not to connect to a running instance
+  * constants: whether or not to load constants
+
+These options will, when given, override the class-level defaults.
+
+### Events ###
+
+COM events are easily dealt with:
+
+    class Word::Application < COM::Instantiable
+      def initialize(options = {})
+        super
+        @events = COM::Events.new(com, 'ApplicationEvents',
+                                  'OnQuit')
+      end
+
+      def quit(saving = Word::WdDoNotSaveChanges, *args)
+        @events.observe('OnQuit', proc{ com.quit saving, *args }) do
+          yield if block_given?
+        end
+      end
+    end
+
+To tell you the truth this API sucks and will most likely be rewritten.  The
+reason that it is the way it is is that WIN32OLE, which COM wraps, sucks.  It’s
+event API is horrid and the implementation is buggy.  It will keep every
+registered event block in memory for ever, freeing neither the blocks nor the
+COM objects that yield the events.
+
+### Errors ###
+
+All errors generated by COM methods descend from COM::Error, except for those
+cases where a Ruby error already exists.  The following HRESULT error codes are
+turned into Ruby errors:
+
+  HRESULT Error Code | Error Class
+  -------------------|------------
+  0x80004001         | NotImplementedError
+  0x80020005         | TypeError
+  0x80020006         | NoMethodError
+  0x8002000e         | ArgumentError
+  0x800401e4         | ArgumentError
+
+There are also a couple of other HRESULT error codes that are turned into more
+specific errors than COM::Error:
+
+  HRESULT Error Code | Error Class
+  -------------------|------------
+  0x80020003         | MemberNotFoundError
+  0x800401e3         | OperationUnavailableError
+
+Finally, when a method results in any other error, a COM::MethodInvocationError
+will be raised, which can be queried for the specifics, specifically #message,
+ #method, #server, #code, #hresult_code, and #hresult_message.
+
+### Pathname ###
+
+The Pathname object receives an additional method, #to_com.  This method is
+useful for when you want to pass a Pathname object to a COM method.  Simply
+call #to_com to turn it into a String of the right encoding for COM:
+
+    Word::Application.new.documents.open(Pathname('a.docx').to_com)
+    # ⇒ Word::Document
+
+
+## Installation ##
+
+Install COM with
+
+    % gem install com
+
+
+## License ##
+
+You may use, copy and redistribute this library under the same [terms][1] as
+Ruby itself.
+
+[1]: http://www.ruby-lang.org/en/LICENSE.txt
+
+
+## Contributors ##
+
+  * Nikolai Weibull

data/Rakefile

@@ -0,0 +1,10 @@
+# -*- coding: utf-8 -*-
+
+require 'lookout/rake/tasks'
+require 'yard'
+
+Lookout::Rake::Tasks::Test.new
+Lookout::Rake::Tasks::Gem.new
+YARD::Rake::YardocTask.new do |t|
+  t.options.concat %w[--markup markdown]
+end

data/lib/com.rb

@@ -0,0 +1,73 @@
+# -*- coding: utf-8 -*-
+
+require 'win32ole'
+WIN32OLE.codepage = WIN32OLE::CP_UTF8
+
+# COM is an object-oriented wrapper around WIN32OLE.  COM makes it easy to add
+# behavior to WIN32OLE objects, making them easier to work with from Ruby.
+module COM
+  autoload :Error, 'com/error'
+  autoload :Events, 'com/events'
+  autoload :Instantiable, 'com/instantiable'
+  autoload :Object, 'com/object'
+  autoload :PatternError, 'com/patternerror'
+  autoload :Version, 'com/version'
+  autoload :Wrapper, 'com/wrapper'
+
+  class << self
+    # Gets the iconv character set equivalent of the current COM code page.
+    #
+    # @raise [RuntimeError] If no iconv charset is associated with the current
+    #   COM codepage
+    # @return [String] The iconv character set
+    def charset
+      COMCodePageToIconvCharset[WIN32OLE.codepage] or
+        raise 'no iconv charset associated with current COM codepage: %s' %
+          WIN32OLE.codepage
+    end
+
+    # Connects to a running COM object.
+    #
+    # This method shouldn’t be used directly, but rather is used by
+    # COM::Object.
+    #
+    # @param [String] id The program ID of the COM object to connect to
+    # @raise [COM::Error] Any error that may have occurred while trying to
+    #   connect
+    # @return [COM::MethodMissing] The running COM object wrapped in a
+    #   COM::MethodMissing
+    def connect(id)
+      Wrapper.new(WIN32OLE.connect(id))
+    rescue WIN32OLERuntimeError => e
+      raise Error.from(e)
+    end
+
+    # Creates a new COM object.
+    #
+    # This method shouldn’t be used directly, but rather is used by
+    # COM::Object.
+    #
+    # @param [String] id The program ID of the COM object to create
+    # @param [String, nil] host The host of the program ID
+    # @raise [COM::Error] Any error that may have occurred while trying to
+    #   create the COM object
+    # @return [COM::MethodMissing] The COM object wrapped in a COM::MethodMissing
+    def new(id, host = nil)
+      Wrapper.new(WIN32OLE.new(id, host))
+    rescue WIN32OLERuntimeError => e
+      raise Error.from(e)
+    end
+  end
+
+private
+
+  # @private
+  COMCodePageToIconvCharset = {
+    WIN32OLE::CP_UTF8 => 'UTF-8'
+  }.freeze
+end
+
+require 'com/methodinvocationerror'
+require 'com/pathname'
+require 'com/standarderror'
+require 'com/win32ole'

data/lib/com/error.rb

@@ -0,0 +1,44 @@
+# -*- coding: utf-8 -*-
+
+# Superclass for COM-related errors.  This class is meant to be subclassed an
+# used for refinement of otherwise very unspecific COM errors.
+#
+# @see COM::StandardError
+class COM::Error < RuntimeError
+  class << self
+    # Creates a COM::Error from _error_, with optional _backtrace_.  _Error_
+    # should be an error raised by WIN32OLE.
+    #
+    # This is an internal method.
+    #
+    # @param [WIN32OLERuntimeError] error The error to create a new one from
+    # @param [Array<String>, nil] backtrace The backtrace to use for the new
+    #   error
+    def from(error, backtrace = nil)
+      errors.find{ |replacement| replacement.replaces? error }.replace(error).tap{ |e|
+        e.set_backtrace backtrace if backtrace
+      }
+    end
+
+    # @private method used by {.from}.
+    def replaces?(error)
+      true
+    end
+
+  protected
+
+    def replace(error)
+      new(error.message)
+    end
+
+  private
+
+    def inherited(error)
+      errors.unshift error
+    end
+
+    def errors
+      @@errors ||= [self]
+    end
+  end
+end

data/lib/com/events.rb

@@ -0,0 +1,68 @@
+# -*- coding: utf-8 -*-
+
+# Provides a simple wrapper around COM events.  WIN32OLE provides no way of
+# releasing an observer and thus causes an unbreakable chain of objects,
+# causing uncollectable garbage.  This class obviates most of the problems.
+class COM::Events
+  ArgumentMissing = Object.new.freeze
+
+  # Creates a COM events wrapper for the COM object _com_’s _interface_.
+  # Optionally, any _events_ may be given as additional arguments.
+  #
+  # @param [WIN32OLE] com COM object implementing _interface_
+  # @param [String] interface Name of the COM interface that _com_ implements
+  # @param [Array<String>] events Names of events to register (see
+  #   {#register})
+  def initialize(com, interface = nil)
+    @interface = WIN32OLE_EVENT.new(com, interface)
+    @events = {}
+  end
+
+  # Observe _event_ in _block_ during the execution of _during_.
+  #
+  # @param [String] event Name of the event to observe
+  # @param [Proc] during Block during which to observe _event_
+  # @yield [*args] Event arguments (specific for each event)
+  # @return The result of _during_
+  def observe(event, observer = ArgumentMissing)
+    if ArgumentMissing.equal? observer
+      register event, Proc.new
+      return self
+    end
+    return self unless observer
+    observer = observer.to_proc
+    register event, observer
+    return self unless block_given?
+    begin
+      yield
+    ensure
+      unobserve event, observer
+    end
+    self
+  end
+
+  def unobserve(event, observer = nil)
+    @events[event].delete observer if observer
+    if observer.nil? or @events[event].empty?
+      @interface.off_event event
+      @events.delete event
+    end
+    self
+  end
+
+  private
+
+  def register(event, observer)
+    if @events.include? event
+      @events[event] << observer
+      return
+    end
+    @interface.on_event event do |*args|
+      @events[event].reduce({}){ |result, o|
+        r = o.call(*args)
+        result.merge! r if Hash === r
+      }
+    end
+    @events[event] = [observer]
+  end
+end

data/lib/com/instantiable.rb

@@ -0,0 +1,135 @@
+# -*- coding: utf-8 -*-
+
+# Represents instantiable COM objects.  These are COM objects that we can
+# connect to and create.
+class COM::Instantiable < COM::Object
+  class << self
+    # Gets or sets the COM program ID.
+    #
+    # If no program ID has explicitly been set, one based on the name of this
+    # class and its containing module.  For example, A::B is turned into
+    # 'A.B'.
+    #
+    # @param [String,nil] id Program ID to, if given, use
+    # @return [String] The set or automatically generated program ID
+    # @raise [ArgumentError] If no program ID has been set and one can’t be
+    #   automatically generated
+    def program_id(id = nil)
+      @id = id if id
+      return @id if defined? @id
+      raise ArgumentError,
+        'no automatic COM program ID for class available: %s' % self unless
+          matches = /^.*?([^:]+)::([^:]+)$/.match(name)
+      @id = '%s.%s' % matches[1..2]
+    end
+
+    # Marks this class as trying to connect to already running instances of COM
+    # objects.
+    #
+    # @return true
+    def connect
+      @connect = true
+    end
+
+    # Queries whether or not this class tries to connect to already running
+    # instances of COM objects.
+    #
+    # The default is false.
+    #
+    # @return Whether or not this class tries to connect to already running
+    #   instances of COM objects
+    #
+    # @see #connect
+    def connect?
+      @connect ||= false
+    end
+
+    # Sets whether or not this class tries to load constants when connecting to
+    # or creating a COM object.
+    #
+    # @param [Boolean] constants Whether or not to load constans
+    # @return [Boolean] Whether or not to load constants
+    def constants(constants)
+      @constants = constants
+    end
+
+    # Queries whether or not this class tries to load constans when connecting
+    # to or creating a COM object.
+    #
+    # The default is true.
+    #
+    # @return Whether or not to load constants
+    def constants?
+      return true unless defined? @constants
+      @constants
+    end
+
+    # Loads constants associated with COM object _com_.  This is an internal
+    # method that shouldn’t be called outside of this class.
+    #
+    # @param [WIN32OLE] com COM object to load constants from
+    # @return [Boolean] Whether or not any constants where loaded
+    def load_constants(com)
+      return if constants_loaded?
+      modul = nesting[-2]
+      com.load_constants modul
+      @constants_loaded = true
+    end
+
+    # Queries whether constants have already been loaded for this class.
+    #
+    # @return Whether or not constants have already been loaded for this class
+    def constants_loaded?
+      @constants_loaded ||= false
+    end
+
+  private
+
+    # Gets the nesting of modules that lead up to this class.
+    #
+    # @return [Array<Module>] Modules that nest this class
+    def nesting
+      result = []
+      name.split(/::/).inject(Module) do |modul, name|
+        modul.const_get(name).tap{ |c| result << c }
+      end
+      result
+    end
+  end
+
+  # Connects to or creates a new instance of a COM object.
+  #
+  # @option options [Boolean] :connect (false) Whether or not to connect to a
+  #   running instance (see {.connect})
+  # @option options [Boolean] :constants (true) Whether or not to load
+  #   constants associated with the COM object (see {.constants})
+  def initialize(options = {})
+    @connected = false
+    connect if options.fetch(:connect, self.class.connect?)
+    self.com = COM.new(self.class.program_id) unless connected?
+    self.class.load_constants(com) if
+      options.fetch(:constants, self.class.constants?)
+  end
+
+  # Queries whether or not an already running COM object was connected to.
+  # This is useful when deciding whether or not to close down the COM object
+  # when you’re done with it.
+  #
+  # @return Whether or not an already running COM object was connected to
+  def connected?
+    @connected
+  end
+
+  def inspect
+    '#<%s%s>' % [self.class, connected? ? ' connected' : '']
+  end
+
+private
+
+  # Try to connect to a running COM object.
+  def connect
+    self.com = COM.connect(self.class.program_id)
+    @connected = true
+  rescue COM::OperationUnavailableError
+  end
+end