* ext/readline/README.ja: updated API document for Readline module.

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@18418 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

ChangeLog

@@ -1,3 +1,7 @@
+Thu Aug  7 22:55:44 2008  TAKAO Kouji  <kouji@takao7.net>
+
+	* ext/readline/README.ja: updated API document for Readline module.
+
 Thu Aug  7 20:52:08 2008  Shugo Maeda  <shugo@ruby-lang.org>
 
 	* lib/net/ftp.rb (login): raise FTPReplyError if passwd or acct

ext/readline/README.ja

@@ -1,63 +1,404 @@
-GNU Readline Libraryを利用するための拡張モジュールです。
+GNU Readline によるコマンドライン入力インタフェースを提供するモジュール
+です。GNU Readline の互換ライブラリのひとつである Edit Line(libedit) も
+サポートしています。
 
-require "readline"
-include Readline
+GNU Readline:: http://www.gnu.org/directory/readline.html
+libedit::      http://www.thrysoee.dk/editline/
 
-line = readline("Prompt> ", true)
+Readline.readline を使用してユーザからの入力を取得できます。このとき、
+GNU Readline のように入力の補完やEmacs のようなキー操作などができます。
 
-のように使用してください。
+  require "readline"
+  while buf = Readline.readline("> ", true)
+    p buf
+  end
 
-[Readline]
+ユーザが入力した内容を履歴(以下、ヒストリ)として記録することができます。
+定数 Readline::HISTORY を使用してヒストリにアクセスできます。
 
-<モジュール関数>
+  require "readline"
+  while buf = Readline.readline("> ", true)
+    p Readline::HISTORY.to_a
+    print("-> ", buf, "\n")
+  end
 
-readline(prompt, add_history=nil)
+使用するライブラリにより、いくつかのメソッドで例外 NotImplementedError
+が発生します。
 
-  一行入力を読み込みます。
-  add_historyがtrueの場合、ヒストリに読み込んだ文字列を追加します。
+$SAFE が 4 の場合、多くのメソッドで例外 SecurityError が発生します。
 
-<クラスメソッド>
+== Readline モジュール
 
-completion_proc = proc
+=== モジュール関数
 
-  補完時の動作を決定するProcオブジェクトを指定します。
-  procは引数に入力文字列を取り、候補文字列の配列を返すように
-  してください。
+readline([prompt, [add_hist]]) -> String | nil
 
-completion_proc
+  prompt を出力し、ユーザからのキー入力を待ちます。
+  エンターキーの押下などでユーザが文字列を入力し終えると、
+  入力した文字列を返します。
+  このとき、add_hist が true であれば、入力した文字列をヒストリに追加します。
+  
+  何も入力していない状態で EOF(UNIX では ^D) を入力するなどで、
+  ユーザからの入力がない場合は nil を返します。
+  
+  次の条件を全て満たす場合、例外 IOError が発生します。
+  1. 標準入力が tty でない。
+  2. 標準入力をクローズしている。(isatty(2) の errno が EBADF である。)
+  
+  本メソッドはスレッドに対応しています。
+  入力待ち状態のときはスレッドコンテキストの切替えが発生します。
+  
+  入力時には行内編集が可能で、vi モードと Emacs モードが用意されています。
+  デフォルトは Emacs モードです。
+  
+  本メソッドには注意事項があります。
+  入力待ちの状態で ^C すると ruby インタプリタが終了し、端末状態を復帰しません。
+  これを回避するための例を3つ挙げます。
+  
+  * ^CによるInterrupt例外を補足して、端末状態を復帰します:
+  
+      require "readline"
+      
+      stty_save = `stty -g`.chomp
+      begin
+        while buf = Readline.readline
+            p buf
+            end
+          rescue Interrupt
+            system("stty", stty_save)
+            exit
+          end
+        end
+      end
+  
+  * INTシグナルを補足して、端末状態を復帰します:
+  
+      require "readline"
+      
+      stty_save = `stty -g`.chomp
+      trap("INT") { system "stty", stty_save; exit }
+    
+      while buf = Readline.readline
+        p buf
+      end
+  
+  * 単に ^C を無視する方法もあります:
+  
+      require "readline"
+      
+      trap("INT", "SIG_IGN")
+      
+      while buf = Readline.readline
+        p buf
+      end
+  
+  入力履歴 Readline::HISTORY を使用して、空行や直前の入力と同じ内容は入力
+  履歴に残さないということもできます。
+  
+    require "readline"
+      
+    while buf = Readline.readline("> ", true)
+      # p Readline::HISTORY.to_a
+      Readline::HISTORY.pop if /^\s*$/ =~ buf
+   
+      begin
+        if Readline::HISTORY[Readline::HISTORY.length-2] == buf
+          Readline::HISTORY.pop 
+        end
+      rescue IndexError
+      end
+   
+      # p Readline::HISTORY.to_a
+      print "-> ", buf, "\n"
+    end
+  
+  $SAFE が 4 の場合、例外 SecurityError が発生します。
 
-  補完時の動作を決定するProcオブジェクトを返します。
+=== クラスメソッド
 
-completion_case_fold = case_fold
+Readline.input = input
 
-  補完時に大文字小文字を区別しない場合、trueを指定します。
+  Readline.readline メソッドで使用する入力用の File オブジェクト input
+  を指定します。
 
-completion_case_fold
+  $SAFE が 4 の場合、例外 SecurityError が発生します。
 
-  補完時に大文字小文字を区別しない場合、trueを返します。
+Readline.output = output
 
-completion_append_character = char
+  Readline.readline メソッドで使用する出力用の File オブジェクト
+  output を指定します。
 
-  補完時に付加される文字を文字列で指定します。先頭の一文字が
-  設定され、空文字列 ("") または nil を指定すると何も付加
-  されなくなります。
+  $SAFE が 4 の場合、例外 SecurityError が発生します。
 
-completion_append_character
+Readline.completion_proc = proc
 
-  補完時に付加される文字を文字列で返します。デフォルトは
-  空白 (" ") です。
+  ユーザからの入力を補完する時の候補を取得する Proc オブジェクト proc を
+  指定します。proc は、次のものを想定しています。
+  1. call メソッドを持ちます。
+     call メソッドを持たない場合、例外 ArgumentError が発生します。
+  2. 引数にユーザからの入力文字列(注1)を取ります。
+  3. 候補の文字列の配列を返します。
 
-vi_editing_mode
+  注1:「/var/lib /v」の後で補完を行うと、
+  デフォルトでは proc の引数に「/v」が渡されます。
+  このように、ユーザが入力した文字列を
+  Readline.completer_word_break_characters に含まれる文字で区切ったも
+  のを単語とすると、カーソルがある単語の最初の文字から現在のカーソル位
+  置までの文字列が proc の引数に渡されます。
 
-  VIモードになります。
+  $SAFE が 4 の場合、例外 SecurityError が発生します。
 
-emacs_editing_mode
+Readline.completion_proc -> proc
 
-  Emacsモードになります。
+  ユーザからの入力を補完する時の候補を取得する Proc オブジェクト proc
+  を取得します。
 
-<クラス定数>
+  $SAFE が 4 の場合、例外 SecurityError が発生します。
+
+Readline.completion_case_fold = bool
+
+  ユーザの入力を補完する際、大文字と小文字を区別する／しないを指定します。
+  bool が真ならば区別しません。bool が偽ならば区別します。
+
+  $SAFE が 4 の場合、例外 SecurityError が発生します。
+
+Readline.completion_case_fold -> bool
+
+  ユーザの入力を補完する際、大文字と小文字を区別する／しないを取得します。
+  bool が真ならば区別しません。bool が偽ならば区別します。
+
+ なお、Readline.completion_case_fold= メソッドで指定したオブジェクトを
+ そのまま取得するので、次のような動作をします。
+
+   require "readline"
+   
+   Readline.completion_case_fold = "This is a String."
+   p Readline.completion_case_fold # => "This is a String."
+
+  $SAFE が 4 の場合、例外 SecurityError が発生します。
+
+Readline.vi_editing_mode -> nil
+
+  編集モードを vi モードにします。
+  vi モードの詳細は、GNU Readline のマニュアルを参照してください。
+
+  サポートしていない環境では、例外 NotImplementedError が発生します。
+
+  $SAFE が 4 の場合、例外 SecurityError が発生します。
+
+Readline.emacs_editing_mode -> nil
+
+  編集モードを Emacs モードにします。
+  デフォルトは Emacs モードです。
+  Emacs モードの詳細は、GNU Readline のマニュアルを参照してください。
+
+  サポートしていない環境では、例外 NotImplementedError が発生します。
+
+  $SAFE が 4 の場合、例外 SecurityError が発生します。
+
+Readline.completion_append_character = char
+
+  ユーザの入力の補完が完了した場合に、最後に付加する文字 char を指定し
+  ます。半角スペース「" "」などの単語を区切る文字を指定すれば、連続して
+  入力する際に便利です。
+
+  使用例:
+
+    require "readline"
+    
+    Readline.readline("> ", true)
+    Readline.completion_append_character = " "
+
+  実行例:
+
+    >
+    ここで "/var/li" を入力します。
+    
+    > /var/li
+    ここで TAB キーを入力します。
+    
+    > /var/lib
+    "b" が補完され、最後に " " が追加されるので、"/usr" を連続して入力できます。
+    
+    > /var/lib /usr
+
+  なお、1文字しか指定することはできません。
+  例えば、"string"を指定した場合は最初の文字である"s"だけを使用します。
+
+    require "readline"
+
+    Readline.completion_append_character = "string"
+    p Readline.completion_append_character # => "s"
+
+  サポートしていない環境では、例外 NotImplementedError が発生します。
+
+  $SAFE が 4 の場合、例外 SecurityError が発生します。
+
+Readline.completion_append_character -> char
+
+  ユーザの入力の補完が完了した場合に、最後に付加する文字を取得します。
+  デフォルトは空白 (" ") です。
+
+  サポートしていない環境では、例外 NotImplementedError が発生します。
+
+  $SAFE が 4 の場合、例外 SecurityError が発生します。
+
+Readline.basic_word_break_characters = string
+
+  ユーザの入力の補完を行う際、単語の区切りを示す複数の文字で構成される
+  文字列 string を指定します。
+
+  GNU Readline のデフォルトの値は、Bash の補完処理で使用している文字列
+  " \t\n\"\\'`@$><=;|&{(" (スペースを含む) になっています。
+
+  サポートしていない環境では、例外 NotImplementedError が発生します。
+
+  $SAFE が 4 の場合、例外 SecurityError が発生します。
+
+Readline.basic_word_break_characters -> string
+
+  ユーザの入力の補完を行う際、単語の区切りを示す複数の文字で構成される
+  文字列を取得します。
+
+  サポートしていない環境では、例外 NotImplementedError が発生します。
+
+  $SAFE が 4 の場合、例外 SecurityError が発生します。
+
+Readline.completer_word_break_characters = string
+
+  ユーザの入力の補完を行う際、単語の区切りを示す複数の文字で構成される
+  文字列 string を指定します。
+  Readline.basic_word_break_characters= との違いは、
+  GNU Readline の rl_complete_internal 関数で使用されることです。
+
+  GNU Readline のデフォルトの値は、 
+  Readline.basic_word_break_characters と同じです。
+
+  サポートしていない環境では、例外 NotImplementedError が発生します。
+
+  $SAFE が 4 の場合、例外 SecurityError が発生します。
+
+Readline.completer_word_break_characters -> string
+
+  ユーザの入力の補完を行う際、単語の区切りを示す複数の文字で構成された
+  文字列を取得します。
+
+  サポートしていない環境では、例外 NotImplementedError が発生します。
+
+  $SAFE が 4 の場合、例外 SecurityError が発生します。
+
+Readline.basic_quote_characters = string
+
+  スペースなどの単語の区切りをクオートするための複数の文字で構成される
+  文字列 string を指定します。
+
+  サポートしていない環境では、例外 NotImplementedError が発生します。
+
+  $SAFE が 4 の場合、例外 SecurityError が発生します。
+
+Readline.basic_quote_characters -> string
+
+  スペースなどの単語の区切りをクオートするための複数の文字で構成される
+  文字列を取得します。
+
+  サポートしていない環境では、例外 NotImplementedError が発生します。
+
+  $SAFE が 4 の場合、例外 SecurityError が発生します。
+
+Readline.completer_quote_characters = string
+
+  ユーザの入力の補完を行う際、スペースなどの単語の区切りを
+  クオートするための複数の文字で構成される文字列 string を指定します。
+  指定した文字の間では、Readline::completer_word_break_characters=
+  で指定した文字列に含まれる文字も、普通の文字列として扱われます。
+
+  サポートしていない環境では、例外 NotImplementedError が発生します。
+
+  $SAFE が 4 の場合、例外 SecurityError が発生します。
+
+Readline.completer_quote_characters -> string
+
+  ユーザの入力の補完を行う際、スペースなどの単語の区切りを
+  クオートするための複数の文字で構成される文字列を取得します。
+
+  サポートしていない環境では、例外 NotImplementedError が発生します。
+
+  $SAFE が 4 の場合、例外 SecurityError が発生します。
+
+Readline.filename_quote_characters = string
+
+  ユーザの入力時にファイル名の補完を行う際、スペースなどの単語の区切りを
+  クオートするための複数の文字で構成される文字列 string を指定します。
+
+  GNU Readline のデフォルト値は nil です。
+
+  サポートしていない環境では、例外 NotImplementedError が発生します。
+
+  $SAFE が 4 の場合、例外 SecurityError が発生します。
+
+Readline.filename_quote_characters -> string
+
+  ユーザの入力時にファイル名の補完を行う際、スペースなどの単語の区切りを
+  クオートするための複数の文字で構成される文字列を取得します。
+
+  サポートしていない環境では、例外 NotImplementedError が発生します。
+
+  $SAFE が 4 の場合、例外 SecurityError が発生します。
+
+=== クラス定数
 
 HISTORY
 
-ヒストリに対する操作はこの定数を通して行ってください。
-配列と同じように扱えるようになっています。
+  定数 HISTORY を使用してヒストリにアクセスできます。
+  Enumerable モジュールを extend しており、
+  配列のように振る舞うことができます。
+  例えば、HISTORY[4] により 5 番目に入力した内容を取り出すことができます。
+
+    require "readline"
+    
+    Readline::HISTORY.push("a", "b", "c", "d", "e")
+    p Readline::HISTORY[4] # => "e"
+
+  実装しているメソッドを次に挙げます。
+  * HISTORY.to_s -> "HISTORY"
+  * HISTORY[index] -> string
+  * HISTORY[index] = string
+  * HISTORY.push(string[, string, ...]) -> self
+  * HISTORY << string -> self
+  * HISTORY.pop -> string
+  * HISTORY.shift -> string
+  * HISTORY.each -> Enumerable::Enumerator
+  * HISTORY.each { |i| } -> [string]
+  * HISTORY.length -> Integer
+  * HISTORY.empty? -> true or false
+  * HISTORY.delete_at(index) -> string
+  * HISTORY.clear -> self
+
+  サポートしていない環境では、次のメソッドで例外 NotImplementedError が
+  発生します。
+  * HISTORY[index] = string
+  * HISTORY.pop -> string
+  * HISTORY.shift -> string
+  * HISTORY.delete_at(index) -> string
+  * HISTORY.clear -> self
+
+  $SAFE が 4 の場合、ヒストリにアクセスしたときに例外 SecurityError が
+  発生します。
+
+FILENAME_COMPLETION_PROC
+
+  ファイル名の補完を行う call メソッドを持つオブジェクトです。
+ 
+  Readline.completion_proc= により、ユーザの入力時にファイル名の補完を
+  行うように設定するために使用することを想定してます。
+
+USERNAME_COMPLETION_PROC
+
+  ユーザ名の補完を行う call メソッドを持つオブジェクトです。
+
+  Readline.completion_proc= により、ユーザの入力時にユーザ名の補完を行
+  うように設定するために使用することを想定してます。
+
+VERSION
+
+  使用している GNU Readline または libedit のバージョンです。