About ReFe
==========

  ReFe (りふぇ) は ri or rdindex もどきの Ruby メソッド
  検索ましーんです。ただし ri とは違って RD リファレンス
  から直接情報を読みこみます。

インストール
------------

  コマンドラインで次のように打ってください。

      $ ruby install.rb config
      $ ruby install.rb setup
     ($ su)
      # ruby install.rb install

  install.rb の詳しい使い方は ruby install.rb --help で見られます。


初期設定
--------

  バージョン 0.6 からは処理済みのデータベースが添付されているので
  自分でデータベースを作る必要はありません。環境変数 REFE_DATA_DIR
  にデータベースのあるディレクトリを設定すればすぐに使えます。
  REFE_DATA_DIR のデフォルトは /usr/local/share/refe です。

  [環境変数の設定]

      (sh 系の場合)
      $ REFE_DATA_DIR=/usr/local/share/refe
      $ export REFE_DATA_DIR

      (csh 系の場合)
      % setenv REFE_DATA_DIR /usr/local/share/refe


基本的な使い方
--------------

  まず

      $ refe

  とだけ打つと、データベースにドキュメントが収録されている
  クラスが全て表示されます。まずはこれで動作を確認してください。

  次に、リファレンスマニュアルのエントリを表示するには、

      $ refe メソッド名
      $ refe クラス名
      $ refe クラス名 メソッド名

  のいずれかを使います。メソッドを指定するとメソッドの説明、
  クラスだけを指定すると定義されているメソッドの一覧が表示されます。

      # 実行例

      $ refe Array
      ==== Array ====
      配列クラス。配列の要素は任意の Ruby オブジェクトです。
      一般的には配列は配列式を使って

	[1, 2, 3]

      のように生成します。
      ---- Singleton methods ----
      [] new
      ---- Instance methods ----
      & * + << <=> == [] []= assoc at clear clone collect! compact
      compact! concat delete delete_at delete_if dup each
      each_index empty? eql? fetch fill first flatten flatten!
      include? index indexes indices insert join last length map!
      nitems pack pop push rassoc reject! replace reverse
      reverse! reverse_each rindex self shift size slice slice!
      sort sort! to_a to_ary to_s transpose uniq uniq! unshift
      values_at |

      $ refe 'Array#to_a'
      Array#to_a
      --- to_a
      --- to_ary

	  self をそのまま返します。

      $ refe Array to_a      ← '#' はなくてもよい
      Array#to_a
	       ：
	       ：

  また特殊なクラスとして「man」というものがあります。このクラスには
  「sprintfフォーマット」や「packテンプレート文字列」が収録されています。

      $ refe man.            ← 最後にピリオドが必要 (後述の補完を使っている)
      man.pack man.sprintf

      $ refe man.sprintf
      man.sprintf
      = sprintfフォーマット

      Ruby の sprintf フォーマットは基本的に C 言語の sprintf(3) [manual page]
      のものと同じです。ただし、short や long などの C 特有の型に対する修飾子が
      ないこと、2進数の指示子(%b)が存在すること、sprintf のすべての方言をサ
      ポートしていないこと(': 3桁区切り)などの違いがあります。

      rubyのsprintfフォーマットに関する完全な説明は以下の通りです。
			  ：
			  ：

少しだけ便利な技
----------------

  ReFe はメソッド名を以下の三つの組み合わせで管理します。

    * クラス名 (例えば Array)
    * インスタンスメソッド／特異メソッドの指定 (#/.)
    * メソッド名 (例えば to_a)

  つまり $ refe Array '#' to_a と打つと確実にただ一つのメソッドを
  指定できるわけです。

  しかし毎回この完全名を打つのは面倒なので、一意に定まる限りは
  ほとんどの部分は省略できるようになっています。以下に大雑把な
  省略ルールを示します。

    * #/. は省略可能
    * クラス名・メソッド名はどちらかだけでもよい
    * 単語が小文字だけの場合、大文字小文字を区別しない。
      例えば Hash を hash としてもよい。
    * 名前は先頭だけでもよい。
      例えば concat は conca conc con co c と短くしていける。
    * gsub! など末尾に !?= がつくメソッドは記号の前だけを省略できる。
      例えば gsub! は gsu! gs! g! と省略できる。

   以上の省略ルールを適用してメソッドを特定できればそのメソッドの
   ドキュメントを表示します。

      $ refe str ind
      String#index
      --- index(pattern[, pos])

	  部分文字列の探索を左端から右端に向かって行います。見つかった部分文
	  字列の左端の位置を返します。見つからなければ nil を返します。

   省略されすぎて特定できなくなった場合は候補を一覧します。

      $ refe s in
      Singleton#instance String#include? String#index
      String#insert String#intern Super#in_reply_to Syslog#info
      Syslog#inspect Syslog.instance

   このような場合には -a オプションを使うと全ての候補のドキュメントが
   表示できます。

   以下にいくつか省略の例を示します。

      $ refe String          String のメソッド一覧を表示
      $ refe each_with_index Enumerable#each_with_index の説明を表示
      $ refe String#index    String#index の説明を表示
      $ refe s#ind           String#index の説明を表示
      $ refe inde            Array#index String#index など、一致する候補を表示
      $ refe s ind           String#index の説明を表示
      $ refe st g!           String#gsub! の説明を表示

  挙句はワイルドカードまで使えたりします。

      $ refe '*!'            '!' で終わるメソッド全部


さらに進んだ使い方
------------------

  コマンドラインオプションを付けるとメソッドのドキュメント以外も
  検索できます。

  -e を付けると Ruby C API のドキュメントを引きます。

      $ refe -e r d class          rb_define_class() の説明を表示
      $ refe -e _s args            rb_scan_args() の説明を表示
      $ refe -e r e s w            下線でくぎられた単語ごとに補完可能！
                                   → rb_eval_string_wrap()
      $ refe -e r eval             最後の単語が完全一致したら残りは切り捨て
                                   → rb_eval()

  -c を付けるとメソッド名からその実体の関数を引きます。

      $ refe -c s g!               rb_str_gsub_bang() の内容を表示

  -C なら関数名で直接引きます。
  -e と同様の補完が効きます。

      $ refe -C rb_str_gsub_bang   rb_str_gsub_bang() の内容を表示


データベースの更新
------------------

  (-withdoc, -withdocsrc パッケージをインストールした場合は必要ありません)

  (1) 基本ライブラリ・標準添付ライブラリ リファレンスマニュアル

  まず RDP から ruby-refm.rd を入手します。インターネットに接続
  している状態で misc/get.sh を実行してください。以下の場所から
  手動で取ってきても構いません。その場合は gzip で解凍しておきます。

    http://www.rubyist.net/~rubikitch/refm/ruby-refm.rd.gz

  これをもとにデータベースを作ります。あらかじめ環境変数
  REFE_DATA_DIR を設定しておいてください。

    % mkrefe_rubyrefm ruby-refm.rb


  (2) 拡張ライブラリ API リファレンスマニュアル (オプション)

  -e オプションを使うために必要です。

  get.sh を実行すると extrefm.rd というファイルも同時にダウンロード
  されます。これが拡張モジュール API のリファレンスマニュアルを固めた
  ものです。手動で取ってくる場合は以下から取ってください。

    http://i.loveruby.net/archive/extrefm.rd

  取ってきたら以下を実行します。

    % mkrefe_extrefm extrefm.rd


  (3) ruby のソースコード (オプション)

  -c/-C オプションを使うために必要です。

  ruby のソースコード一式をどこかに展開して以下を実行してください。

    % mkrefe_rubysrc srcdir
    % mkrefe_mfrelation srcdir


  以上と同じやりかたで上書き更新も可能です。


名前の由来
----------

  レニウムと鉄。

  ………………冗談ですごめんなさい

  reference から ref にしようとしたらもうあったので
  refer にしようと思ったらやっぱりあったので re もあるので
  でも r はちょっと短すぎるので refe。


ライセンス
----------

  GNU Lesser General Public License version 2 です。
  LGPL の正式な内容および詳細についてはファイル COPYING を
  参照してください。


ホームページ
------------

  http://i.loveruby.net/ja/prog/refe.html


青木峰郎 <aamine@loveruby.net>
http://i.loveruby.net
