com 0.3.0

data/test/unit/com/methodinvocationerror.rb

@@ -0,0 +1,67 @@
+# -*- coding: utf-8 -*-
+
+Expectations do
+  expect COM::MethodInvocationError do
+    COM::Error.from(stub(:message => %{method
+  OLE error code:123abcDE in server
+    message
+  HRESULT error code:0x123abcDE
+    hresult message}))
+  end
+
+  expect 'method' do
+    COM::Error.from(stub(:message => %{method
+  OLE error code:123abcDE in server
+    message
+  HRESULT error code:0x123abcDE
+    hresult message})).method
+  end
+
+  expect 'server' do
+    COM::Error.from(stub(:message => %{method
+  OLE error code:123abcDE in server
+    message
+  HRESULT error code:0x123abcDE
+    hresult message})).server
+  end
+
+  expect 0x123abcDE do
+    COM::Error.from(stub(:message => %{method
+  OLE error code:123abcDE in server
+    message
+  HRESULT error code:0x123abcDE
+    hresult message})).code
+  end
+
+  expect 0x123abcDE do
+    COM::Error.from(stub(:message => %{method
+  OLE error code:123abcDE in server
+    message
+  HRESULT error code:0x123abcDE
+    hresult message})).hresult_code
+  end
+
+  expect 'hresult message' do
+    COM::Error.from(stub(:message => %{method
+  OLE error code:123abcDE in server
+    message
+  HRESULT error code:0x123abcDE
+    hresult message})).hresult_message
+  end
+
+  expect 'message' do
+    COM::Error.from(stub(:message => %{method
+  OLE error code:123abcDE in server
+    message
+  HRESULT error code:0x123abcDE
+    hresult message})).message
+  end
+
+  expect 'message' do
+    COM::Error.from(stub(:message => %{method
+  OLE error code:123abcDE in server
+    message
+  HRESULT error code:0x123abcDE
+    hresult message})).to_s
+  end
+end

data/test/unit/com/object.rb

@@ -0,0 +1,33 @@
+# -*- coding: utf-8 -*-
+
+Expectations do
+=begin
+  expect :result do
+    COM::Object.new(stub).with_properties({}){ :result }
+  end
+
+  expect 1 do
+    o = {:a => 1}
+    COM::Object.new(o).with_properties(:a => 2){ }
+    o[:a]
+  end
+
+  expect 1 do
+    o = {:a => 1}
+    COM::Object.new(o).with_properties(:a => 2){ raise } rescue nil
+    o[:a]
+  end
+
+  expect 2 do
+    o = {:a => 1}
+    v = nil
+    COM::Object.new(o).with_properties(:a => 2){ v = o[:a] } rescue nil
+    o[:a]
+    v
+  end
+=end
+
+  expect StandardError do
+    COM::Object.new(stub).with_properties({}){ raise StandardError }
+  end
+end

data/test/unit/com/pathname.rb

@@ -0,0 +1,21 @@
+# -*- coding: utf-8 -*-
+
+require 'pathname'
+
+Expectations do
+  expect 'c:/a' do
+    stub(COM).charset{ 'UTF-8' }
+    Pathname('c:/a').to_com
+  end
+
+  expect 'c:/å' do
+    stub(COM).charset{ 'UTF-8' }
+    Pathname('c:/å').to_com
+  end
+
+  # ANSI and ISO-8859-1 å
+  expect 'c:/å' do
+    stub(COM).charset{ 'UTF-8' }
+    Pathname("c:/\xe5".force_encoding('Windows-1252')).to_com
+  end
+end

data/test/unit/com/standarderror.rb

@@ -0,0 +1,27 @@
+# -*- coding: utf-8 -*-
+
+Expectations do
+  expect NotImplementedError do
+    COM::Error.from(stub(:message => "\nHRESULT error code:0x80004001\n"))
+  end
+
+  expect NoMethodError do
+    COM::Error.from(stub(:message => "\nHRESULT error code:0x80020006\n"))
+  end
+
+  expect ArgumentError do
+    COM::Error.from(stub(:message => "\nHRESULT error code:0x8002000e\n"))
+  end
+
+  expect ArgumentError do
+    COM::Error.from(stub(:message => "\nHRESULT error code:0x800401e4\n"))
+  end
+
+  expect COM::OperationUnavailableError do
+    COM::Error.from(stub(:message => "\nHRESULT error code:0x800401e3\n"))
+  end
+
+  expect NameError.new('unknown COM server: A.B') do
+    COM::Error.from(stub(:message => "unknown OLE server: `A.B'\n    HRESULT error code:0x800401f3\n"))
+  end
+end

metadata

@@ -0,0 +1,178 @@
+--- !ruby/object:Gem::Specification
+name: com
+version: !ruby/object:Gem::Version
+  version: 0.3.0
+  prerelease: 
+platform: ruby
+authors:
+- Nikolai Weibull
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2011-10-14 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: lookout
+  requirement: &14503188 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: *14503188
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: &14502792 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.6.0
+  type: :development
+  prerelease: false
+  version_requirements: *14502792
+description: ! "# COM #\n\nCOM is an object-oriented wrapper around WIN32OLE.  COM
+  makes it easy to add\nbehavior to WIN32OLE objects, making them easier to work with
+  from Ruby.\n\n\n## Usage ##\n\nUsing COM is rather straightforward.  There’s basically
+  four concepts to keep\ntrack of:\n\n  1. COM objects\n  2. Instantiable COM objects\n
+  \ 3. COM events\n  4. COM errors\n\nLet’s look at each concept separately, using
+  the following example as a base.\n\n    module Word end\n\n    class Word::Application
+  < COM::Instantiable\n      def without_interaction\n        with_properties('displayalerts'
+  => Word::WdAlertsNone){ yield }\n      end\n\n      def documents\n        Word::Documents.new(com.documents)\n
+  \     end\n\n      def quit(saving = Word::WdDoNotSaveChanges, *args)\n        com.quit
+  saving, *args\n      end\n    end\n\n### COM Objects ###\n\nA COM::Object is a wrapper
+  around a COM object.  It provides error\nspecialization, which is discussed later
+  and a few utility methods.  You\ntypically use it to wrap COM objects that are returned
+  by COM methods.  If we\ntake the example given in the introduction, Word::Documents
+  is a good\ncandidate:\n\n    class Word::Documents < COM::Object\n      DefaultOpenOptions
+  = {\n        'confirmconversions' => false,\n        'readonly' => true,\n        'addtorecentfiles'
+  => false,\n        'visible' => false\n      }.freeze\n      def open(path, options
+  = {})\n        options = DefaultOpenOptions.merge(options)\n        options['filename']
+  = Pathname(path).to_com\n        Word::Document.new(com.open(options))\n      end\n
+  \   end\n\nHere we override the #open method to be a bit easier to use, providing
+  sane\ndefaults for COM interaction.  Worth noting is the use of the #com method
+  to\naccess the actual COM object to invoke the #open method on it.  Also note that\nWord::Document
+  is also a COM::Object.\n\nCOM::Object provides a convenience method called #with_properties,
+  which is\nused in the #without_interaction method above.  It lets you set properties
+  on\nthe COM::Object during the duration of a block, restoring them after it exits\n(successfully
+  or with an error).\n\n\n### Instantiable COM Objects ###\n\nInstantiable COM objects
+  are COM objects that we can connect to and that can be\ncreated.  The Word::Application
+  object can, for example, be created.\nInstantiable COM objects should inherit from
+  COM::Instantiable.  Instantiable\nCOM objects can be told what program ID to use,
+  whether or not to allow\nconnecting to an already running object, and to load its
+  associated constants\nupon creation.\n\nThe program ID is used to determine what
+  instantiable COM object to connect to.\nBy default the name of the COM::Instantiable
+  class’ name is used, taking the\nlast two double-colon-separated components and
+  joining them with a dot.  For\nWord::Application, the program ID is “Word.Application”.
+  \ The program ID can be\nset by using the .program_id method:\n\n    class IDontCare::ForConventions
+  < COM::Instantiable\n      program_id 'Word.Application'\n    end\n\nThe program
+  ID can be accessed with the same method:\n\n    Word::Application.program_id # ⇒
+  'Word.Application'\n\nConnecting to an already running COM object is not done by
+  default, but is\nsometimes desirable: the COM object might take a long time to create,
+  or some\ncommon state needs to be accessed.  If the default for a certain instantiable\nCOM
+  object should be to connect, this can be done using the .connect method:\n\n    class
+  Word::Application < COM::Instantiable\n      connect\n    end\n\nIf no running COM
+  object is available, then a new COM object will be created in\nits stead.  Whether
+  or not a class uses the connection method can be queried\nwith the .connect? method:\n\n
+  \   Word::Application.connect? # ⇒ true\n\nWhether or not to load constants associated
+  with an instantiable COM object is\nset with the .constants method:\n\n    class
+  Word::Application < COM::Instantiable\n      constants true\n    end\n\nand can
+  similarly be checked:\n\n    Word::Application.constants? # ⇒ true\n\nConstants
+  are loaded by default.\n\nWhen an instance of the instantiable COM object is created,
+  a check is run to\nsee if constants should be loaded and whether or not they already
+  have been\nloaded.  If they should be loaded and they haven’t already been loaded,\nthey’re,
+  you guessed it, loaded.  The constants are added to the module\ncontaining the COM::Instantiable.
+  \ Thus, for Word::Application, the Word module\nwill contain all the constants.
+  \ Whether or not the constants have already been\nloaded can be checked with .constants_loaded?:\n\n
+  \   Word::Application.constants_loaded # ⇒ false\n\nThat concludes the class-level
+  methods.\n\nLet’s begin with the #connected? method among the instance-level methods.
+  \ This\nmethod queries whether or not this instance connected to an already running
+  COM\nobject:\n\n    Word::Application.new.connected? # ⇒ false\n\nThis can be very
+  important in determining how shutdown of a COM object should\nbe done.  If you connected
+  to an already COM object it might be foolish to shut\nit down if someone else is
+  using it.\n\nThe #initialize method takes a couple of options:\n\n  * connect: whether
+  or not to connect to a running instance\n  * constants: whether or not to load constants\n\nThese
+  options will, when given, override the class-level defaults.\n\n### Events ###\n\nCOM
+  events are easily dealt with:\n\n    class Word::Application < COM::Instantiable\n
+  \     def initialize(options = {})\n        super\n        @events = COM::Events.new(com,
+  'ApplicationEvents',\n                                  'OnQuit')\n      end\n\n
+  \     def quit(saving = Word::WdDoNotSaveChanges, *args)\n        @events.observe('OnQuit',
+  proc{ com.quit saving, *args }) do\n          yield if block_given?\n        end\n
+  \     end\n    end\n\nTo tell you the truth this API sucks and will most likely
+  be rewritten.  The\nreason that it is the way it is is that WIN32OLE, which COM
+  wraps, sucks.  It’s\nevent API is horrid and the implementation is buggy.  It will
+  keep every\nregistered event block in memory for ever, freeing neither the blocks
+  nor the\nCOM objects that yield the events.\n\n### Errors ###\n\nAll errors generated
+  by COM methods descend from COM::Error, except for those\ncases where a Ruby error
+  already exists.  The following HRESULT error codes are\nturned into Ruby errors:\n\n
+  \ HRESULT Error Code | Error Class\n  -------------------|------------\n  0x80004001
+  \        | NotImplementedError\n  0x80020005         | TypeError\n  0x80020006         |
+  NoMethodError\n  0x8002000e         | ArgumentError\n  0x800401e4         | ArgumentError\n\nThere
+  are also a couple of other HRESULT error codes that are turned into more\nspecific
+  errors than COM::Error:\n\n  HRESULT Error Code | Error Class\n  -------------------|------------\n
+  \ 0x80020003         | MemberNotFoundError\n  0x800401e3         | OperationUnavailableError\n\nFinally,
+  when a method results in any other error, a COM::MethodInvocationError\nwill be
+  raised, which can be queried for the specifics, specifically #message,\n #method,
+  #server, #code, #hresult_code, and #hresult_message.\n\n### Pathname ###\n\nThe
+  Pathname object receives an additional method, #to_com.  This method is\nuseful
+  for when you want to pass a Pathname object to a COM method.  Simply\ncall #to_com
+  to turn it into a String of the right encoding for COM:\n\n    Word::Application.new.documents.open(Pathname('a.docx').to_com)\n
+  \   # ⇒ Word::Document\n\n\n## Installation ##\n\nInstall COM with\n\n    % gem
+  install com\n\n\n## License ##\n\nYou may use, copy and redistribute this library
+  under the same [terms][1] as\nRuby itself.\n\n[1]: http://www.ruby-lang.org/en/LICENSE.txt\n\n\n##
+  Contributors ##\n\n  * Nikolai Weibull\n"
+email: now@bitwi.se
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/com/error.rb
+- lib/com/events.rb
+- lib/com/instantiable.rb
+- lib/com/methodinvocationerror.rb
+- lib/com/object.rb
+- lib/com/pathname.rb
+- lib/com/patternerror.rb
+- lib/com/standarderror.rb
+- lib/com/version.rb
+- lib/com/win32ole.rb
+- lib/com/wrapper.rb
+- lib/com.rb
+- test/unit/com/error.rb
+- test/unit/com/events.rb
+- test/unit/com/instantiable.rb
+- test/unit/com/methodinvocationerror.rb
+- test/unit/com/object.rb
+- test/unit/com/pathname.rb
+- test/unit/com/standarderror.rb
+- test/unit/com.rb
+- README
+- Rakefile
+homepage: http://github.com/now/com
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.10
+signing_key: 
+specification_version: 4
+summary: COM is an object-oriented wrapper around WIN32OLE.
+test_files: []