[ruby-list:24413] Re: Ruby Documentation Project(仮)

師星です。

> さぁ、遠慮なくどんどんいこう!!

では、お言葉に甘えて。元が自分用のメモなので、不適切なところが
あればご指摘下さい。一応見直したつもりではありますが、まだ流儀が
よくわかっていないと思いますので。

 - delegate.rd
 - eregex.rd
 - final.rd
 - observer.rd
 - tracer.rd
 - weakref.rd
です。


=begin
= delegate.rb
== 目的・概要
メソッドの委譲(delegation)を行う。

Delagatorクラスは指定したオブジェクトにメソッドの実行を委譲する。
Delegatorクラスを利用する場合はこれを継承して(({__getobj__}))メソッドを
再定義して委譲先のオブジェクトを指定する。

SimpleDelegatorはDelegatorの利用例の一つであり、コンストラクタに
渡されたオブジェクトにメソッドの実行を委譲する。

関数DelegateClass(((|supperclass|)))は((|superclass|))クラスの
オブジェクトをひとつとり、そのオブジェクトにインスタンスメソッドを委譲す
るクラスを定義して返す。
== サンプルコード
  foo = Object::new
  def foo.test
    25
  end
  foo_d = SimpleDelegator::new(foo)
  foo2.test # => 25
  
  class ExtArray<DelegateClass(Array)
    def initialize()
      super([])
    end
  end
  a = ExtArray::new
  p a.type  # => ExtArray
  a.push 25
  p a       # => [25]
== Delegator
与えられたオブジェクトの持つメソッドに関して委譲用のメソッド定義を
提供するクラス。

コンストラクタで指定されたオブジェクトのもつインスタンスメソッドのうち、
自分の持たないメソッドについて、
(({__getobj__}))が返すオブジェクトに実行を委譲するようメソッドを定義する。
=== インスタンスメソッド
--- initialize(obj)
        ((|obj|))のもつインスタンスメソッドのうち、
        自分の持たないメソッドについて、
        (({__getobj__}))が返すオブジェクトに実行を委譲する
        ようインスタンスメソッドを定義する。
--- __getobj__
        委譲先のオブジェクトを返す。
        デフォルトではNotImplementErrorを発生するので、サブクラスで
        再定義する必要がある。
== class SimpleDelegator
Delegatorクラスをそのまま利用した、
指定したオブジェクトにメソッドを委譲するクラス。
:上位クラス
         Delegator
=== クラスメソッド
--- new(obj)
        ((|obj|))がもつメソッドについて、実行を((|obj|))に委譲する
	オブジェクトを生成する。
=== インスタンスメソッド
--- __getobj__
        委譲先のオブジェクトを返す。
--- __setobj__(obj)
        委譲先のオブジェクトを((|obj|))に変更する。

        委譲するメソッドの定義は生成時にのみ行われるため、
        以前の委譲先オブジェクトと((|obj|))の間でインスタンスメソッドに
        違いがあっても、
        委譲するインスタンスメソッドの再設定は行われないことに注意。
== 関数
--- DelegateClass(superclass)
        クラス((|superclass|))のインスタンスへメソッドを委譲するクラスを
        定義し、そのクラスを返す。
== SEE ALSO
--- Object#method_missing(method_symbol, ...)
        メソッドがオブジェクトに定義されていなかったときにこのメソッドが
        呼ばれる。これを使って自分の知らないメソッドをほかのオブジェクト
        に委譲することができる。

        例:
          def hoge.method_missing(message, *arg)
              @to_obj.send(message, *arg)
          end
=end

=begin
= eregex.rb
== 目的・概要
2つの正規表現によるAND/ORを提供する。

Regexpクラスに&と|のメソッドを定義し、それぞれ
2つの正規表現の両方にマッチすれば真となるもの(RegAnd)と
いずれかにマッチすれば真となるもの(RegOr)を返す。
RegAnd、RegOrは=~のみサポートしている。
== サンプルコード
 require 'eregex'
 p "abc" =~ /b/|/c/
 p "abc" =~ /b/&/c/
== class Regexp
組み込みクラスRegexpを拡張して次のメソッドを定義している。
=== インスタンスメソッド
--- &(other)
      (({RegAnd(self,((|other|)))}))を返す
--- |(other)
      (({RegOr(self,((|other|)))}))を返す
== class RegAnd
=== インスタンスメソッド
--- initialize(reg1,reg2)
      コンストラクタ
--- =~(str)
      ((|str|))が((|reg1|))と((|reg2|))の両方にマッチすれば真を返す

== class RegOr
=== インスタンスメソッド
--- initialize(reg1,reg2)
      コンストラクタ
--- =~(str)
      ((|str|))が((|reg1|))か((|reg2|))のいずれかにマッチすれば真を返す
=end

=begin
= final.rb
== 目的・概要
オブジェクト単位のfinalization機構を提供する。

ObjectSpaceに追加メソッドを定義して、個別のオブジェクトごとに
ファイナライザprocを指定できるようにする。
== サンプルコード
なし
== module ObjectSpace (拡張)
--- define_finalizer(obj,proc=lambda())
        ((|obj|))が解放されるときに実行されるファイナライザを登録する。
        同じオブジェクトについて複数回呼ばれたときは置き換えではなく
        追加登録される。
--- undefine_finalizer(obj)
        ((|obj|))に対するファイナライザをすべて解除する。
=end

=begin
= Observable
== 目的・概要
Mix-inによりobserverパターンを提供する。

Observableモジュールをincludeしたクラスは
Observable#changedメソッドにより更新フラグを立て、
Observable#notify_observers()が呼び出されると
更新フラグが立っている場合はオブザーバに通知する
(オブザーバのupdateメソッドを呼び出す)。
Observable#notify_observers()の引数は
そのままオブザーバのupdateメソッドに渡される。
== サンプルコード
  require 'observer'
  class AObservable
    include Observable
    ...
  end
  class AObserver
    def update(arg)
      ...
    end
    ...
  end
  obj = AObservable::new
  observer = AObserver::new
  obj.add_observer(observer)
  obj.changed
  obj.update_observers(args)
== モジュールメソッド
--- add_observer(observer)
        オブザーバを追加する。
        オブザーバは(({update}))メソッドを備えている必要がある。

        ((|observer|))が(({update}))メソッドを持たないときは
        例外NameErrorを発生する。
--- delete_observer(observer)
        オブザーバを削除する。
--- delete_observers
        オブザーバをすべて削除する。
--- count_observers
        オブザーバの数を返す。
--- changed(state=true)
        更新フラグを立てる。
--- changed?
        更新フラグの状態を返す。
--- notify_observers(*arg)
        更新フラグが立っていたら、オブザーバの(({update}))メソッドを呼び出す。
        与えられた引数はその(({update}))メソッドに渡される。
        更新フラグは(({false}))になる。
=end

=begin
= Singleton
== 目的・概要
Mix-inによりsingletonパターンを提供する。

Singletonモジュールをincludeすることにより、クラスは
高々ひとつのインスタンスしか持たないことが保証される。

Singletonをmix-inしたクラスの
クラスメソッド(({instance}))はその唯一のインスタンスを返す。

(({new}))はprivateメソッドに移され、外部から呼び出そうとするとエラーになる。
== サンプルコード
   class SomeSingletonClass
     include Singleton
    #....
   end
   a = SomeSingletonClass.instance
   b = SomeSingletonClass.instance	# a and b are same object
   p [a,b]
   a = SomeSingletonClass.new		# error (`new' is private)
== モジュールメソッド
--- instance
        そのクラスの唯一のインスタンスを返す。
        最初に呼ばれたときはそのインスタンスを生成する。

        Singletonをincludeしたクラスで定義されるので、
        正確にはSingletonモジュールのメソッドではない。
=end

=begin
= tracer.rb
== 目的・概要
実行トレース出力をとる機能を提供する。

使い方は大きく分けて2通り。
:((%ruby -rtracer hoge.rb%))
        hoge.rbの実行をすべてトレース出力する。

:(({require 'tracer'}))
        (({Tracer.on}))
        によりトレース出力を有効にする。

        (({Tracer.off}))
        によりトレース出力を無効にする。

        また、ブロック付きで (({Tracer.on})) を呼び出すと、そのブロック内のみ
        トレースを出力する。
== サンプルコード
なし
== class Tracer
=== クラスメソッド
--- Tracer.on
--- Tracer.on {...}
        トレース出力を開始。
        ブロックを与えられた場合はそのブロック内のみトレース出力を行う。
--- Tracer.off
        トレース出力を中断。
--- Tracer.set_get_line_procs(filename, proc)
--- Tracer.set_get_line_procs(filename) { |line| ...}
        あるファイルについて利用する、行番号からソースのその行の内容を返す
        手続きを指定する。何も指定しなければデフォルトの動作が利用される。
        指定する手続きは行番号を唯一の引数として呼び出される。
--- Tracer.add_filter(proc)
--- Tracer.add_filter { |event,file,line,id,binding| ...}
        トレース出力するかどうかを決定するフィルタを追加する。
        何もフィルタを与えない場合はすべての行についてトレース情報が出力される。
        与えられた手続き(ブロックまたはProcオブジェクト)が真を返せば
        トレースは出力される。
        フィルタは複数追加でき、そのうち一つでも偽を返すとトレースの出力は
        抑制される。
        フィルタ手続きは引数として event,file,line,id,binding の5つ
        をとる(組み込み関数set_trace_funcで指定するものとほぼ同じ)。
        set_trace_funcに関してはRuby本 p.391を参照。

        :フィルタ手続きのパラメータ
          Ruby本 p.391より。
          :event
            イベントを表す文字列。
            
            以下の種類がある。カッコ内はtracer.rbの出力での表記。
            :line (-) 
                ある行を実行
            :call (>) 
                メソッド呼び出し
            :return (<) 
                メソッドからのリターン
            :class (C)
                クラスコンテキストに入った
            :end (E)
                クラスコンテキストから出た
            :raise
                例外が発生した
            :c-call
                Cで記述されたメソッドが呼ばれた
            :c-return
                Cで記述されたメソッドからreturn
          :file
            現在処理しているファイルの名前
          :line
            現在処理している行番号
          :id
            最後に呼び出されたメソッドのメソッド名(のシンボル)
            そのようなメソッドがなければ0になる。
          :binding
            現在のコンテキスト
== SEE ALSO
* set_trace_func
=end

=begin
= weakref.rb
== 目的・概要
WeakRefクラスによりweak referenceを実現する。

WeakRefオブジェクトは与えられたオブジェクトをポイントするが、
ポイント先のオブジェクトはGCされる可能性がある。
アクセスしようとしたときにオブジェクトがGCされていれば
WeakRef::RefErrorが発生する。
== サンプルコード
 require 'weakref'
 foo = Object.new
 ref = WeakRef::new(foo)
 ref.some_method_of_foo
== class WeakRef
weak referenceを提供するクラス。

:上位クラス
        Delegator
=== クラスメソッド
--- new(obj)
        ((|obj|))へのweak referenceを生成する
=== インスタンスメソッド
--- weakref_alive?
        参照先のオブジェクトがまだ生きていればtrueを返す

== class WeakRef::RefError
GCされたオブジェクトを参照しようとしたときに発生する例外。
:上位クラス
        StandardError
== see also
* delegate.rb
=end