青木です。細切れなメールですみません。

  In mail "[ruby-reference-manual:285] Re: requireするライブラリの存在について"
  Minero Aoki <aamine@l...> wrote:

require を書く理由 1

> ユーザが、あるライブラリを require したときに使えるクラスの一覧を出す
> ためです。例えば require 'tk' と書いたら tk ライブラリの一連のクラス
> はすべて使えるようになるわけですが、src/tk.rd 自体にはその一部しか書
> いてありません。つまり、tk 以下のライブラリのページを全部見ないと使える
> クラスがわからないわけです。それでは不便なので、require を書いといて、
> 自動的にクラス一覧を計算できるようにしよう、ということです。

require を書く理由 2

> もう一つありました。
> あるクラスを使いたいとき、どのライブラリを require すればいいか示すためです。
> 
> 例えば Test::Unit::TestCase が使いたいと思ったとき、所属するライブラリは
> test/unit/testcase だけれども、実際には test/unit を require するのが
> 普通です。その「普通 require するライブラリ」を計算するためには require
> を書いておく必要があります。


この 2 つの理由から、require を書くときのルールが導出できます。すなわち、

  (1) 「あるライブラリを require したとき、同時に使えると仮定してよい
       ライブラリ」は、ドキュメントにも require を書くべき。
       e.g. webrick を require したら webrick/httpserver を使えるのは

  (1') 「あるライブラリを require したとき一緒に require されるけど、
         それは一種の偶然であるライブラリ」は、ドキュメントに書くべきでない。
       e.g. webrick が fcntl を require しているのは
            「一種の偶然」なので、ドキュメントに書くべきではない。

  (2) あるクラスを使いたいとき、そのクラスから「require すべきライブラリ」
      までは、ドキュメントの require を逆にたどって到達できなければならない。
       e.g. WEBrick::HTTPServer が書いてあるドキュメントファイルから
            require を逆にたどって webrick.rd に到達できなければならない。

  (2') あるクラスからドキュメントの require を逆にたどって到達できる
       ライブラリは、すべて「そのクラスを使うために require するのが
       適切である」ライブラリでなければならない。
       e.g. Fcntl モジュールを使いたいときに webrick ライブラリを
            require するのは不適切である。したがって、webrick.rd
            から require をたどって fcntl に到達できてはならない。

ちょっと混乱ぎみなので、まずファイル構成についてまとめます。

  * このリファレンスマニュアルにおける「ライブラリ」とは、
    ユーザが require する単位のことである。複数の *.rb が
    存在する場合でも、require する *.rb が 1 つだけなら
    ドキュメントでは 1 つにまとめる。

    この、「リファレンスマニュアルにおけるライブラリ」を
    仮に logical library と呼んでおく。

  * 1 つの logical library は原則として 1 つの .rd で
    表現される。それでファイルが大きくなりすぎる場合は、
    ファイルを分割しておき、#@include を使って結合する。

で、logical library の主要ファイル 1 つのみに「.rd」という拡張子を
付け、それ以外の (#@include される) ファイルには拡張子を付けない、
というのが原則です。_builtin 以下のファイルは拡張子がついてますが、
あれは一時の気の迷いです。いま移動しました。

次に、require についてまとめます。

  * 2 つの logical library の間に「このライブラリを
    require したら、こっちのライブラリも使えるのが当然である」
    という関係がある場合は、ドキュメントにも require を書く。

  * ドキュメントにおける require は、logical library 同士の
    関係である。つまり、logical library でない名前、*.rb に
    しかない名前を書いてはいけない。

--
青木峰郎

--
ML: ruby-reference-manual@m...
使い方: http://QuickML.com/