Ruby 1.9.3 リファレンスマニュアル > ライブラリ一覧 > win32oleライブラリ > WIN32OLEクラス

class WIN32OLE + Object

クラスの継承リスト: WIN32OLE < Object < Kernel < BasicObject

要約

OLEオートメーションサーバをRubyで操作するためのクラスです。

Windowsの多くのアプリケーションやライブラリは、COMと呼ばれるAPI群を利用して他のプログラムから操作できます。WIN32OLEがサポートしているのは、 COMのAPIのうち、特にインタープリタ用のインターフェイスであるOLEオートメーション（IDispatchインターフェイス）とそれに付随するリフレクション用のインターフェイスです。

これらのインターフェイスをサポートしている代表的なWindowsアプリケーションに、Office、IE、iTunes、Illustratorがあります。また、WMI、WshShellなどのライブラリを利用してWindowsの情報を操作することも可能です。これらのプログラムをOLEオートメーションサーバと呼びます。

WIN32OLEオブジェクトは、OLEオートメーションサーバが提供するメソッドやプロパティ（Rubyの属性に対応）をスクリプトから呼び出す手段を提供します。呼び出しには、Rubyのオブジェクトと同様にオブジェクトに続けて「.」とメソッド名、必要であれば引数のリストを記述します。最後の引数にHashを指定した場合は、名前付き引数としてキーにパラメータ名、値に引数を指定できます。

サンプルコード

require 'win32ole'

excel = WIN32OLE.new('Excel.Application')
workbook = excel.Workbooks.Open('workbook.xls')
workbook.PrintOut
workbook.Close(:SaveChanges => false)
excel.Quit

なお、OLEオートメーションの仕様ではメソッド名は大文字と小文字を区別しません。そのため、以下のようにOLEオートメーションサーバのメソッド名は小文字で記述しても構いません。

require 'win32ole'

excel = WIN32OLE.new('Excel.Application')
workbook = excel.workbooks.open('workbook.xls')
workbook.printout
workbook.close(:SaveChanges => false)
excel.quit

マルチスレッドでの利用制限

注）以下の記述はWIN32OLEの将来のバージョンの仕様を規定するものではありません。

WIN32OLEはシングルスレッドモードでCOMとインターフェイスします。このため、 ruby 1.9以降のRubyのThreadとネイティブスレッドが1対1で対応する実行環境ではスレッドをまたがる呼び出しはエラーとなります。

excel = WIN32OLE.new('Excel.Application')
Thread.start do
  workbook = excel.Workbooks.Open('workbook.xls') #=> HRESULT error code:0x800401f0
  workbook.PrintOut
  workbook.Close(:SaveChanges => false)
end.join
excel.Quit

発生するエラーはThreadの実行方法によって 0x800401f0（CO_E_NOTINITIALIZED）または0x8001010e（RPC_E_WRONG_THREAD）です。

特異メソッド

codepage -> Fixnum

WIN32OLEがOLEオートメーションのインターフェイスに利用するコードページを取得します。

OLEオートメーションに利用する文字列はUnicodeでエンコードします。 WIN32OLEはここで示されたコードページを利用してRubyのStringとUnicodeの相互変換を行います。

ロード時の既定値はEncoding.default_internal、または Encoding.default_internalがnilの場合はEncoding.default_externalによって求めたエンコーディングに対応するコードページです。もし、該当するコードページが見つからない場合は、WIN32OLE::CP_ACPを利用します。

[RETURN]: WIN32OLEがオートメーション呼び出しの文字列変換に利用するコードページを返します。

WIN32OLE.codepage   # => 932 （日本語Windowsの既定値）

codepage=(cp) -> nil

WIN32OLEがOLEオートメーションのインターフェイスに利用するコードページを設定します。

WIN32OLEは、OLEオートメーション呼び出しに利用する文字列のUnicode変換にここで設定したコードページを利用します。通常、WIN32OLEはロード時の Encoding.default_internalまたはEncoding.default_externalから適切なコードページを判断し、それを利用します。したがって、当メソッドを呼び出す必要があるのは、WIN32OLEをrequireしたスクリプトと異なるエンコーディングを利用しているスクリプトや、異なるエンコーディングを利用しているファイルから読み込んだ文字列を利用してWIN32OLEを呼び出す場合です。

[PARAM] cp:: コードページを指定します。

WIN32OLE.codepage = WIN32OLE::CP_UTF8

connect(ole) -> WIN32OLE

現在実行中のOLEオートメーションサーバに接続します。

connectメソッドは、COMのモニカを利用して、現在実行中のOLEオートメーションサーバを検索し、接続します。接続に成功した場合、該当サーバを操作可能なWIN32OLEオブジェクトが返ります。

[PARAM] ole:: 接続対象のサーバを示すPROGID、CLSIDまたはモニカ（別名）を指定します。
[RETURN]: ole引数で特定されるWIN32OLEオブジェクトを返します。
[EXCEPTION] WIN32OLERuntimeError:: オートメーションサーバの呼び出しに失敗しました。理由はメッセージのHRESULTを調べてください。

WIN32OLE.connect('Excel.Application') # => WIN32OLE object which represents running Excel.

PROGID: OLEオートメーションサーバを識別するための文字列。通常「ベンダー名.アプリケーション名.インターフェイス名」の形式を取ります。レジストリの HKEY_CLASSES_ROOTの「.」で始まらないキーとして登録されます。
CLSID: OLEオートメーションサーバを含むCOMのクラスを識別するための128ビット GUID。文字列表現は、レジストリのHKEY_CLASSES_ROOT\CLSID下のキーとして登録されます。
モニカ: モニカは、URIのようにWindows上のリソースを一意に識別するためのオブジェクトのインターフェイスで、文字表現を持ちます。詳細については http://msdn.microsoft.com/en-us/library/ms691261(v=VS.85).aspx を参照してください。

const_load(ole, mod = WIN32OLE) -> ()

OLEオートメーションサーバが保持する定数を読み込み、指定されたモジュールに組み込みます。

OLEオートメーションサーバは、定数をクライアントへ提供できます。

const_loadメソッドはこれらの定数を読み込み、指定したモジュールに組み込むことで参照可能とします。

[PARAM] ole:: 定数を読み込む対象のWIN32OLEオブジェクトまたはタイプライブラリ名（文字列）を指定します。
[PARAM] mod:: 定数を定義する対象のモジュールを指定します。省略時は WIN32OLEに組み込まれます。
[EXCEPTION] WIN32OLERuntimeError:: オートメーションサーバの呼び出しに失敗しました。理由はメッセージのHRESULTを調べてください。

OLEオートメーションの定数は通常、VBのコード規約に準じて、vbConstantsのように小文字で始まります。しかし、Rubyの定数は大文字で開始する規則のため、WIN32OLEによってVbConstantsのように自動的に先頭が大文字化されます。

また、先頭が英字で始まらない定数については、CONSTANTSハッシュに登録されます。この場合、元の定数名がキーとなります。

module EXCEL_CONST
end

excel = WIN32OLE.new('Excel.Application')
WIN32OLE.const_load(excel, EXCEL_CONST)
puts EXCEL_CONST::XlTop # => -4160
puts EXCEL_CONST::CONSTANTS['_xlDialogChartSourceData'] # => 541

モジュール名を省略した例

WIN32OLE.const_load(excel)
puts WIN32OLE::XlTop # => -4160

タイプライブラリ名を指定した例

module MSO
end

WIN32OLE.const_load('Microsoft Office 9.0 Object Library', MSO)
puts MSO::MsoLineSingle # => 1

create_guid -> String

GUID(グローバル一意識別子：Global Unique Identifier)を生成します。

GUIDは、COMのクラス識別子(CLSID)、インターフェイス識別子(IID)など多数の領域でWindows上のオブジェクトの識別に利用される128ビットの値です。

WIN32OLEが生成するGUIDは以下の形式によるGUIDの文字列表現です。なお00〜 FFはGUIDの先頭からのバイト位置を示します。これはレジストリのキーとして利用される形式です。

{33221100-5544-7766-8899-AABBCCDDEEFF}

[RETURN]: GUIDの文字列表現を返します。

WIN32OLE.create_guid   # => "{????????-????-????-????-????????????}"

locale -> Fixnum

WIN32OLEがオートメーション呼び出し時に設定するロケール識別子(LCID)を取得します。

OLEオートメーションでは、UNIXで利用される"ja_JP"などの国名と言語名を「_」で接続した文字列ではなく、32ビット整数で示します。32ビットの内訳は上位 16ビットが予約領域で0、下位16ビットが言語ID(LANGID）です。LANGIDは、0〜 9ビットでプライマリ言語ID、10〜15ビットでサブ言語IDを示します。

ロード時の既定値はWIN32OLE::LOCALE_SYSTEM_DEFAULTです。

[RETURN]: WIN32OLEがオートメーション呼び出し時に設定するロケール識別子 (LCID)を返します。

lcid = WIN32OLE.locale

locale=(lcid) -> nil

WIN32OLEがオートメーション呼び出し時に設定するロケール識別子(LCID)を設定します。

[PARAM] lcid:: 新たに設定するロケール識別子を整数で指定します。
[EXCEPTION] WIN32OLERuntimeError:: システムにインストールされていないロケールを指定すると発生します。

WIN32OLE.locale = 1033 # set locale English(U.S)
obj = WIN32OLE_VARIANT.new("$100,000", WIN32OLE::VARIANT::VT_CY)

オブジェクトがサポートしていないロケールを設定した場合、オブジェクトのメソッド呼び出し時にDISP_E_UNKNOWNLCID(HRESULT error code:0x8002000C)や、TYPE_E_INVDATAREAD(HRESULT error code:0x80028018)などを理由としたWIN32OLERuntimeError例外となります。ほとんどすべての場合において、既定値を変更する必要はありません。

new(server, host=nil) -> WIN32OLE

OLEオートメーションサーバを生成します。

引数で指定したCLSIDまたはPROGIDを持つOLEオートメーションサーバを生成します。生成に成功した場合、該当サーバを操作可能なWIN32OLEオブジェクトが返ります。

CLSIDおよびPROGIDについてはWIN32OLE.connectを参照してください。

[PARAM] server:: OLEオートメーションサーバを示すPROGIDまたはCLSIDを文字列で指定します。
[PARAM] host:: サーバを生成するホストのホスト名またはIPアドレスを文字列で指定します。省略時は現在スクリプトを実行中のホストで生成します。
[RETURN]: hostで指定したホスト上のserver引数で指定したWIN32OLEオブジェクトを返します。
[EXCEPTION] WIN32OLERuntimeError:: オートメーションサーバの呼び出しに失敗しました。理由はメッセージのHRESULTを調べてください。

WIN32OLE.new('Excel.Application') # => Excel OLE Automation WIN32OLE object.

WIN32OLE.new('{00024500-0000-0000-C000-000000000046}') # => Excel OLE Automation WIN32OLE object.

new -> Object

Objectクラスのインスタンスを生成して返します。

some = Object.new
p some #=> #<Object:0x2b696d8>

ole_free(aWIN32OLE) -> Integer

引数で指定したオブジェクトを解放します。

このメソッドは主にWIN32OLEのデバッグおよびWIN32OLEを利用するミドルウェアの実装のために用意されています。このため、メソッドの内部動作は不定です。COMの仕様とWIN32OLEの内部処理に熟知していない場合は使用しないでください。

[PARAM] aWIN32OLE:: 解放するWIN32OLEオブジェクト。
[RETURN]: Releaseの戻り値。COMの仕様上は現在のオブジェクトの参照カウント値を示します。

ole_reference_count(aWIN32OLE) -> Integer

引数で指定したオブジェクトの現在の参照カウント値を返します。

[PARAM] aWIN32OLE:: 参照カウント値を求めるWIN32OLEオブジェクト。
[RETURN]: AddRef呼び出し後のReleaseの戻り値。COMの仕様上は現在のオブジェクトの参照カウント値を示します。

ole_show_help(obj, helpcontext = nil) -> ()

WIN32OLEオブジェクトのヘルプファイルを表示します。

Windows標準のヘルプ表示コンポーネントのHHCtrl.OCXを利用して、オブジェクトに関連付けられたヘルプファイル（chmファイル）を表示します。

また、chmファイルのフルパス名を指定して表示させることも可能です。

[PARAM] obj:: WIN32OLE_TYPEオブジェクトまたはWIN32OLE_METHODオブジェクト。直接ヘルプファイルのフルパス名を指定することも可能です。
[PARAM] helpcontext:: obj引数にWIN32OLE_TYPEオブジェクトまたは WIN32OLE_METHODオブジェクトを指定した場合は、これらのオブジェクトの設定値を利用するため指定不要です。 obj引数にヘルプファイルのフルパス名を設定した場合は 0を指定してください。
[EXCEPTION] RuntimeError:: オブジェクトが関連するヘルプファイルを持たない場合 (no helpfile of `オブジェクト名') や、ヘルプファイルがインストールされていない場合 (failed to open help file `ファイル名') に通知します。

excel = WIN32OLE.new('Excel.Application')
typeobj = excel.ole_obj_help
WIN32OLE.ole_show_help(typeobj) if typeobj.helpfile

インスタンスメソッド

self !~ other -> bool

自身が other とマッチしない事を判定します。

self#=~(obj) を反転した結果と同じ結果を返します。

[PARAM] other:: 判定するオブジェクトを指定します。

[SEE_ALSO] Object#=~

self == other -> bool

オブジェクトと other が等しければ真を返します。

このメソッドは各クラスの性質に合わせて再定義すべきです。多くの場合、オブジェクトの内容が等しければ真を返すように（同値性を判定するように）再定義されることが期待されています。

デフォルトでは equal? と同じオブジェクトの同一性判定になっています。

[PARAM] other:: 比較するオブジェクトです。

p("foo" == "bar") #=> false
p("foo" == "foo") #=> true

p(4 == 4) #=> true
p(4 == 4.0) #=> true

[SEE_ALSO] Object#equal?,Object#eql?

self === other -> bool

メソッド Object#== の別名です。 case 式で使用されます。このメソッドは case 式での振る舞いを考慮して、各クラスの性質に合わせて再定義すべきです。

一般的に所属性のチェックを実現するため適宜再定義されます。

when 節の式をレシーバーとして === を呼び出すことに注意してください。

また Enumerable#grep でも使用されます。

[PARAM] other:: 比較するオブジェクトです。

age = 12
result =
case age
when 0 .. 2
  "baby"
when 3 .. 6
  "little child"
when 7 .. 12
  "child"
when 13 .. 18
  "youth"
else
  "adult"
end

puts result #=> "child"

def check arg
  case arg
  when /ruby(?!\s*on\s*rails)/i
    "hit! #{arg}"
  when String
    "Instance of String class. But don't hit."
  else
    "unknown"
  end
end

puts check([]) #=> unknown
puts check("mash-up in Ruby on Rails") #=> instance of String class. But not hit...
puts check("<Ruby's world>") #=> hit! <Ruby's world>

[SEE_ALSO] Object#==, Range#===, Module#===, Enumerable#grep

self =~ other -> nil

右辺に正規表現オブジェクトを置いた正規表現マッチ obj =~ /RE/ をサポートするためのメソッドです。常に nil を返します。

この定義により、=~ が再定義されたオブジェクトでは正常にマッチを行い、それ以外のものは nil を返すようになります。

[PARAM] other:: 任意のオブジェクトです。結果に影響しません。

obj = 'regexp'
p(obj =~ /re/) #=> 0

obj = nil
p(obj =~ /re/) #=> nil

[SEE_ALSO] String#=~

self[key...] -> object

オブジェクトのデフォルトプロパティを参照します。

OLEオートメーションにはデフォルトプロパティというプロパティ名を指定せずにアクセスできるプロパティがあります。

WIN32OLEからデフォルトプロパティにアクセスするには、[]内に必要なキーを「,」で区切って記述します。シンボルは文字列として扱います。

なおデフォルトプロパティは記述が省略できるプロパティ名に意味がないため、 OLEオートメーション規約ではItemと命名することが決められています。

[PARAM] key:: プロパティでアクセスする情報を特定するキーを指定します。プロパティの特定に複数のキーが必要な場合は「,」で区切って列記します。
[RETURN]: プロパティ値を返します。

fsys = WIN32OLE.new('Scripting.FileSystemObject')
fsys.Drives[:c].FreeSpace #=> Cドライブの空き容量

self[key...] = value

オブジェクトのデフォルトプロパティを設定します。

OLEオートメーションにはデフォルトプロパティというプロパティ名を指定せずにアクセスできるプロパティがあります。

WIN32OLEからデフォルトプロパティにアクセスするには、[]内に必要なキーを記述します。

なおデフォルトプロパティは記述が省略できるプロパティ名には意味がありません。このためOLEオートメーション規約では一律にItemと命名することが決められています。

[PARAM] key:: プロパティでアクセスする情報を特定するキーを指定します。プロパティの特定に複数のキーが必要な場合は「,」で区切って列記します。
[PARAM] value:: プロパティに設定する値を指定します。
[EXCEPTION] WIN32OLERuntimeError:: オートメーションサーバの呼び出しに失敗しました。理由はメッセージのHRESULTを調べてください。

dict = WIN32OLE.new('Scripting.Dictionary')
dict[:a] = 0x41
dict[:b] = 0x42
dict[:a] #=> 65
dict[:b] #=> 66

send(name, *args) -> object

send(name, *args) { .... } -> object

__send__(name, *args) -> object

__send__(name, *args) { .... } -> object

オブジェクトのメソッド name を args を引数にして呼び出し、メソッドの実行結果を返します。

ブロック付きで呼ばれたときはブロックもそのまま引き渡します。

send が再定義された場合に備えて別名 __send__ も用意されており、ライブラリではこちらを使うべきです。また __send__ は再定義すべきではありません。

send, __send__ は、メソッドの呼び出し制限にかかわらず任意のメソッドを呼び出せます。クラス／メソッドの定義/呼び出し制限も参照してください。

[PARAM] name:: 文字列かSymbol で指定するメソッド名です。
[PARAM] args:: 呼び出すメソッドに渡す引数です。

p -365.send(:abs) #=> 365
p "ruby".send(:sub,/./,"R") #=> "Ruby"


class Foo
  def foo() "foo" end
  def bar() "bar" end
  def baz() "baz" end
end

# 任意のキーとメソッド(の名前)の関係をハッシュに保持しておく
# レシーバの情報がここにはないことに注意
methods = {1 => :foo,
  2 => :bar,
  3 => :baz}

# キーを使って関連するメソッドを呼び出す
# レシーバは任意(Foo クラスのインスタンスである必要もない)
p Foo.new.send(methods[1])      # => "foo"
p Foo.new.send(methods[2])      # => "bar"
p Foo.new.send(methods[3])      # => "baz"

[SEE_ALSO] Object#method, Kernel.#eval, Proc, Method

_dump(limit) -> String

Marshal.#dump において出力するオブジェクトがメソッド _dump を定義している場合には、そのメソッドの結果が書き出されます。

バージョン1.8.0以降ではObject#marshal_dump, Object#marshal_loadの使用が推奨されます。 Marshal.dump するオブジェクトが _dump と marshal_dump の両方のメソッドを持つ場合は marshal_dump が優先されます。

メソッド _dump は引数として再帰を制限するレベル limit を受け取り、オブジェクトを文字列化したものを返します。

インスタンスがメソッド _dump を持つクラスは必ず同じフォーマットを読み戻すクラスメソッド _load を定義する必要があります。_load はオブジェクトを表現した文字列を受け取り、それをオブジェクトに戻したものを返す必要があります。

[PARAM] limit:: 再帰の制限レベルを表す整数です。
[RETURN]: オブジェクトを文字列化したものを返すように定義すべきです。

class Foo
  def initialize(arg)
    @foo = arg
  end
  def _dump(limit)
    Marshal.dump(@foo, limit)
  end
  def self._load(obj)
    p obj
    Foo.new(Marshal.load(obj))
  end
end
foo = Foo.new(['foo', 'bar'])
p foo                      #=> #<Foo:0xbaf234 @foo=["foo", "bar"]>
dms = Marshal.dump(foo)
p dms                      #=> "\004\bu:\bFoo\023\004\b[\a\"\bfoo\"\bbar"
result = Marshal.load(dms) #=> "\004\b[\a\"\bfoo\"\bbar" # self._load の引数
p result                   #=> #<Foo:0xbaf07c @foo=["foo", "bar"]>

インスタンス変数の情報は普通マーシャルデータに含まれるので、上例のように _dump を定義する必要はありません(ただし _dump を定義するとインスタンス変数の情報は dump されなくなります)。 _dump/_load はより高度な制御を行いたい場合や拡張ライブラリで定義したクラスのインスタンスがインスタンス変数以外に情報を保持する場合に利用します。(例えば、クラス Time は、_dump/_load を定義しています)

[SEE_ALSO] Object#marshal_dump,Object#marshal_load

_getproperty(dispid, args, types) -> object

DISPIDとパラメータの型を指定してオブジェクトのプロパティを参照します。

アクセスするプロパティのインターフェイスを事前に知っている場合に、 DISPIDとパラメータの型を指定してプロパティを参照します。

[PARAM] dispid:: プロパティのDISPID（メソッドを一意に特定する数値）を指定します。
[PARAM] args:: プロパティが引数を取る場合に配列で指定します。引数の順序は最左端の引数のインデックスを0とします。引数が不要な場合は空配列を指定します。
[PARAM] types:: プロパティが引数を取る場合に配列で引数の型を指定します。引数の順序は最左端の引数のインデックスを0とします。型の指定には、WIN32OLE::VARIANTの定数を利用します。引数が不要な場合は空配列を指定します。

このメソッドはCOMアーリーバインディングを利用することで外部プロセスサーバとのラウンドトリップを減らして処理速度を向上させることを目的としたものです。このため、DLLの形式で型情報（TypeLib）を提供しているサーバに対してはあまり意味を持ちません。

[RETURN]: プロパティ値を返します。
[EXCEPTION] WIN32OLERuntimeError:: オートメーションサーバの呼び出しに失敗しました。理由はメッセージのHRESULTを調べてください。

DISPID_CELLS = 238
include WIN32OLE::VARIANT
excel = WIN32OLE.new('Excel.Application')
puts excel._getproperty(558, [], []) # VisibleプロパティのDISPIDは558
workbook = excel.Workbooks.Add
sheet = workbook.Worksheets[1]
sheet._setproperty(DISPID_CELLS, [1, 2, 'hello'], [VT_I2, VT_I2, VT_BSTR])
puts sheet._getproperty(DISPID_CELLS, [1, 2], [VT_I2, VT_I2]).value  #=> 'hello'
workbook.Close(:SaveChanges => false)
excel.Quit

DISPIDはWIN32OLE_METHOD#dispidから取得できます。

[SEE_ALSO] WIN32OLE::VARIANT

_invoke(dispid, args, types) -> object | nil

DISPIDとパラメータの型を指定してオブジェクトのメソッドを呼び出します。

呼び出すメソッドのインターフェイスを事前に知っている場合に、DISPIDとパラメータの型を指定してメソッドを呼び出します。

このメソッドは引数の変換方法をプログラマが制御できるようにすることと、 COMアーリーバインディングを利用して外部プロセスサーバとのラウンドトリップを減らして処理速度を向上させることを目的としたものです。後者の目的については、DLLの形式で型情報（TypeLib）を提供しているサーバに対してはあまり意味を持ちません。そのため、型の高精度な制御が不要な場合は、直接メソッド名を指定したメソッド呼び出しを行うことを、プログラムの可読性の点から推奨します。

[PARAM] dispid:: メソッドのDISPID（メソッドを一意に特定する数値）を指定します。
[PARAM] args:: メソッドの引数を配列で指定します。引数の順序は最左端の引数のインデックスを0とします。引数が不要な場合は空配列を指定します。
[PARAM] types:: メソッドの引数の型を配列で指定します。引数の順序は最左端の引数のインデックスを0とします。型の指定には、 WIN32OLE::VARIANTの定数を利用します。引数が不要な場合は空配列を指定します。
[RETURN]: メソッドの返り値。ただし返り値を持たないメソッドの場合はnil。
[EXCEPTION] WIN32OLERuntimeError:: オートメーションサーバの呼び出しに失敗しました。理由はメッセージのHRESULTを調べてください。

excel = WIN32OLE.new('Excel.Application')
excel._invoke(302, [], []) #  DISPID 302は、Quitメソッド

MFCの制約により、バイト配列の型情報は通常 WIN32OLE::VARIANT::VT_VARIANTとなります。このような場合に、バイト配列を与えるつもりで

include WIN32OLE::VARIANT
obj.method(DISPID, [[0, 1, 2, 3]], [VT_VARIANT])

のように記述すると、単に32ビット整数（VT_I4）の配列が送られることになり空間効率が低下します。

引数の最終的な型がわかっている場合は、下記の例のように型指定パラメータには実際の型を指定してください。

include WIN32OLE::VARIANT
obj.method(DISPID, [[0, 1, 2, 3]], [VT_BYREF | VT_ARRAY | VT_UI1])

なお、VB6で作成したCOMコンポーネントのパラメータに配列を与える場合は、 WIN32OLE::VARIANT::VT_BYREFの指定が必須です。

DISPIDはWIN32OLE_METHOD#dispidから取得できます。

[SEE_ALSO] WIN32OLE::VARIANT

_setproperty(dispid, args, types) -> ()

DISPIDとパラメータの型を指定してオブジェクトのプロパティを設定します。

アクセスするプロパティのインターフェイスを事前に知っている場合に、 DISPIDとパラメータの型を指定してプロパティを設定します。

[PARAM] dispid:: プロパティのDISPID（メソッドを一意に特定する数値）を指定します。
[PARAM] args:: 引数を配列で指定します。引数の順序は最左端の引数のインデックスを0とします。プロパティに対する設定値は最右端の要素です。
[PARAM] types:: プロパティの引数の型を配列で指定します。引数の順序は最左端の引数のインデックスを0とします。型の指定には、 WIN32OLE::VARIANTの定数を利用します。
[EXCEPTION] WIN32OLERuntimeError:: オートメーションサーバの呼び出しに失敗しました。理由はメッセージのHRESULTを調べてください。

DISPID_CELLS = 238
include WIN32OLE::VARIANT
excel = WIN32OLE.new('Excel.Application')
puts excel._setproperty(558,      # VisibleプロパティのDISPIDは558
                       [true], [VT_BOOL])
workbook = excel.Workbooks.Add
sheet = workbook.Worksheets[1]
sheet._setproperty(DISPID_CELLS, [1, 2, 'hello'], [VT_I2, VT_I2, VT_BSTR])
puts sheet._getproperty(DISPID_CELLS, [1, 2], [VT_I2, VT_I2]).value  #=> 'hello'
workbook.Close(:SaveChanges => false)
excel.Quit

DISPIDはWIN32OLE_METHOD#dispidから取得できます。

[SEE_ALSO] WIN32OLE::VARIANT

class -> Class

レシーバのクラスを返します。

p "ruby".class #=> String
p 999999999999999.class #=> Bignum
p ARGV.class #=> Array
p self.class #=> Object
p Class.class #=> Class
p Kernel.class #=> Module

[SEE_ALSO] Class#superclass,Object#kind_of?,Object#instance_of?

clone -> object

dup -> object

オブジェクトの複製を作成して返します。

dup はオブジェクトの内容, taint 情報をコピーし、 clone はそれに加えて freeze, 特異メソッドなどの情報も含めた完全な複製を作成します。

clone や dup は浅い(shallow)コピーであることに注意してください。後述。

[EXCEPTION] TypeError:: TrueClass, FalseClass, NilClass, Symbol, そして Numeric クラスのインスタンスなど一部のオブジェクトを複製しようとすると発生します。

obj = "string"
obj.taint
def obj.fuga
end
obj.freeze

p(obj.equal?(obj))          #=> true
p(obj == obj)               #=> true
p(obj.tainted?)             #=> true
p(obj.frozen?)              #=> true
p(obj.respond_to?(:fuga))   #=> true

obj_c = obj.clone

p(obj.equal?(obj_c))        #=> false
p(obj == obj_c)             #=> true
p(obj_c.tainted?)           #=> true
p(obj_c.frozen?)            #=> true
p(obj_c.respond_to?(:fuga)) #=> true

obj_d = obj.dup

p(obj.equal?(obj_d))        #=> false
p(obj == obj_d)             #=> true
p(obj_d.tainted?)           #=> true
p(obj_d.frozen?)            #=> false
p(obj_d.respond_to?(:fuga)) #=> false

[SEE_ALSO] Object#initialize_copy

深いコピーと浅いコピー

clone や dup はオブジェクト自身を複製するだけで、オブジェクトの指している先(たとえば配列の要素など)までは複製しません。これを浅いコピー(shallow copy)といいます。

深い(deep)コピーが必要な場合には、 Marshalモジュールを利用して

Marshal.load(Marshal.dump(obj))

このように複製を作成する方法があります。ただしMarshal出来ないオブジェクトが含まれている場合には使えません。

obj = ["a","b","c"]

obj_d = obj.dup
obj_d[0] << "PLUS"

p obj   #=> ["aPLUS", "b", "c"]
p obj_d #=> ["aPLUS", "b", "c"]

obj_m = Marshal.load(Marshal.dump(obj))
obj_m[1] << "PLUS"

p obj   #=> ["aPLUS", "b", "c"]
p obj_m #=> ["aPLUS", "bPLUS", "c"]

display(out = $stdout) -> nil

オブジェクトを out に出力します。

以下のように定義されています。

class Object
  def display(out = $stdout)
    out.print self.to_s
    nil
  end
end

[PARAM] out:: 出力先のIOオブジェクトです。指定しない場合は標準出力に出力されます。
[RETURN]: nil を返します。

Object.new.display #=> #<Object:0xbb0210>

[SEE_ALSO] $stdout

each {|i|...} -> ()

オブジェクトの列挙インターフェイスを呼び出してアイテム単位にブロックを実行します。

OLEオートメーションサーバの中には、コレクション用インターフェイスを持つものがあります。eachメソッドは、このようなオブジェクトの列挙メソッドを呼び出して、アイテム毎のイテレーションを行います。

[PARAM] i:: コレクション内のアイテム
[EXCEPTION] WIN32OLERuntimeError:: selfが列挙インターフェイスをサポートしていない場合に通知します。

excel = WIN32OLE.new('Excel.Application')
book = excel.workbooks.add
sheets = book.worksheets(1)
cells = sheets.cells("A1:A5")
cells.each do |cell|
  cell.value = 10
end
excel.Quit

to_enum(method = :each, *args) -> Enumerator

enum_for(method = :each, *args) -> Enumerator

Enumerator.new(self, method, *args) を返します。

[PARAM] method:: メソッド名の文字列かシンボルです。
[PARAM] args:: 呼び出すメソッドに渡される引数です。
[EXCEPTION] NameError:: 存在しないメソッド名を指定すると発生します。

str = "xyz"

enum = str.enum_for(:each_byte)
p(a = enum.map{|b| '%02x' % b }) #=> ["78", "79", "7a"]

# protects an array from being modified
a = [1, 2, 3]
p(a.to_enum) #=> #<Enumerator: [1, 2, 3]:each>

[SEE_ALSO] Enumerator

eql?(other) -> bool

オブジェクトと other が等しければ真を返します。Hash で二つのキーが等しいかどうかを判定するのに使われます。

このメソッドは各クラスの性質に合わせて再定義すべきです。多くの場合、 == と同様に同値性の判定をするように再定義されていますが、適切にキー判定ができるようにより厳しくなっている場合もあります。

デフォルトでは equal? と同じオブジェクトの同一性判定になっています。

このメソッドを再定義した時には Object#hash メソッドも再定義しなければなりません。

[PARAM] other:: 比較するオブジェクトです。

p("foo".eql?("bar")) #=> false
p("foo".eql?("foo")) #=> true

p(4.eql?(4)) #=> true
p(4.eql?(4.0)) #=> false

[SEE_ALSO] Object#hash,Object#equal?,Object#==

equal?(other) -> bool

other が self 自身の時、真を返します。

二つのオブジェクトが同一のものかどうか調べる時に使用します。このメソッドを再定義してはいけません。

お互いのObject#object_idが一致するかどうかを調べます。

[PARAM] other:: 比較するオブジェクトです。

p("foo".equal?("bar")) #=> false
p("foo".equal?("foo")) #=> false

p(4.equal?(4)) #=> true
p(4.equal?(4.0)) #=> false

p(:foo.equal? :foo) #=> true

[SEE_ALSO] Object#object_id,Object#==,Object#eql?,Symbol

extend(*modules) -> self

引数で指定したモジュールのインスタンスメソッドを self の特異メソッドとして追加します。

Module#include は、クラス(のインスタンス)に機能を追加しますが、extend は、ある特定のオブジェクトだけにモジュールの機能を追加したいときに使用します。

引数に複数のモジュールを指定した場合、最後の引数から逆順に extend を行います。

[PARAM] modules:: モジュールを任意個指定します（クラスは不可）。
[RETURN]: self を返します。

module Foo
  def a
    'ok Foo'
  end
end

module Bar
  def b
    'ok Bar'
  end
end

obj = Object.new
obj.extend Foo, Bar
p obj.a #=> "ok Foo"
p obj.b #=> "ok Bar"

class Klass
  include Foo
  extend Bar
end

p Klass.new.a #=> "ok Foo"
p Klass.b     #=> "ok Bar"

extend の機能は、「特異クラスに対する Module#include」と言い替えることもできます。ただしその場合、フック用のメソッドが Module#extended ではなく Module#included になるという違いがあります。

# obj.extend Foo, Bar とほぼ同じ
class << obj
  include Foo, Bar
end

[SEE_ALSO] Module#extend_object,Module#include,Module#extended

freeze -> self

オブジェクトを凍結（内容の変更を禁止）します。

凍結されたオブジェクトの変更は例外 RuntimeError を発生させます。いったん凍結されたオブジェクトを元に戻す方法はありません。

凍結されるのはオブジェクトであり、変数ではありません。代入などで変数の指すオブジェクトが変化してしまうことは freeze では防げません。 freeze が防ぐのは、 `破壊的な操作' と呼ばれるもの一般です。変数への参照自体を凍結したい場合は、グローバル変数なら Kernel.#trace_var が使えます。

[RETURN]: self を返します。

a1 = "foo".freeze
a1 = "bar"
p a1 #=> "bar"

a2 = "foo".freeze
a2.replace("bar")# can't modify frozen string (RuntimeError)

凍結を解除することはできませんが、Object#dup を使えばほぼ同じ内容の凍結されていないオブジェクトを得ることはできます。

a = [1].freeze
p a.frozen?     #=> true

a[0] = "foo"
p a             # can't modify frozen array (RuntimeError)

b = a.dup
p b             #=> [1]
p b.frozen?     #=> false

b[0] = "foo"
p b             #=> ["foo"]

[SEE_ALSO] Object#frozen?,Object#dup,Kernel.#trace_var

frozen? -> bool

オブジェクトが凍結（内容の変更を禁止）されているときに真を返します。

obj = "someone"
p obj.frozen? #=> false
obj.freeze
p obj.frozen? #=> true

[SEE_ALSO] Object#freeze

hash -> Fixnum

オブジェクトのハッシュ値を返します。Hash クラスでオブジェクトを格納するのに用いられています。

メソッド hash は Object#eql? と組み合わせて Hash クラスで利用されます。その際

A.eql?(B) ならば A.hash == B.hash

の関係を必ず満たしていなければいけません。eql? を再定義した時には必ずこちらも合わせて再定義してください。

デフォルトでは、Object#object_id と同じ値を返します。ただし、Fixnum, Symbol, String だけは組込みのハッシュ関数が使用されます(これを変えることはできません)。

hash を再定義する場合は、一様に分布する任意の整数を返すようにします。

[RETURN]: ハッシュ値を返します。Fixnumに収まらない場合は切り捨てられます。

p self.hash #=> 21658870
p 0.hash #=> 1
p 0.0.hash #=> 0
p nil.hash #=> 4

p "ruby".hash #=> -241670986
p "ruby".hash #=> -241670986
p :ruby.hash #=> 103538
p :ruby.hash #=> 103538

[SEE_ALSO] Object#eql?,BasicObject#__id__

inspect -> String

オブジェクトを人間が読める形式に変換した文字列を返します。

組み込み関数 Kernel.#p は、このメソッドの結果を使用してオブジェクトを表示します。

puts Class.new.inspect #=> #<Class:0xbafd88>
puts Time.now.inspect #=> 2007-10-15 21:01:37 +0900

[SEE_ALSO] Kernel.#p

instance_of?(klass) -> bool

オブジェクトがクラス klass の直接のインスタンスである時真を返します。

obj.instance_of?(c) が成立する時には、常に obj.kind_of?(c) も成立します。

[PARAM] klass:: Classかそのサブクラスのインスタンスです。

class C < Object
end
class S < C
end

obj = S.new
p obj.instance_of?(S)       # true
p obj.instance_of?(C)       # false

[SEE_ALSO] Object#kind_of?,Object#class

instance_variable_defined?(var) -> bool

インスタンス変数 var が定義されていたら真を返します。

[PARAM] var:: インスタンス変数名を文字列か Symbol で指定します。

class Fred
  def initialize(p1, p2)
    @a, @b = p1, p2
  end
end
fred = Fred.new('cat', 99)
p fred.instance_variable_defined?(:@a)    #=> true
p fred.instance_variable_defined?("@b")   #=> true
p fred.instance_variable_defined?("@c")   #=> false

[SEE_ALSO] Object#instance_variable_get,Object#instance_variable_set,Object#instance_variables

instance_variable_get(var) -> object|nil

オブジェクトのインスタンス変数の値を取得して返します。

インスタンス変数が定義されていなければ nil を返します。

[PARAM] var:: インスタンス変数名を文字列か Symbol で指定します。

class Foo
  def initialize
    @foo = 1
  end
end

obj = Foo.new
p obj.instance_variable_get("@foo")     #=> 1
p obj.instance_variable_get(:@foo)      #=> 1
p obj.instance_variable_get(:@bar)      #=> nil

[SEE_ALSO] Object#instance_variable_set,Object#instance_variables,Object#instance_variable_defined?

instance_variable_set(var, value) -> object

オブジェクトのインスタンス変数 var に値 value を設定します。

インスタンス変数が定義されていなければ新たに定義されます。

[PARAM] var:: インスタンス変数名を文字列か Symbol で指定します。
[PARAM] value:: 設定する値です。
[RETURN]: value を返します。

obj = Object.new
p obj.instance_variable_set("@foo", 1)  #=> 1
p obj.instance_variable_set(:@foo, 2)   #=> 2
p obj.instance_variable_get(:@foo)      #=> 2

[SEE_ALSO] Object#instance_variable_get,Object#instance_variables,Object#instance_variable_defined?

instance_variables -> [Symbol]

オブジェクトのインスタンス変数名をシンボルの配列として返します。

obj = Object.new
obj.instance_eval { @foo, @bar = nil }
p obj.instance_variables

#=> [:@foo, :@bar]

[SEE_ALSO] Object#instance_variable_get,Kernel.#local_variables,Kernel.#global_variables,Module.constants,Module#constants,Module#class_variables

invoke(name, *args) -> object | nil

メソッド名を指定してオブジェクトのメソッドを呼び出します。

OLEオートメーションサーバのメソッドを動的に呼び出したい場合に利用します。

なお、OLEオートメーションの仕様により、メソッド名の大文字、小文字は区別されません。

[PARAM] name:: メソッド名を文字列またはシンボルで指定します。
[PARAM] args:: メソッドの引数を指定します。また、最後の引数にHashを与えることで、名前付き引数を指定できます。この場合、キーに文字列またはシンボルでパラメータ名、値に引数を指定します。
[RETURN]: メソッドの返り値。ただし返り値を持たないメソッドの場合はnil。
[EXCEPTION] WIN32OLERuntimeError:: オートメーションサーバの呼び出しに失敗しました。理由はメッセージのHRESULTを調べてください。 excel = WIN32OLE.new('Excel.Application') workbook = excel.workbooks.invoke(:Open, :FileName => 'c:\\users\\public\\test.xml', :ReadOnly => true, :Password => 'secret') excel.invoke(:Quit)

このリストは、以下の記述と同等です。

excel = WIN32OLE.new('Excel.Application')
workbook = excel.workbooks.Open(:FileName => 'c:\\users\\public\\test.xml',
                                :ReadOnly => true,
                                :Password => 'secret')
excel.Quit

is_a?(mod) -> bool

kind_of?(mod) -> bool

オブジェクトが指定されたクラス mod かそのサブクラスのインスタンスであるとき真を返します。

また、オブジェクトがモジュール mod をインクルードしたクラスかそのサブクラスのインスタンスである場合にも真を返します。上記のいずれでもない場合に false を返します。

[PARAM] mod:: クラスやモジュールなど、Moduleかそのサブクラスのインスタンスです。

module M
end
class C < Object
  include M
end
class S < C
end

obj = S.new
p obj.is_a?(S)       # true
p obj.is_a?(C)       # true
p obj.is_a?(Object)  # true
p obj.is_a?(M)       # true
p obj.is_a?(Hash)    # false

[SEE_ALSO] Object#instance_of?,Module#===,Object#class

marshal_dump -> object

Marshal.#dump を制御するメソッドです。

Marshal.dump(some) において、出力するオブジェクト some がメソッド marshal_dump を持つ場合には、その返り値がダンプされたものが Marshal.dump(some) の返り値となります。

marshal_dump/marshal_load の仕組みは Ruby 1.8.0 から導入されました。これから書くプログラムでは _dump/_load ではなく marshal_dump/marshal_load を使うべきです。

[RETURN]: 任意のオブジェクトで marshal_load の引数に利用できます。

class Foo
  def initialize(arg)
    @foo = arg
  end
  def marshal_dump
    @foo
  end
  def marshal_load(obj)
    p obj
    @foo = obj
  end
end
foo = Foo.new(['foo', 'bar'])
p foo                      #=> #<Foo:0xbaf3b0 @foo=["foo", "bar"]>
dms = Marshal.dump(foo)
p dms                      #=> "\004\bU:\bFoo[\a\"\bfoo\"\bbar"
result = Marshal.load(dms) #=> ["foo", "bar"] # marshal_load の引数
p result                   #=> #<Foo:0xbaf2ac @foo=["foo", "bar"]>

インスタンス変数の情報は普通マーシャルデータに含まれるので、上例のように marshal_dump を定義する必要はありません (ただし marshal_dump を定義するとインスタンス変数の情報はダンプされなくなるので、marshal_dump/marshal_load で扱う必要があります)。 marshal_dump/marshal_load はより高度な制御を行いたい場合や拡張ライブラリで定義したクラスのインスタンスがインスタンス変数以外に情報を保持する場合に利用します。

特に、marshal_dump/marshal_load を定義したオブジェクトは特異メソッドが定義されていてもマーシャルできるようになります (特異メソッドの情報が自動的に dump されるようになるわけではなく、 marshal_dump/marshal_load によりそれを実現する余地があるということです)。

[SEE_ALSO] Object#marshal_load, Marshal

marshal_load(obj) -> object

Marshal.#load を制御するメソッドです。

some のダンプ結果（Marshal.dump(some)）をロードする（Marshal.load(Marshal.dump(some))）には some がメソッド marshal_load を持っていなければなりません。このとき、marshal_dump の返り値が marshal_load の引数に利用されます。 marshal_load 時の self は、生成されたばかり（Class#allocate されたばかり）の状態です。

marshal_dump/marshal_load の仕組みは Ruby 1.8.0 から導入されました。これから書くプログラムでは _dump/_load ではなく marshal_dump/marshal_load を使うべきです。

[PARAM] obj:: marshal_dump の返り値のコピーです。
[RETURN]: 返り値は無視されます。

[SEE_ALSO] Object#marshal_dump, Marshal

method(name) -> Method

オブジェクトのメソッド name をオブジェクト化した Method オブジェクトを返します。

[PARAM] name:: メソッド名をSymbol またはStringで指定します。
[EXCEPTION] NameError:: 定義されていないメソッド名を引数として与えると発生します。

me = -365.method(:abs)
p me #=> #<Method: Fixnum#abs>
p me.call #=> 365

[SEE_ALSO] Module#instance_method,Method,Object#__send__,Kernel.#eval

method_missing(id, *args) -> object | nil

WIN32OLE#invokeメソッドを実行します。

WIN32OLEのインスタンスに対して、このリファレンスに明記されていないメソッドを呼び出した場合、OLEオートメーションサーバのメソッド（プロパティ）呼び出しと解釈します。

[PARAM] id:: メソッド名をシンボルで指定します。
[PARAM] args:: メソッドの引数を指定します。
[RETURN]: メソッドの返り値。ただし返り値を持たないメソッドの場合はnil。
[EXCEPTION] RuntimeError:: idが有効なシンボルではありません。
[EXCEPTION] WIN32OLERuntimeError:: オートメーションサーバの呼び出しに失敗しました。理由はメッセージのHRESULTを調べてください。

WIN32OLEはOLEオートメーションオブジェクトのメソッド呼び出しを method_missingを利用して実行します。このためWIN32OLEを継承するクラスを作成してmethod_missingをオーバーライドする場合、superを呼び出してください。

[SEE_ALSO] WIN32OLE#invoke

methods(include_inherited = true) -> [Symbol]

そのオブジェクトに対して呼び出せるメソッド名の一覧を返します。このメソッドは public メソッドおよび protected メソッドの名前を返します。

ただし特別に、引数が偽の時は Object#singleton_methods(false) と同じになっています。

[PARAM] include_inherited:: 引数が偽の時は Object#singleton_methods(false) と同じになります。

#例1:

class Parent
  private;   def private_parent()   end
  protected; def protected_parent() end
  public;    def public_parent()    end
end

class Foo < Parent
  private;   def private_foo()   end
  protected; def protected_foo() end
  public;    def public_foo()    end
end

obj = Foo.new
class <<obj
    private;   def private_singleton()   end
    protected; def protected_singleton() end
    public;    def public_singleton()    end
end

# あるオブジェクトの応答できるメソッドの一覧を得る。
p obj.methods(false)
p obj.public_methods(false)
p obj.private_methods(false)
p obj.protected_methods(false)

#実行結果

[:protected_singleton, :public_singleton]
[:public_singleton, :public_foo]
[:private_singleton, :private_foo]
[:protected_singleton, :protected_foo]

#例2:

# あるオブジェクトの応答できるメソッドの一覧を得る。
# 自身のクラスの親クラスのインスタンスメソッドも含めるために true を指定して
# いるが、Object のインスタンスメソッドは一覧から排除している。
p obj.methods(true)           - Object.instance_methods(true)
p obj.public_methods(true)    - Object.public_instance_methods(true)
p obj.private_methods(true)   - Object.private_instance_methods(true)
p obj.protected_methods(true) - Object.protected_instance_methods(true)

#実行結果

[:protected_singleton, :public_singleton, :protected_foo, :public_foo, :protected_parent, :public_parent]
[:public_singleton, :public_foo, :public_parent]
[:private_singleton, :private_foo, :private_parent]
[:protected_singleton, :protected_foo, :protected_parent]

[SEE_ALSO] Module#instance_methods,Object#singleton_methods

nil? -> bool

レシーバが nil であれば真を返します。

p false.nil? #=> false
p nil.nil? #=> true

[SEE_ALSO] NilClass

object_id -> Integer

各オブジェクトに対して一意な整数を返します。あるオブジェクトに対してどのような整数が割り当てられるかは不定です。

Rubyでは、(Garbage Collectされていない)アクティブなオブジェクト間で重複しない整数(object_id)が各オブジェクトにひとつずつ割り当てられています。このメソッドはその値を返します。

TrueClass, FalseClass, NilClass, Symbol, Fixnum クラスのインスタンスなど Immutable（変更不可）なオブジェクトの一部は同じ内容ならば必ず同じ object_id になります。

これは、Immutable ならば複数の場所から参照されても`破壊的操作'による問題が発生しないので、同じ内容のインスタンスを複数生成しないという内部実装が理由です。

p "ruby".object_id #=> 22759500
p "ruby".object_id #=> 22759400

p [].object_id #=> 22759360
p [].object_id #=> 22759340

p :ruby.object_id #=> 103538
p :ruby.object_id #=> 103538

p 11.object_id #=> 23
p 11.object_id #=> 23

p true.object_id #=> 2
p true.object_id #=> 2

[SEE_ALSO] Object#equal?,Symbol

ole_activex_initialize -> nil

ActiveXコントロール用の初期化を行います。

ole_activex_initializeメソッドは、スクリプト内でActiveXコントロールを利用できるように、オブジェクトが持つ永続化データを初期化します。

ActiveXコントロール（OCX）は、主にUI用に利用されるOLEオートメーションサーバです。ActiveXコントロールは、IDEを利用した開発時と、プログラムの実行時の2種類の実行モードを持ちます。これは、開発時の設定を永続化するためです。

幾つかのActiveXコントロールは、上記の動作を前提に組まれているため、実行に先だって永続化データの転送をデータの有無と関係なく要求します。この場合、もし永続化データを初期化しないと、実行時モード状態へ遷移せず、後続のメソッド呼び出しがすべてエラーとなります。

[EXCEPTION] WIN32OLERuntimeError:: オブジェクトがActiveXコントロールの永続化インターフェイスを持たない場合に通知します。

obj = WIN32OLE.new("ProgID_or_GUID_of_ActiveX_Control")
obj.ole_activex_initialize
obj.method(...)

なお、生成したOLEオートメーションサーバが永続化データの初期化を必要とするActiveXコントロールか、そうでないかを簡単に区別する方法はありません。そのため、とりあえず普通にメソッドを呼び出し、その結果 WIN32OLERuntimeErrorが通知され、メッセージにHRESULT 0x8000ffffと示されている場合にのみ、オブジェクト生成直後に当メソッドを呼び出してみてください。

また、オブジェクトによっては、当メソッドの呼び出しにより後続のデータを要求してハングアップする場合があります。その場合は、Ctrl-Cなどによって実行を中止してください。

ole_free -> ()

selfが参照するCOMオブジェクトを解放します。

selfが参照するCOMオブジェクトのIUnknown::Releaseを呼び出すことで、COMオブジェクトを開放します。ole_freeを呼び出した後は、このオブジェクトに対する操作は行えません。

excel = WIN32OLE.new('Excel.Application')
excel.ole_free  # オブジェクトの解放
excel.Quit      #=> RuntimeError (failed to get Dispatch Interface)

通常は利用されなくなったWIN32OLEオブジェクトはGCのタイミングで自動的に解放されるため、当メソッドを呼び出す必要はありません。Officeのような外部プロセスサーバ呼び出し時に、スクリプト終了後もサーバが解放されない場合に強制的にサーバを終了するために当メソッドを利用できます。ただし、現実には途中で生成される子オブジェクトからの逆参照などがあるため、 WIN32OLEがIUnknown::Releaseを呼び出してもオブジェクトが解放されるとは限りません。

excel = WIN32OLE.new('Excel.Application')
workbook = excel.Workbooks.Open('workbook.xls')
workbook.Close(:SaveChanges => false)
workbook.ole_free
excel.ole_free
# この時点でExcel.EXEは終了しない

上の例では、excel.Workbooks.Openの行で、excel.Workbooksオブジェクトが生成されています。しかし、後続の処理で該当オブジェクトが解放されていないため、Workbooksオブジェクトによって参照されているexcelオブジェクトは解放されません。それに対して下の例では正しく解放されます。

excel = WIN32OLE.new('Excel.Application')
books = excel.Workbooks
workbook = books.Open('workbook.xls')
books.ole_free
workbook.Close(:SaveChanges => false)
workbook.ole_free
excel.ole_free

ole_func_methods -> [WIN32OLE_METHOD]

オブジェクトのファンクション情報をWIN32OLE_METHODの配列として返します。

ole_func_methodsメソッドは、OLEオートメーションサーバのメソッドのうちファンクション（何らかの機能的な操作）に属するものをWIN32OLE_METHODの配列として返します。

[RETURN]: WIN32OLE_METHODの配列。
[EXCEPTION] WIN32OLERuntimeError:: オートメーションサーバの呼び出しに失敗しました。型情報ライブラリ(TypeLib)が提供されていない場合などに発生します。

excel = WIN32OLE.new('Excel.Application')
excel.visible = true
excel.ole_func_methods.each do |fun|
  if fun.name.upcase == 'QUIT'
    excel._invoke(fun.dispid, [], [])
    break
  end
end

[SEE_ALSO] WIN32OLE#ole_methods, WIN32OLE#ole_get_methods, WIN32OLE#ole_put_methods

ole_get_methods -> [WIN32OLE_METHOD]

オブジェクトの参照可能プロパティ情報をWIN32OLE_METHODの配列として返します。

ole_get_methodsメソッドは、OLEオートメーションサーバのメソッドのうち読み取り可能なプロパティをWIN32OLE_METHODの配列として返します。

[RETURN]: WIN32OLE_METHODの配列。
[EXCEPTION] WIN32OLERuntimeError:: オートメーションサーバの呼び出しに失敗しました。型情報ライブラリ(TypeLib)が提供されていない場合などに発生します。

excel = WIN32OLE.new('Excel.Application')
excel.ole_get_methods.each do |prop|
  begin
    puts "#{prop.name}=#{excel._getproperty(prop.dispid, [], [])}"
  rescue WIN32OLERuntimeError
    puts "can't read #{prop.name} property"
  end
end

[SEE_ALSO] WIN32OLE#ole_methods, WIN32OLE#ole_func_methods, WIN32OLE#ole_put_methods

ole_method(method) -> WIN32OLE_METHOD

ole_method_help(method) -> WIN32OLE_METHOD

メソッド名を指定して対応するWIN32OLE_METHODオブジェクトを取得します。

OLEオートメーションの仕様により、メソッド名の大文字、小文字は区別されません。

[PARAM] method:: メソッド情報を取り出す対象のメソッド名を文字列で指定します。
[RETURN]: WIN32OLE_METHODオブジェクト。
[EXCEPTION] WIN32OLERuntimeError:: 指定したメソッド名が未定義あるいは型情報ライブラリ(TypeLib)が提供されていない場合などに発生します。

excel = WIN32OLE.new('Excel.Application')
method = excel.ole_method_help('Quit')

ole_methods -> [WIN32OLE_METHOD]

オブジェクトのメソッド情報をWIN32OLE_METHODの配列として返します。

ole_methodsメソッドは、OLEオートメーションサーバが提供するすべてのメソッドをWIN32OLE_METHODの配列として返します。

[RETURN]: WIN32OLE_METHODの配列。
[EXCEPTION] WIN32OLERuntimeError:: オートメーションサーバの呼び出しに失敗しました。型情報ライブラリ(TypeLib)が提供されていない場合などに発生します。

excel = WIN32OLE.new('Excel.Application')
methods = excel.ole_methods

[SEE_ALSO] WIN32OLE#ole_func_methods, WIN32OLE#ole_put_methods

ole_obj_help -> WIN32OLE_TYPE | nil

ole_type -> WIN32OLE_TYPE | nil

WIN32OLE_TYPEオブジェクトを返します。

WIN32OLE_TYPEオブジェクトは、WIN32OLEオブジェクトの文書情報と型情報を保持するオブジェクトです。

[RETURN]: オブジェクトに関連するWIN32OLE_TYPEオブジェクトを返します。オブジェクトがドキュメント情報を持たない場合はnilを返します。

excel = WIN32OLE.new('Excel.Application')
tobj = excel.ole_obj_help

[SEE_ALSO] WIN32OLE_TYPE

ole_put_methods -> [WIN32OLE_METHOD]

オブジェクトの設定可能プロパティ情報をWIN32OLE_METHODの配列として返します。

ole_put_methodsメソッドは、OLEオートメーションサーバのメソッドのうちプロパティ設定メソッドに属するものをWIN32OLE_METHODの配列として返します。

[RETURN]: WIN32OLE_METHODの配列。
[EXCEPTION] WIN32OLERuntimeError:: オートメーションサーバの呼び出しに失敗しました。型情報ライブラリ(TypeLib)が提供されていない場合などに発生します。

excel = WIN32OLE.new('Excel.Application')
properties = excel.ole_put_methods

[SEE_ALSO] WIN32OLE#ole_methods, WIN32OLE#ole_func_methods, WIN32OLE#ole_get_methods

ole_query_interface(iid) -> WIN32OLE

IID（インターフェイスID）を指定してオブジェクトの別のインターフェイスを持つオブジェクトを取得します。

オブジェクトが複数のオートメーション用インターフェイスを持つ場合に、当メソッドを利用して既定のインターフェイスとは異なるインターフェイスを取得します。

[PARAM] iid:: 取得するインターフェイスのIIDを文字列で指定します。
[RETURN]: iidパラメータで指定したインターフェイスを持つWIN32OLEオブジェクト
[EXCEPTION] WIN32OLERuntimeError:: 指定したIIDをオブジェクトが持たない場合に通知されます。

ie = WIN32OLE.new('InternetExplorer.Application')
ie_web_app = ie.ole_query_interface('{0002DF05-0000-0000-C000-000000000046}')

上例のie_web_appは、ieと同じインスタンスとなります。

COMの仕様では1つのインターフェイスについて同じIID問い合わせに対しては常に同一のインターフェイスを返すことが決められています。

このため、正しく実装されたOLEオートメーションサーバでは本メソッドが意味を持つことはありません。というのは、2つ以上の異なるWIN32OLEで操作可能なインターフェイスを持つということは、IID_IDispatch（OLEオートメーションのインターフェイスID）を指定した問い合わせに対して異なるインターフェイスを返すということになるからです。これは、結果的に呼び出し側プログラムがいつでも間違えたインターフェイスを呼び出す可能性を持つということを意味します。当然、それはサーバ実装のバグです。

問題は、C++のvtblアクセスや.NET FrameworkのCOM Interopのために静的型情報が必要となることです。このため、一度あるインターフェイスを返すことに決めた場合、実際に返すインターフェイスが元のインターフェイスを継承していたとしても、ドキュメント上は異なるインターフェイスとして定義しなければ追加のメソッドが呼び出せません。

たとえば、当メソッドの存在理由である http://www.ruby-forum.com/topic/109954（なお、元のパッチと異なりGUIDの統一フォーマットを利用するように改造されているため、IIDの前後に {}が必要です）には、Solutionオブジェクトに対してSolution2オブジェクトの取得を依頼するために、必要ということになっています。実際、Solutionプロパティが返すのは、この場合はSolutionインターフェイスを継承した Solution2インターフェイスです。しかし、Solutionプロパティの型情報は Solutionインターフェイスを返すことになっているため、静的に型を解決している場合は、追加のメソッドの呼び出しを記述できません。

しかし、WIN32OLEが利用するIDispatchインターフェイスは、メソッド名による動的なメソッド検索が行われます。このため、Solutionオブジェクト（しかしその実態はSolution2オブジェクト）に対してSolution2で追加されたメソッド（たとえばGetProjectTemplate）を指定したとしても正しく呼び出せます。つまり、http://www.ruby-forum.com/topic/109954で例示されているようなole_query_interfaceメソッドの呼び出しは不要です。

もし、当メソッドの呼び出しが本当に必要なのであれば、まず、該当するOLEオートメーションサーバの修正を依頼してください。その実装は正しくありません。

正しく実装されたオブジェクトに対して当メソッドを適用すると、結果として、同一オブジェクトの参照カウント値を無駄に増加させることになります。

なお、サポートしているインターフェイスのバージョンを調べたい場合に、以下のような方法で、インターフェイスのバージョンを調べることができます。

def check_solution_version(obj)
  [['{CDA7305C-78B6-4D9D-90AD-93EBE71F9341}', 4],
   ['{DF23915F-FDA3-4DD5-9CAA-2E1372C2BB16}', 3],
   ['{FA238614-FBB1-4314-A7F7-49AE8BB6C6BA}', 2]].each do |iid, ver|
    begin
      intf = obj.ole_query_interface(iid)
      intf.ole_free
      return ver
    rescue WIN32OLERuntimeError
    end
  end
  1
end

しかし、ole_query_interfaceのような特異なメソッドを利用するよりも、 WIN32OLE.new('VisualStudio.DTE.8.0') のように生成時にバージョン番号（この例では8.0）を指定するほうが良いスタイルです。

また、単に特定のメソッドをサポートしているかどうかを知りたいだけであれば、WIN32OLE#ole_respond_to?を利用したダックタイピングをしてください。

ole_respond_to?(name) -> bool

指定したメソッドをオブジェクトがサポートしているか調べます。

OLEオートメーションサーバが引数で指定した名前のメソッド（プロパティ）をサポートしているかどうかを調べます。

なお、OLEオートメーションの仕様により、メソッド名の大文字、小文字は区別されません。

[PARAM] name:: 調べるメソッド名を文字列またはシンボルで指定します。
[RETURN]: nameで指定したメソッドをオブジェクトが提供していれば真を返します。

excel = WIN32OLE.new('Excel.Application')
excel.ole_respond_to?(:quit) #=> true
excel.ole_respond_to?(:exit) #=> false

ole_typelib -> WIN32OLE_TYPELIB

オブジェクトに対応する型情報ライブラリ（TypeLib）を WIN32OLE_TYPELIBとして返します。

OLEオートメーションではクラス、インターフェイス、メソッド、引数などの型情報と文書情報を型情報ライブラリとして利用します。型情報ライブラリは独立したファイル（拡張子tlb）の場合もあれば、オブジェクトのバイナリへリソースとして埋め込まれている場合があります。

OLEオートメーションでは型情報ライブラリの提供方法を問わずに統一したインターフェイスでアプリケーションが参照できるように、オブジェクトの形式（ITypeInfoインターフェイス）で提供します。WIN32OLEは、このオブジェクトをラップしてWIN32OLE_TYPELIBとして提供します。

[RETURN]: オブジェクトに対応するWIN32OLE_TYPELIBオブジェクト。
[EXCEPTION] WIN32OLERuntimeError:: オートメーションサーバの呼び出しに失敗しました。型情報ライブラリ(TypeLib)が提供されていない場合などに発生します。

excel = WIN32OLE.new('Excel.Application')
tlib = excel.ole_typelib
puts tlib.name  # => 'Microsoft Excel 9.0 Object Library'

private_methods(include_inherited = true) -> [Symbol]

そのオブジェクトが理解できる private メソッド名の一覧を返します。

[PARAM] include_inherited:: 偽となる値を指定すると自身のクラスのスーパークラスで定義されたメソッドを除きます。

[SEE_ALSO] Module#private_instance_methods,Object#methods,Object#singleton_methods

protected_methods(include_inherited = true) -> [Symbol]

そのオブジェクトが理解できる protected メソッド名の一覧を返します。

[PARAM] include_inherited:: 偽となる値を指定すると自身のクラスのスーパークラスで定義されたメソッドを除きます。

[SEE_ALSO] Module#protected_instance_methods,Object#methods,Object#singleton_methods

public_methods(include_inherited = true) -> [Symbol]

そのオブジェクトが理解できる public メソッド名の一覧を返します。

[PARAM] include_inherited:: 偽となる値を指定すると自身のクラスのスーパークラスで定義されたメソッドを除きます。

[SEE_ALSO] Module#public_instance_methods,Object#methods,Object#singleton_methods

public_send(name, *args) -> object

オブジェクトの public メソッド name を args を引数にして呼び出し、メソッドの実行結果を返します。

1.public_send(:+, 2)  # => 3

[PARAM] name:: 文字列かSymbol で指定するメソッド名です。
[PARAM] args:: 呼び出すメソッドに渡す引数です。
[EXCEPTION] ArgumentError:: name を指定しなかった場合に発生します。
[EXCEPTION] NoMethodError:: protected メソッドや private メソッドに対して実行した場合に発生します。

1.public_send(:puts, "hello")  # => NoMethodError

[SEE_ALSO] Object#send

respond_to?(name, include_private = false) -> bool

オブジェクトがメソッド name を持つとき真を返します。

オブジェクトがメソッド name を持つというのは、オブジェクトがメソッド name に応答することができることをいいます。

[PARAM] name:: Symbol または文字列で指定するメソッド名です。
[PARAM] include_private:: private メソッドを確認の対象に含めるかを true か false で指定します。省略した場合は false(含めない) を指定した事になります。

class F
  def hello
    "Bonjour"
  end
end

class D
private
  def hello
    "Guten Tag"
  end
end
list = [F.new,D.new]

list.each{|it| puts it.hello if it.respond_to?(:hello)}
#=> Bonjour

list.each{|it| it.instance_eval("puts hello if it.respond_to?(:hello, true)")}
#=> Bonjour
#   Guten Tag

[SEE_ALSO] Module#method_defined?

respond_to_missing?(symbol, include_private) -> bool

自身が symbol で表されるメソッドに対し BasicObject#method_missing で反応するつもりならば真を返します。

Object#respond_to? はメソッドが定義されていない場合、デフォルトでこのメソッドを呼びだし問合せます。

BasicObject#method_missing を override した場合にこのメソッドも override されるべきです。

false を返します。

[PARAM] symbol:: メソッド名シンボル
[PARAM] include_private:: private method も含めたい場合に true が渡されます

[SEE_ALSO] Object#respond_to?, BasicObject#method_missing

setproperty(name, val) -> ()

setproperty(name, args..., val) -> ()

オブジェクトのプロパティを設定します。

プロパティ名を指定してOLEオートメーションオブジェクトのプロパティ（Rubyの属性に相当）を設定します。

なお、OLEオートメーションの仕様により、プロパティ名の大文字、小文字は区別されません。

[PARAM] name:: プロパティ名を文字列またはシンボルで指定します。
[PARAM] val:: プロパティに設定する値を指定します。
[PARAM] args:: 集合的なプロパティに対する設定項目を特定するための引数を指定します。
[EXCEPTION] WIN32OLERuntimeError:: オートメーションサーバの呼び出しに失敗しました。理由はメッセージのHRESULTを調べてください。

OLEオートメーションのプロパティはRubyの属性と異なり、パラメータを取ることができます。

たとえばExcelのWorksheetオブジェクトのCellsプロパティは桁位置と行番号の 2つのパラメータを取ります。

これはVBでは次のように記述できます。

sheet.Cells(1, 1) = sheet.Cells(1, 2) ' セルB1の内容をセルA1へ

Rubyでは上記のコードの右辺をVBと同じく「sheet.Cells(1, 2)」のように記述できますが、左辺の記述はできません。

そのため、次の例のようにsetpropertyメソッドを利用して、パラメータ付きプロパティを設定します。

excel = WIN32OLE.new('Excel.Application')
excel.visible = true
sheet = excel.Workbooks.Add.Worksheets[1]
sheet.setproperty(:Cells, 1, 2, 32)
sheet.setproperty(:Cells, 1, 1, sheet.Cells(1, 2))

singleton_class -> Class

レシーバの特異クラスを返します。まだ特異クラスがなければ、新しく作成します。

レシーバが nil か true か false なら、それぞれ NilClass, TrueClass, FalseClass を返します。

[EXCEPTION] TypeError:: レシーバが Fixnum か Symbol の場合に発生します。

Object.new.singleton_class  #=> #<Class:#<Object:0xb7ce1e24>>
String.singleton_class      #=> #<Class:String>
nil.singleton_class         #=> NilClass

[SEE_ALSO] Object#class

singleton_methods(inherited_too = true) -> [Symbol]

そのオブジェクトに対して定義されている特異メソッド名 (public あるいは protected メソッド) の一覧を返します。

クラスメソッド(Classのインスタンスの特異メソッド)に関しては引数が真のとき、スーパークラスのクラスメソッドも対象になります。

singleton_methods(false) は、Object#methods(false) と同じです。

[PARAM] inherited_too:: 引数が真のとき、スーパークラスのクラスメソッドも対象になります。これが意味を持つのは self がクラスオブジェクトであるときだけです。

#例1:

Parent = Class.new

class <<Parent
  private;   def private_class_parent() end
  protected; def protected_class_parent() end
  public;    def public_class_parent() end
end

Foo = Class.new(Parent)

class <<Foo
  private;   def private_class_foo() end
  protected; def protected_class_foo() end
  public;    def public_class_foo() end
end

module Bar
  private;   def private_bar()   end
  protected; def protected_bar() end
  public;    def public_bar()    end
end

obj = Foo.new
class <<obj
  include Bar
  private;   def private_self()   end
  protected; def protected_self() end
  public;    def public_self()    end
end

# あるオブジェクトの特異メソッドの一覧を得る。
p obj.singleton_methods(false)
p obj.methods(false)
p Foo.singleton_methods(false)

#実行結果

[:protected_self, :public_self]
[:protected_self, :public_self]
[:protected_class_foo, :public_class_foo]


#例2:

# あるオブジェクトの特異メソッドの一覧を得る。
# 親クラスのクラスメソッドも含まれるよう true を指定したが、
# Object のクラスメソッドは一覧から排除している。

p obj.singleton_methods(true)
p Foo.singleton_methods(true) - Object.singleton_methods(true)

#実行結果

[:protected_self, :public_self, :protected_bar, :public_bar]
[:protected_class_foo, :public_class_foo, :protected_class_parent, :public_class_parent]

[SEE_ALSO] Object#methods,Object#extend

taint -> self

オブジェクトの「汚染マーク」をセットします。

環境変数（ENVで得られる文字列）など一部のオブジェクトは最初から汚染されています。オブジェクトの汚染に関してはセキュリティモデルを参照してください。

$SAFE = 1

some = "puts '@&%&(#!'"
p some.tainted? #=> false
eval(some) #=> @&%&(#!

some.taint
p some.tainted? #=> true
eval(some) # Insecure operation - eval (SecurityError)

some.untaint
p some.tainted? #=> false
eval(some) #=> @&%&(#!

p ENV['OS'].tainted? #=> true

[SEE_ALSO] Object#tainted?,Object#untaint,Object#freeze

tainted? -> bool

オブジェクトの「汚染マーク」がセットされている時真を返します。

オブジェクトの汚染に関してはセキュリティモデルを参照してください。

p String.new.tainted? #=> false
p ENV['OS'].tainted? #=> true

[SEE_ALSO] Object#taint,Object#untaint

tap {|x| ... } -> self

self を引数としてブロックを評価し、self を返します。

メソッドチェインの途中で直ちに操作結果を表示するためにメソッドチェインに "入り込む" ことが、このメソッドの主目的です。

(1..10)                    .tap {|x| puts "original: #{x.inspect}"}.
   to_a                    .tap {|x| puts "array: #{x.inspect}"}.
   select {|x| x % 2 == 0} .tap {|x| puts "evens: #{x.inspect}"}.
   map { |x| x * x }       .tap {|x| puts "squares: #{x.inspect}"}

to_a -> Array

オブジェクトを配列に変換した結果を返します。デフォルトでは定義されていません。

説明のためここに記載してありますが、このメソッドは実際には Object クラスには定義されていません。必要に応じてサブクラスで定義すべきものです。

p( {'a'=>1}.to_a )  # [["a", 1]]
p ['array'].to_a    # ["array"]
p nil.to_a          # []

[SEE_ALSO] Object#to_ary,Kernel.#Array

to_ary -> Array

オブジェクトの Array への暗黙の変換が必要なときに内部で呼ばれます。デフォルトでは定義されていません。

このメソッドを定義する条件は、

配列が使われるすべての場面で代置可能であるような、
配列そのものとみなせるようなもの

という厳しいものになっています。

class Foo
 def to_ary
   [3,4]
 end
end

it = Foo.new
p([1,2] + it) #=> [1, 2, 3, 4]

[SEE_ALSO] Object#to_a,Kernel.#Array

to_hash -> Hash

オブジェクトの Hash への暗黙の変換が必要なときに内部で呼ばれます。デフォルトでは定義されていません。

このメソッドを定義する条件は、

ハッシュが使われるすべての場面で代置可能であるような、
ハッシュそのものとみなせるようなもの

という厳しいものになっています。

class Foo
 def to_hash
   {'as' => 24}
 end
end

it = Foo.new
p({:as => 12}.merge(it)) #=> {"as"=>24, :as=>12}

to_int -> Integer

オブジェクトの Integer への暗黙の変換が必要なときに内部で呼ばれます。デフォルトでは定義されていません。

このメソッドを定義する条件は、

整数が使われるすべての場面で代置可能であるような、
整数そのものとみなせるようなもの

という厳しいものになっています。

class Foo
 def to_int
   666
 end
end

it = Foo.new
p(9**9 & it) #=> 8

[SEE_ALSO] Kernel.#Integer

to_io -> IO

オブジェクトの IO への暗黙の変換が必要なときに内部で呼ばれます。デフォルトでは定義されていません。

このメソッドを定義する条件は、

IOオブジェクトが使われるすべての場面で代置可能であるような、
IOオブジェクトそのものとみなせるようなもの

という厳しいものになっています。

to_proc -> Proc

オブジェクトの Proc への暗黙の変換が必要なときに内部で呼ばれます。デフォルトでは定義されていません。

def doing
  yield
end

class Foo
 def to_proc
   Proc.new{p 'ok'}
 end
end

it = Foo.new
doing(&it) #=> "ok"

to_regexp -> Regexp

オブジェクトの Regexp への暗黙の変換が必要なときに内部で呼ばれます。デフォルトでは定義されていません。

このメソッドを定義する条件は、

正規表現が使われるすべての場面で代置可能であるような、
正規表現そのものとみなせるようなもの

という厳しいものになっています。

class Foo
 def to_regexp
   /[\d]+/
 end
end

it = Foo.new
p Regexp.union(/^at/, it) #=> /(?-mix:^at)|(?-mix:[\d]+)/

to_s -> String

オブジェクトの文字列表現を返します。

Kernel.#print や Kernel.#sprintf は文字列以外のオブジェクトが引数に渡された場合このメソッドを使って文字列に変換します。

class Foo
  def initialize num
    @num = num
  end
end
it = Foo.new(40)

puts it #=> #<Foo:0x2b69110>

class Foo
 def to_s
   "Class:Foo Number:#{@num}"
 end
end

puts it #=> Class:Foo Number:40

[SEE_ALSO] Object#to_str,Kernel.#String

to_str -> String

オブジェクトの String への暗黙の変換が必要なときに内部で呼ばれます。デフォルトでは定義されていません。

このメソッドを定義する条件は、

文字列が使われるすべての場面で代置可能であるような、
文字列そのものとみなせるようなもの

という厳しいものになっています。

class Foo
 def to_str
   'Edition'
 end
end

it = Foo.new
p('Second' + it) #=> "SecondEdition"

[SEE_ALSO] Object#to_s,Kernel.#String

trust -> self

[TODO]

オブジェクトの「untrustマーク」を取り除きます。

[SEE_ALSO] Object#untrusted?,Object#untrust

untaint -> self

オブジェクトの「汚染マーク」を取り除きます。

汚染マークを取り除くことによる危険性はプログラマが責任を負う必要があります。

オブジェクトの汚染に関してはセキュリティモデルを参照してください。

[EXCEPTION] SecurityError:: セキュリティレベルが3以上の時にこのメソッドを使用すると発生します。

[SEE_ALSO] Object#taint,Object#tainted?

untrust -> self

[TODO]

オブジェクトの「untrustマーク」をセットします。

[SEE_ALSO] Object#trust,Object#untrusted?

untrusted? -> bool

[TODO]

オブジェクトの「untrustマーク」がセットされている時真を返します。

[SEE_ALSO] Object#trust,Object#untrust

privateメソッド

initialize(*args, &block) -> object

ユーザ定義クラスのオブジェクト初期化メソッド。

このメソッドは Class#new から新しく生成されたオブジェクトの初期化のために呼び出されます。他の言語のコンストラクタに相当します。デフォルトの動作ではなにもしません。

initialize には Class#new に与えられた引数がそのまま渡されます。

サブクラスではこのメソッドを必要に応じて再定義されることが期待されています。

initialize という名前のメソッドは自動的に private に設定されます。

[PARAM] args:: 初期化時の引数です。
[PARAM] block:: 初期化時のブロック引数です。必須ではありません。

class Foo
  def initialize name
    puts "initialize Foo"
    @name = name
  end
end

class Bar < Foo
  def initialize name, pass
    puts "initialize Bar"
    super name
    @pass = pass
  end
end

it = Bar.new('myname','0500')
p it
#=> initialize Bar
#   initialize Foo
#   #<Bar:0x2b68f08 @name="myname", @pass="0500">

[SEE_ALSO] Class#new

initialize_copy(obj) -> object

(拡張ライブラリによる) ユーザ定義クラスのオブジェクトコピーの初期化メソッド。

このメソッドは self を obj の内容で置き換えます。ただし、self のインスタンス変数や特異メソッドは変化しません。 Object#clone, Object#dupの内部で使われています。

initialize_copy は、Ruby インタプリタが知り得ない情報をコピーするために使用(定義)されます。例えば C 言語でクラスを実装する場合、情報をインスタンス変数に保持させない場合がありますが、そういった内部情報を initialize_copy でコピーするよう定義しておくことで、dup や clone を再定義する必要がなくなります。

デフォルトの Object#initialize_copy は、 freeze チェックおよび型のチェックを行い self を返すだけのメソッドです。

initialize_copy という名前のメソッドは自動的に private に設定されます。

[EXCEPTION] TypeError:: レシーバが freeze されているか、obj のクラスがレシーバのクラスと異なる場合に発生します。

[SEE_ALSO] Object#clone,Object#dup

以下に例として、dup や clone がこのメソッドをどのように利用しているかを示します。

obj.dup は、新たに生成したオブジェクトに対して initialize_copy を呼び

obj2 = obj.class.allocate
obj2.initialize_copy(obj)

obj2 に対してさらに obj の汚染状態、インスタンス変数、ファイナライザをコピーすることで複製を作ります。 obj.clone は、さらに特異メソッドのコピーも行います。

obj = Object.new
class <<obj
  attr_accessor :foo
  def bar
    :bar
  end
end

def check(obj)
  puts "instance variables: #{obj.inspect}"
  puts "tainted?: #{obj.tainted?}"
  print "singleton methods: "
  begin
    p obj.bar
  rescue NameError
    p $!
  end
end

obj.foo = 1
obj.taint

check Object.new.send(:initialize_copy, obj)
        #=> instance variables: #<Object:0x4019c9d4>
        #   tainted?: false
        #   singleton methods: #<NoMethodError: ...>
check obj.dup
        #=> instance variables: #<Object:0x4019c9c0 @foo=1>
        #   tainted?: true
        #   singleton methods: #<NoMethodError: ...>
check obj.clone
        #=> instance variables: #<Object:0x4019c880 @foo=1>
        #   tainted?: true
        #   singleton methods: :bar

remove_instance_variable(name) -> object

オブジェクトからインスタンス変数 name を取り除き、そのインスタンス変数に設定されていた値を返します。

[PARAM] name:: 削除するインスタンス変数の名前をシンボルか文字列で指定します。
[EXCEPTION] NameError:: オブジェクトがインスタンス変数 name を持たない場合に発生します。

class Foo
  def foo
    @foo = 1
    p remove_instance_variable(:@foo) #=> 1
    p remove_instance_variable(:@foo) # instance variable @foo not defined (NameError)
  end
end
Foo.new.foo

[SEE_ALSO] Module#remove_class_variable,Module#remove_const

定数

ARGV -> [object]

直前のメソッド呼び出しの引数を格納した配列です。

OLEオートメーションでは呼び出し先が引数に対して値を設定できます。しかし、 Rubyのメソッド引数は値のみを取るため、そのままでは呼び出し先が設定した値を参照できません。このような場合、ARGVを参照することで呼び出し先の設定値を参照できます。

以下のリストは、VBで開発したオブジェクトのメソッド呼び出しを例としています。このメソッド（Accm）は、第1引数で指定した演算を第2引数と第3引数に適用し、結果を第2引数に設定します。

' VB (OLE Automation server)
Public Sub Accm(ByVal Operator, ByRef Accumulator, ByVal Operand)
    If Operator = "*" Then
        Accmulator = Accmulator * Operand
    Else If Operator = "+" Then
        Accmulator = Accmulator + Operand
    End If
End Sub

# Ruby
x = 10
obj.Accm '*', x, 11
p x               # => 10 …… 呼び出しによって影響を受けない
p WIN32OLE::ARGV  # => ['*', 110, 11] …… 結果はARGVの対応する引数に反映される
obj.Accm '+', 10, 11
p WIN32OLE::ARGV  # => ['+', 21, 11]

直前のメソッド呼び出しが例外となった場合、ARGVの設定内容は呼び出し前の状態が保たれます。つまり、WIN32OLE自身がARGVの内容を消去するのは、メソッド呼び出しに成功した場合のみです。このため最後のメソッド呼び出しが引数にオブジェクトを返すタイプのメソッドだった場合、GCにオブジェクトを回収させるために、呼び出し側でARGVを消去してください。

' VB (OLE Automation server)
Public Sub GetInterface(ByRef obj)
    Set Obj = New OleObject
End Sub

# Ruby
obj.GetInterface nil   # 引数の数を合わせるためダミー引数を指定
WIN32OLE::ARGV.clear   # 通常は、後続のメソッド呼び出しによって消去される

CP_ACP -> Fixnum

Windows既定のANSIコードページ（0）を示します。

CP_MACCP -> Fixnum

Macintoshコードページ（2）を示します。

CP_OEMCP -> Fixnum

OEMコードページ（1）を示します。

CP_SYMBOL -> Fixnum

文字コードの変換にシンボルを利用することを示します（42）。

CP_THREAD_ACP -> Fixnum

現在実行中のスレッドの既定のコードページ（3）を示します。

Windowsのコードページはスレッド毎に異なる値を設定できます。

CP_UTF7 -> Fixnum

文字コードの変換にUTF-7を利用することを示します（65000）。

CP_UTF8 -> Fixnum

文字コードの変換にUTF-8を利用することを示します（65001）。

LOCALE_SYSTEM_DEFAULT -> Fixnum

システム既定のロケールを示すLCID(0x0800)です。WIN32OLEがオートメーションを利用する場合の既定値です。

LOCALE_USER_DEFAULT -> Fixnum

ユーザ既定のロケールを示すLCID(0x0400)です。

VERSION -> String

Major.Minor.Patch形式のWIN32OLEのバージョン番号を示す文字列です。

class WIN32OLE

Ruby 1.9.3 リファレンスマニュアル
- はじめに
- コマンド
- Rubyの起動
- 環境変数
- Ruby言語仕様
- 組み込みライブラリ
- 標準添付ライブラリ
  - CUI
    - curses
    - expect
    - io/console
    - pty
    - readline
    - shell
  - 文字コード
    - iconv
    - kconv
    - nkf
  - コマンドライン
    - getoptlong
    - optparse
  - データベース
    - dbm
    - gdbm
    - pstore
    - sdbm
  - 日付・時間
    - date
    - time
  - デザインパターン
  - 開発
    - benchmark
    - coverage
    - debug
    - irb
    - minitest/mock
    - minitest/spec
    - minitest/unit
    - mkmf
    - pp
    - profile
    - profiler
    - rake
    - rbconfig
    - test/unit
    - tracer
  - ファイル
    - fileutils
    - find
    - pathname
    - tempfile
    - tmpdir
    - un
  - ファイルフォーマット
    - csv
    - json
    - psych
    - rdoc
    - rexml
    - rss
    - syck
    - yaml
    - zlib
  - GC
    - weakref
  - GUI
    - tk
  - 入出力
    - fcntl
    - io/nonblock
    - io/wait
    - open3
    - scanf
  - 数学
    - bigdecimal
    - cmath
    - complex
    - mathn
    - matrix
    - prime
    - rational
    - set
    - tsort
  - ネットワーク
    - cgi
    - drb
    - gserver
    - ipaddr
    - net/ftp
    - net/http
    - net/https
    - net/imap
    - net/pop
    - net/protocol
    - net/smtp
    - net/telnet
    - open-uri
    - openssl
    - resolv
    - resolv-replace
    - socket
    - uri
    - webrick
    - xmlrpc
  - テキスト
    - digest
    - erb
    - ripper
    - shellwords
    - stringio
    - strscan
  - スレッド
    - monitor
    - mutex_m
    - sync
    - thread
    - thwait
    - timeout
  - Unix
    - etc
    - syslog
  - Windows
  - その他
    - abbrev
    - base64
    - continuation
    - dl
    - e2mmap
    - English
    - fiber
    - logger
    - objspace
    - ostruct
    - prettyprint
    - racc/parser
    - rinda/rinda
    - rinda/tuplespace
    - rubygems
    - securerandom
    - ubygems
- pack テンプレート文字列
- sprintf フォーマット
- Ruby用語集
- Rubyで使われる記号の意味
- 疑似BNFによるRubyの文法
- バージョン情報 / このリファレンスについて