Find2.rb

                          Motoyuki Kasahara
                         (m-kasahr@sra.co.jp)


Copyright 1998, 2001  Motoyuki Kasahara

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation approved
by Free Software Foundation, Inc.


はじめに
========
`Find2.rb' は、UNIX の `find' コマンドのように、ファイルツリーを再帰
的に探索する Ruby のライブラリです。Ruby バージョン 1.6 およびそれ以降
のバージョンで動作します。

このプログラムはフリーソフトウェアです。あなたは、Free Software
Foundation が公表した GNU General Public License (GNU 一般公有使用許諾)
バージョン 2 あるいはそれ以降の各バージョンの中からいずれかを選択し、
そのバージョンが定める条項に従って本プログラムを再頒布または変更するこ
とができます。

このプログラムは有用とは思いますが、頒布にあたっては、市場性及び特定目
的適合性についての暗黙の保証を含めて、いかなる保証も行ないません。詳細
については GNU General Public License をお読みください。


`find.rb' との比較
==================
`Find2.rb' は Ruby と一緒に配布されている `find.rb' に似ていますが、
`Find2.rb' には次のような長所があります。

  * `-follow' オプションのサポート
    シンボリックリンクを辿ります。

  * `-depth' オプションのサポート
    サブディレクトリのエントリをすべて調べてから、サブディレクトリ自身
    を調べます。

  * `-xdev' オプションのサポート
    他のファイルシステムのディレクトリには降りていきません。

  * `find2' メソッドの提供
    見つかったエントリのファイル名と File::Stat の両方をイテレータブロッ
    クに渡します。


Details about the `Find2' class
===============================

Super Class
-----------
Object


Class Methods
-------------
find(filename...)
find(options, filename...)
find(filename...) {|name| ...}
find(options, filename...) {|name| ...}
    それぞれの `filename' に対して、再帰的にファイルツリーを下降します。

    ブロックが与えられなかった場合 (1 番目と 2 番目の形式の場合)、メソッ
    ドはファイル名のリストを Array オブジェクトにして返します。ブロッ
    クが与えられた場合 (3 番目と 4 番目の形式)、見つかった各エントリに
    対して、ブロックを評価します。`name' の値は、見つかったエントリの
    ファイル名です。

    第 1 引数が Hash オブジェクトであれば (2 番目と 4 番目の形式であれ
    ば)、`find' はそれをオプションとみまします。ハッシュのキーとして、
    有効なものは、以下の通り。

    `follow'
	値が `true' なら、`find' メソッドはシンボリックリンクを辿りま
	す。
    `depth'
	値が `true' なら、メソッドはサブディレクトリの下のエントリをす
	べて調べてから、そのサブディレクトリ自身を調べます。
    `xdev'
	値が `true' なら、メソッドは他のファイルシステムのディレクトリ
	に降りていきません。

find2(filename...)
find2(options, filename...)
find2(filename...) {|name, stat| ...}
find2(options, filename...) {|name, stat| ...}
    このメソッドは `find' に非常に良く似ていますが、ブロックに `stat'
    引数も渡します。`stat' は File::Stat オブジェクトで、見つかったエ
    ントリのステータスを表します。

    ブロックが与えられなかった場合 (1 番目と 2 番目の形式の場合) は、
    `find' と `find2' に違いはありません。

prune
    `find' あるいは `find2' メソッドに渡された `block' の中でこのメソッ
    ドを呼び出すと、`find' や `find2' は、現在いるディレクトリのエント
    リを調べなくなります。


使用例
------
    $list = Find2.find("/usr/local", "/usr/X11")
    $list = Find2.find2("/usr/local", "/usr/X11")

    $list = Find2.find({"follow" => true, "depth" => true}, "/usr")
    $list = Find2.find2("follow" => true, "depth" => true, "/usr")

    Find2.find({"xdev" => true}, "/opt", "/prj") do |name|
        print "#{name}\n"
    end

    Find2.find2({"xdev" => true}, "/opt", "/prj") do |name, stat|
        print "#{name}\n" if stat.directory?
    end