path: root/jni/ruby/ext/readline/README.ja

GNU Readline によるコマンドライン入力インタフェースを提供するモジュール
です。GNU Readline の互換ライブラリのひとつである Edit Line(libedit) も
サポートしています。

GNU Readline:: http://www.gnu.org/directory/readline.html
libedit::      http://www.thrysoee.dk/editline/

Readline.readline を使用してユーザからの入力を取得できます。このとき、
GNU Readline のように入力の補完やEmacs のようなキー操作などができます。

  require "readline"
  while buf = Readline.readline("> ", true)
    p buf
  end

ユーザが入力した内容を履歴(以下、ヒストリ)として記録することができます。
定数 Readline::HISTORY を使用してヒストリにアクセスできます。

  require "readline"
  while buf = Readline.readline("> ", true)
    p Readline::HISTORY.to_a
    print("-> ", buf, "\n")
  end

使用するライブラリにより、いくつかのメソッドで例外 NotImplementedError
が発生します。

== Readline モジュール

=== モジュール関数

readline([prompt, [add_hist]]) -> String | nil

  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

=== クラスメソッド

Readline.input = input

  Readline.readline メソッドで使用する入力用の File オブジェクト input
  ã‚’指定します。

Readline.output = output

  Readline.readline メソッドで使用する出力用の File オブジェクト
  output を指定します。

Readline.completion_proc = proc

  ãƒ¦ãƒ¼ã‚¶ã‹ã‚‰ã®å…¥åŠ›ã‚’補完する時の候補を取得する Proc オブジェクト proc を
  æŒ‡å®šã—ます。proc は、次のものを想定しています。
  1. call メソッドを持ちます。
     call メソッドを持たない場合、例外 ArgumentError が発生します。
  2. 引数にユーザからの入力文字列(注1)を取ります。
  3. 候補の文字列の配列を返します。

  æ³¨1:「/var/lib /v」の後で補完を行うと、
  ãƒ‡ãƒ•ã‚©ãƒ«ãƒˆã§ã¯ proc の引数に「/v」が渡されます。
  ã“のように、ユーザが入力した文字列を
  Readline.completer_word_break_characters に含まれる文字で区切ったも
  ã®ã‚’単語とすると、カーソルがある単語の最初の文字から現在のカーソル位
  ç½®ã¾ã§ã®æ–‡å­—列が proc の引数に渡されます。

Readline.completion_proc -> proc

  ãƒ¦ãƒ¼ã‚¶ã‹ã‚‰ã®å…¥åŠ›ã‚’補完する時の候補を取得する Proc オブジェクト proc
  ã‚’取得します。

Readline.completion_case_fold = bool

  ãƒ¦ãƒ¼ã‚¶ã®å…¥åŠ›ã‚’補完する際、大文字と小文字を区別する／しないを指定します。
  bool が真ならば区別しません。bool が偽ならば区別します。

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."

Readline.line_buffer -> string

  å…¥åŠ›ä¸­ã®è¡Œå…¨ä½“を返します。complete_proc の中で使用することを想定し
  ã¦ã„ます。Readline.line_buffer の長さは GNU Readline の rl_end 変数の
  å€¤ã¨ä¸€è‡´ã—ます。

Readline.point -> int

  ç¾åœ¨ã®ã‚«ãƒ¼ã‚½ãƒ«ã®ä½ç½®ã‚’返します。
  Readline モジュールは補完対象の単語の開始位置の情報を提供していません。
  ã—かしながら、 completion_proc の中で入力した単語 text と
  Readline.point を使用することで開始位置を導くことができます。

    é–‹å§‹ä½ç½® = 入力した単語の長さ - Readline.point

Readline.vi_editing_mode -> nil

  ç·¨é›†ãƒ¢ãƒ¼ãƒ‰ã‚’ vi モードにします。
  vi モードの詳細は、GNU Readline のマニュアルを参照してください。

  ã‚µãƒãƒ¼ãƒˆã—ていない環境では、例外 NotImplementedError が発生します。

Readline.vi_editing_mode? -> bool

  ç·¨é›†ãƒ¢ãƒ¼ãƒ‰ãŒ vi モードの場合、true を返します。そうでなければ false
  ã‚’返します。

  ã‚µãƒãƒ¼ãƒˆã—ていない環境では、例外 NotImplementedError が発生します。

Readline.emacs_editing_mode -> nil

  ç·¨é›†ãƒ¢ãƒ¼ãƒ‰ã‚’ Emacs モードにします。
  ãƒ‡ãƒ•ã‚©ãƒ«ãƒˆã¯ Emacs モードです。
  Emacs モードの詳細は、GNU Readline のマニュアルを参照してください。

  ã‚µãƒãƒ¼ãƒˆã—ていない環境では、例外 NotImplementedError が発生します。

Readline.emacs_editing_mode? -> bool

  ç·¨é›†ãƒ¢ãƒ¼ãƒ‰ãŒ Emacs モードの場合、true を返します。そうでなければ false
  ã‚’返します。

  ã‚µãƒãƒ¼ãƒˆã—ていない環境では、例外 NotImplementedError が発生します。

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 が発生します。

Readline.completion_append_character -> char

  ãƒ¦ãƒ¼ã‚¶ã®å…¥åŠ›ã®è£œå®ŒãŒå®Œäº†ã—た場合に、最後に付加する文字を取得します。
  ãƒ‡ãƒ•ã‚©ãƒ«ãƒˆã¯ç©ºç™½ (" ") です。

  ã‚µãƒãƒ¼ãƒˆã—ていない環境では、例外 NotImplementedError が発生します。

Readline.basic_word_break_characters = string

  ãƒ¦ãƒ¼ã‚¶ã®å…¥åŠ›ã®è£œå®Œã‚’行う際、単語の区切りを示す複数の文字で構成される
  æ–‡å­—列 string を指定します。

  GNU Readline のデフォルトの値は、Bash の補完処理で使用している文字列
  " \t\n\"\\'`@$><=;|&{(" (スペースを含む) になっています。

  ã‚µãƒãƒ¼ãƒˆã—ていない環境では、例外 NotImplementedError が発生します。

Readline.basic_word_break_characters -> string

  ãƒ¦ãƒ¼ã‚¶ã®å…¥åŠ›ã®è£œå®Œã‚’行う際、単語の区切りを示す複数の文字で構成される
  æ–‡å­—列を取得します。

  ã‚µãƒãƒ¼ãƒˆã—ていない環境では、例外 NotImplementedError が発生します。

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 が発生します。

Readline.completer_word_break_characters -> string

  ãƒ¦ãƒ¼ã‚¶ã®å…¥åŠ›ã®è£œå®Œã‚’行う際、単語の区切りを示す複数の文字で構成された
  æ–‡å­—列を取得します。

  ã‚µãƒãƒ¼ãƒˆã—ていない環境では、例外 NotImplementedError が発生します。

Readline.basic_quote_characters = string

  ã‚¹ãƒšãƒ¼ã‚¹ãªã©ã®å˜èªžã®åŒºåˆ‡ã‚Šã‚’クオートするための複数の文字で構成される
  æ–‡å­—列 string を指定します。

  ã‚µãƒãƒ¼ãƒˆã—ていない環境では、例外 NotImplementedError が発生します。

Readline.basic_quote_characters -> string

  ã‚¹ãƒšãƒ¼ã‚¹ãªã©ã®å˜èªžã®åŒºåˆ‡ã‚Šã‚’クオートするための複数の文字で構成される
  æ–‡å­—列を取得します。

  ã‚µãƒãƒ¼ãƒˆã—ていない環境では、例外 NotImplementedError が発生します。

Readline.completer_quote_characters = string

  ãƒ¦ãƒ¼ã‚¶ã®å…¥åŠ›ã®è£œå®Œã‚’行う際、スペースなどの単語の区切りを
  ã‚¯ã‚ªãƒ¼ãƒˆã™ã‚‹ãŸã‚ã®è¤‡æ•°ã®æ–‡å­—で構成される文字列 string を指定します。
  æŒ‡å®šã—た文字の間では、Readline.completer_word_break_characters=
  ã§æŒ‡å®šã—た文字列に含まれる文字も、普通の文字列として扱われます。

  ã‚µãƒãƒ¼ãƒˆã—ていない環境では、例外 NotImplementedError が発生します。

Readline.completer_quote_characters -> string

  ãƒ¦ãƒ¼ã‚¶ã®å…¥åŠ›ã®è£œå®Œã‚’行う際、スペースなどの単語の区切りを
  ã‚¯ã‚ªãƒ¼ãƒˆã™ã‚‹ãŸã‚ã®è¤‡æ•°ã®æ–‡å­—で構成される文字列を取得します。

  ã‚µãƒãƒ¼ãƒˆã—ていない環境では、例外 NotImplementedError が発生します。

Readline.filename_quote_characters = string

  ãƒ¦ãƒ¼ã‚¶ã®å…¥åŠ›æ™‚にファイル名の補完を行う際、スペースなどの単語の区切りを
  ã‚¯ã‚ªãƒ¼ãƒˆã™ã‚‹ãŸã‚ã®è¤‡æ•°ã®æ–‡å­—で構成される文字列 string を指定します。

  GNU Readline のデフォルト値は nil です。

  ã‚µãƒãƒ¼ãƒˆã—ていない環境では、例外 NotImplementedError が発生します。

Readline.filename_quote_characters -> string

  ãƒ¦ãƒ¼ã‚¶ã®å…¥åŠ›æ™‚にファイル名の補完を行う際、スペースなどの単語の区切りを
  ã‚¯ã‚ªãƒ¼ãƒˆã™ã‚‹ãŸã‚ã®è¤‡æ•°ã®æ–‡å­—で構成される文字列を取得します。

  ã‚µãƒãƒ¼ãƒˆã—ていない環境では、例外 NotImplementedError が発生します。

=== クラス定数

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 -> 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

FILENAME_COMPLETION_PROC

  ãƒ•ã‚¡ã‚¤ãƒ«åã®è£œå®Œã‚’行う call メソッドを持つオブジェクトです。

  Readline.completion_proc= により、ユーザの入力時にファイル名の補完を
  è¡Œã†ã‚ˆã†ã«è¨­å®šã™ã‚‹ãŸã‚ã«ä½¿ç”¨ã™ã‚‹ã“とを想定してます。

USERNAME_COMPLETION_PROC

  ãƒ¦ãƒ¼ã‚¶åã®è£œå®Œã‚’行う call メソッドを持つオブジェクトです。

  Readline.completion_proc= により、ユーザの入力時にユーザ名の補完を行
  ã†ã‚ˆã†ã«è¨­å®šã™ã‚‹ãŸã‚ã«ä½¿ç”¨ã™ã‚‹ã“とを想定してます。

VERSION

  ä½¿ç”¨ã—ている GNU Readline または libedit のバージョンです。