module Readline

要約

GNU Readline によるコマンドライン入力インタフェースを提供するモジュールです。

GNU Readline 互換ライブラリのひとつである Edit Line(libedit) もサポートしています。

• https://directory.fsf.org/wiki/Readline
• https://thrysoee.dk/editline/

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

例: プロンプト"> "を表示して、ユーザからの入力を取得する。

require 'readline'
while buf = Readline.readline("> ", true)
  print("-> ", buf, "\n")
end

ユーザが入力した内容を履歴(以下、ヒストリ)として記録できます。定数 Readline::HISTORY を使用して入力履歴にアクセスできます。例えば、Readline::HISTORY.to_a により、全ての入力した内容を文字列の配列として取得できます。

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

目次

特異メソッド

• basic_quote_characters
• basic_quote_characters=
• basic_word_break_characters
• basic_word_break_characters=
• completer_quote_characters
• completer_quote_characters=
• completer_word_break_characters
• completer_word_break_characters=
• completion_append_character
• completion_append_character=
• completion_case_fold
• completion_case_fold=
• completion_proc
• completion_proc=
• completion_quote_character
• delete_text
• emacs_editing_mode
• emacs_editing_mode?
• filename_quote_characters
• filename_quote_characters=
• get_screen_size
• input=
• insert_text
• line_buffer
• output=
• point
• point=
• pre_input_hook
• pre_input_hook=
• quoting_detection_proc
• quoting_detection_proc=
• redisplay
• refresh_line
• set_screen_size
• special_prefixes
• special_prefixes=
• vi_editing_mode
• vi_editing_mode?

モジュール関数

• readline

定数

• FILENAME_COMPLETION_PROC
• USERNAME_COMPLETION_PROC
• VERSION

特異メソッド

basic_quote_characters -> String[permalink][rdoc][edit]

スペースなどの単語の区切りをクオートするための複数の文字で構成される文字列を取得します。

[EXCEPTION] NotImplementedError:

サポートしていない環境で発生します。libedit(Edit Line)を使ったビルドでは、libedit の版によってはこのメソッドを利用できないため発生します。

[SEE_ALSO] Readline.basic_quote_characters=

basic_quote_characters=(string)[permalink][rdoc][edit]

スペースなどの単語の区切りをクオートするための複数の文字で構成される文字列 string を指定します。

GNU Readline のデフォルト値は、「"'」です。

[PARAM] string:

文字列を指定します。

[EXCEPTION] NotImplementedError:

サポートしていない環境で発生します。libedit(Edit Line)を使ったビルドでは、libedit の版によってはこのメソッドを利用できないため発生します。

[SEE_ALSO] Readline.basic_quote_characters

basic_word_break_characters -> String[permalink][rdoc][edit]

ユーザの入力の補完を行う際、単語の区切りを示す複数の文字で構成される文字列を取得します。

[EXCEPTION] NotImplementedError:

サポートしていない環境で発生します。

[SEE_ALSO] Readline.basic_word_break_characters=

basic_word_break_characters=(string)[permalink][rdoc][edit]

ユーザの入力の補完を行う際、単語の区切りを示す複数の文字で構成される文字列 string を指定します。

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

[PARAM] string:

文字列を指定します。

[EXCEPTION] NotImplementedError:

サポートしていない環境で発生します。

[SEE_ALSO] Readline.basic_word_break_characters

completer_quote_characters -> String[permalink][rdoc][edit]

ユーザの入力の補完を行う際、スペースなどの単語の区切りをクオートするための複数の文字で構成される文字列を取得します。

[EXCEPTION] NotImplementedError:

サポートしていない環境で発生します。

[SEE_ALSO] Readline.completer_quote_characters=

completer_quote_characters=(string)[permalink][rdoc][edit]

ユーザの入力の補完を行う際、スペースなどの単語の区切りをクオートするための複数の文字で構成される文字列 string を指定します。指定した文字の間では、Readline.completer_word_break_characters= で指定した文字列に含まれる文字も、普通の文字列として扱われます。

[PARAM] string:

文字列を指定します。

[EXCEPTION] NotImplementedError:

サポートしていない環境で発生します。

[SEE_ALSO] Readline.completer_quote_characters

completer_word_break_characters -> String[permalink][rdoc][edit]

ユーザの入力の補完を行う際、単語の区切りを示す複数の文字で構成された文字列を取得します。 Readline.basic_word_break_characters との違いは、 GNU Readline の rl_complete_internal 関数で使用されることです。

[EXCEPTION] NotImplementedError:

サポートしていない環境で発生します。

[SEE_ALSO] Readline.completer_word_break_characters=

completer_word_break_characters=(string)[permalink][rdoc][edit]

ユーザの入力の補完を行う際、単語の区切りを示す複数の文字で構成される文字列 string を指定します。 Readline.basic_word_break_characters= との違いは、 GNU Readline の rl_complete_internal 関数で使用されることです。

GNU Readline のデフォルトの値は、 Readline.basic_word_break_characters と同じです。

[PARAM] string:

文字列を指定します。

[EXCEPTION] NotImplementedError:

サポートしていない環境で発生します。

[SEE_ALSO] Readline.completer_word_break_characters

completion_append_character -> String[permalink][rdoc][edit]

ユーザの入力の補完が完了した場合に、最後に付加する文字を取得します。

[EXCEPTION] NotImplementedError:

サポートしていない環境で発生します。

[SEE_ALSO] Readline.completion_append_character=

completion_append_character=(string)[permalink][rdoc][edit]

ユーザの入力の補完が完了した場合に、最後に付加する文字 string を指定します。

[PARAM] string:

1文字を指定します。

[EXCEPTION] NotImplementedError:

サポートしていない環境で発生します。

半角スペース「" "」などの単語を区切る文字を指定すれば、連続して入力する際に便利です。

require 'readline'
Readline.readline("> ", true)
Readline.completion_append_character = " "
> /var/li
ここで補完(TABキーを押す)を行う。
> /var/lib
最後に" "が追加されているため、すぐに「/usr」などを入力できる。
> /var/lib /usr

なお、1文字しか指定することはできないため、例えば、"string"を指定した場合は最初の文字である"s"だけを使用します。

require 'readline'
Readline.completion_append_character = "string"
p Readline.completion_append_character # => "s"

[SEE_ALSO] Readline.completion_append_character

completion_case_fold -> bool[permalink][rdoc][edit]

ユーザの入力を補完する際、大文字と小文字を同一視する／しないを取得します。 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."

[SEE_ALSO] Readline.completion_case_fold=

completion_case_fold=(bool)[permalink][rdoc][edit]

ユーザの入力を補完する際、大文字と小文字を同一視する／しないを指定します。 bool が真ならば同一視します。bool が偽ならば同一視しません。

[PARAM] bool:

大文字と小文字を同一視する(true)／しない(false)を指定します。

[SEE_ALSO] Readline.completion_case_fold

completion_proc -> Proc[permalink][rdoc][edit]

ユーザからの入力を補完する時の候補を取得する Proc オブジェクト proc を取得します。

[SEE_ALSO] Readline.completion_proc=

completion_proc=(proc)[permalink][rdoc][edit]

ユーザからの入力を補完する時の候補を取得する Proc オブジェクト proc を指定します。 proc は、次のものを想定しています。

1. callメソッドを持つ。callメソッドを持たない場合、例外 ArgumentError を発生します。
2. 引数にユーザからの入力文字列を取る。
3. 候補の文字列の配列を返す。

「/var/lib /v」の後で補完を行うと、デフォルトでは proc の引数に「/v」が渡されます。このように、ユーザが入力した文字列を Readline.completer_word_break_characters に含まれる文字で区切ったものを単語とすると、カーソルがある単語の最初の文字から現在のカーソル位置までの文字列が proc の引数に渡されます。

[PARAM] proc:

ユーザからの入力を補完する時の候補を取得する Proc オブジェクトを指定します。 nil を指定した場合はデフォルトの動作になります。

例: foo、foobar、foobazを補完する。

require 'readline'

WORDS = %w(foo foobar foobaz)

Readline.completion_proc = proc {|word|
    WORDS.grep(/\A#{Regexp.quote word}/)
}

while buf = Readline.readline("> ")
  print "-> ", buf, "\n"
end

[SEE_ALSO] Readline.completion_proc

completion_quote_character -> String | nilRuby 2.5.0 から[permalink][rdoc][edit]

補完処理中(completion_proc の中など)に呼び出すと、補完対象の引数をクオートするために使われた文字を返します。引数がクオートされていない場合は nil を返します。

補完処理中以外に呼び出した場合は、常に nil を返します。

なお、Readline.completer_quote_characters= が設定されていない場合、このメソッドは常に nil を返します。

[EXCEPTION] NotImplementedError:

サポートしていない環境で発生します。libedit(Edit Line)を使ったビルドではこのメソッドを利用できないため発生します。

[SEE_ALSO] Readline.completer_quote_characters=

delete_text(start, length) -> selfRuby 2.1.0 から[permalink][rdoc][edit]

delete_text(range) -> self

delete_text -> self

現在の入力行のうち、指定した範囲のテキストを削除します。引数を省略した場合は、入力行全体を削除します。

[PARAM] start:

削除する範囲の開始位置を整数で指定します。

[PARAM] length:

削除する文字数を整数で指定します。

[PARAM] range:

削除する範囲を Range オブジェクトで指定します。

[EXCEPTION] NotImplementedError:

サポートしていない環境で発生します。libedit(Edit Line)を使ったビルドでは、libedit の版によってはこのメソッドを利用できないため発生します。

[SEE_ALSO] GNU Readline ライブラリの rl_delete_text 関数

emacs_editing_mode -> nil[permalink][rdoc][edit]

編集モードを Emacs モードにします。デフォルトは Emacs モードです。

Emacs モードの詳細は、 GNU Readline のマニュアルを参照してください。

• http://www.gnu.org/directory/readline.html

[EXCEPTION] NotImplementedError:

サポートしていない環境で発生します。libedit(Edit Line)を使ったビルドではこのメソッドを利用できないため発生します。

emacs_editing_mode? -> boolRuby 1.9.1 から[permalink][rdoc][edit]

Emacs モードが有効であれば true を返します。そうでなければ false を返します。

[EXCEPTION] NotImplementedError:

サポートしていない環境で発生します。libedit(Edit Line)を使ったビルドではこのメソッドを利用できないため発生します。

[SEE_ALSO] Readline.emacs_editing_mode

filename_quote_characters -> String[permalink][rdoc][edit]

ユーザの入力時にファイル名の補完を行う際、スペースなどの単語の区切りをクオートするための複数の文字で構成される文字列を取得します。

[EXCEPTION] NotImplementedError:

サポートしていない環境で発生します。libedit(Edit Line)を使ったビルドではこのメソッドを利用できないため発生します。

[SEE_ALSO] Readline.filename_quote_characters=

filename_quote_characters=(string)[permalink][rdoc][edit]

ユーザの入力時にファイル名の補完を行う際、スペースなどの単語の区切りをクオートするための複数の文字で構成される文字列 string を指定します。

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

[PARAM] string:

文字列を指定します。

[EXCEPTION] NotImplementedError:

サポートしていない環境で発生します。libedit(Edit Line)を使ったビルドではこのメソッドを利用できないため発生します。

[SEE_ALSO] Readline.filename_quote_characters

get_screen_size -> [Integer, Integer]Ruby 1.9.3 から[permalink][rdoc][edit]

端末のサイズを [rows, columns] で返します。

[EXCEPTION] NotImplementedError:

サポートしていない環境で発生します。

[SEE_ALSO] GNU Readline ライブラリの rl_get_screen_size 関数

input=(input)Ruby 1.9.3 から[permalink][rdoc][edit]

readline メソッドで使用する入力用の File オブジェクト input を指定します。戻り値は指定した File オブジェクト input です。

[PARAM] input:

File オブジェクトを指定します。

insert_text(string) -> selfRuby 2.0.0 から[permalink][rdoc][edit]

現在のカーソル位置に文字列 string を挿入します。

[PARAM] string:

挿入する文字列を指定します。

[EXCEPTION] NotImplementedError:

サポートしていない環境で発生します。

[SEE_ALSO] GNU Readline ライブラリの rl_insert_text 関数

line_buffer -> StringRuby 1.9.2 から[permalink][rdoc][edit]

編集中の行全体を返します。

completion_proc の中で、補完要求の文脈を判断するのに便利です。

Readline.line_buffer の長さは、GNU Readline の rl_end と同じです。

[EXCEPTION] NotImplementedError:

サポートしていない環境で発生します。

[SEE_ALSO] Readline.point

output=(output)Ruby 1.9.3 から[permalink][rdoc][edit]

readline メソッドで使用する出力用の File オブジェクト output を指定します。戻り値は指定した File オブジェクト output です。

[PARAM] output:

File オブジェクトを指定します。

point=(pos)Ruby 2.1.0 から[permalink][rdoc][edit]

point -> IntegerRuby 1.9.2 から

編集中の行における現在のカーソル位置のインデックスを設定・取得します。

Readline.point= は、カーソル位置のインデックスを pos に設定します。

Readline.point は、Readline.line_buffer における現在のカーソル位置のインデックスを返します。 completion_proc に渡される入力文字列の開始位置に対応する Readline.line_buffer 中のインデックスは、入力文字列の長さから Readline.point を引くことで求められます。

[PARAM] pos:

カーソル位置のインデックスを整数で指定します。

[EXCEPTION] NotImplementedError:

サポートしていない環境で発生します。

pre_input_hook=(proc)Ruby 2.0.0 から[permalink][rdoc][edit]

pre_input_hook -> Proc | nil

最初のプロンプトが表示された後、readline が入力文字の読み取りを開始する直前に呼び出す Proc オブジェクト proc を指定・取得します。

Readline.pre_input_hook= は、呼び出す Proc オブジェクト proc を指定します。詳細は GNU Readline の rl_pre_input_hook 変数を参照してください。

Readline.pre_input_hook は、指定されている Proc オブジェクトを返します。デフォルトは nil です。

[PARAM] proc:

呼び出す Proc オブジェクトを指定します。

[EXCEPTION] ArgumentError:

proc が call メソッドを持たない場合に発生します。

[EXCEPTION] NotImplementedError:

サポートしていない環境で発生します。

quoting_detection_proc=(proc)Ruby 2.5.0 から Ruby 3.3 で削除[permalink][rdoc][edit]

quoting_detection_proc -> Proc

ユーザの入力中の文字がエスケープされているかどうかを判定する Proc オブジェクト proc を指定・取得します。

Readline.quoting_detection_proc= は、判定用の Proc オブジェクト proc を指定します。 proc は、ユーザの入力文字列と、判定対象の文字のインデックスを引数として受け取り、その文字がエスケープされていれば真を返すことを想定しています。

Readline は、Readline.completer_quote_characters= で指定した文字(クオートされた引数の終わりを判定するため)や、Readline.completer_word_break_characters= で指定した文字(引数の区切りを判定するため)に対してのみ、この proc を呼び出します。

Readline.completer_quote_characters= が設定されていない場合、またはユーザの入力に completer_quote_characters に含まれる文字や \ 文字が含まれない場合、Readline はこの proc を一切使用しません。

Readline.quoting_detection_proc は、指定されている Proc オブジェクトを返します。

[PARAM] proc:

判定を行う Proc オブジェクトを指定します。

[EXCEPTION] ArgumentError:

proc が call メソッドを持たない場合に発生します。

[EXCEPTION] NotImplementedError:

サポートしていない環境で発生します。libedit(Edit Line)を使ったビルドではこのメソッドを利用できないため発生します。

redisplay -> selfRuby 2.0.0 から[permalink][rdoc][edit]

画面の表示を、現在の入力内容を反映した状態に更新します。

[EXCEPTION] NotImplementedError:

サポートしていない環境で発生します。

[SEE_ALSO] GNU Readline ライブラリの rl_redisplay 関数

refresh_line -> nilRuby 1.9.2 から Ruby 3.3 で削除[permalink][rdoc][edit]

現在の入力行をクリアします。

[EXCEPTION] NotImplementedError:

サポートしていない環境で発生します。libedit(Edit Line)を使ったビルドではこのメソッドを利用できないため発生します。

[SEE_ALSO] GNU Readline ライブラリの rl_refresh_line 関数

set_screen_size(rows, columns) -> ReadlineRuby 1.9.3 から[permalink][rdoc][edit]

端末のサイズを引数 row、columns に設定します。

[PARAM] rows:

行数を整数で指定します。

[PARAM] columns:

列数を整数で指定します。

[EXCEPTION] NotImplementedError:

サポートしていない環境で発生します。

[SEE_ALSO] GNU Readline ライブラリの rl_set_screen_size 関数

special_prefixes=(string)Ruby 2.0.0 から[permalink][rdoc][edit]

special_prefixes -> String

単語の区切り文字ではあるものの、補完関数に渡すテキストにはそのまま残しておく文字を指定・取得します。プログラムはこれを使って、どのような補完を行うかを判断できます。例えば、 Bash はシェル変数やホスト名を補完できるように、この値を "$@" に設定しています。

[PARAM] string:

文字列を指定します。

[EXCEPTION] NotImplementedError:

サポートしていない環境で発生します。

[SEE_ALSO] GNU Readline ライブラリの rl_special_prefixes 変数

vi_editing_mode -> nil[permalink][rdoc][edit]

編集モードを vi モードにします。 vi モードの詳細は、GNU Readline のマニュアルを参照してください。

• http://www.gnu.org/directory/readline.html

[EXCEPTION] NotImplementedError:

サポートしていない環境で発生します。libedit(Edit Line)を使ったビルドではこのメソッドを利用できないため発生します。

vi_editing_mode? -> boolRuby 1.9.1 から[permalink][rdoc][edit]

vi モードが有効であれば true を返します。そうでなければ false を返します。

[EXCEPTION] NotImplementedError:

サポートしていない環境で発生します。libedit(Edit Line)を使ったビルドではこのメソッドを利用できないため発生します。

[SEE_ALSO] Readline.vi_editing_mode

モジュール関数

readline(prompt = "", add_hist = false) -> String | nil[permalink][rdoc][edit]

prompt を出力し、ユーザからのキー入力を待ちます。エンターキーの押下などでユーザが文字列を入力し終えると、入力した文字列を返します。このとき、add_hist が true であれば、入力した文字列を入力履歴に追加します。何も入力していない状態で EOF(UNIX では ^D) を入力するなどで、ユーザからの入力がない場合は nil を返します。

本メソッドはスレッドに対応しています。入力待ち状態のときはスレッドコンテキストの切替えが発生します。

入力時には行内編集が可能で、vi モードと Emacs モードが用意されています。デフォルトは Emacs モードです。

[PARAM] prompt:

カーソルの前に表示する文字列を指定します。デフォルトは""です。

[PARAM] add_hist:

真ならば、入力した文字列をヒストリに記録します。デフォルトは偽です。

[EXCEPTION] IOError:

標準入力が tty でない、かつ、標準入力をクローズしている (isatty(2) の errno が EBADF である。) 場合に発生します。

例:

require "readline"

input = Readline.readline
(プロンプトなどは表示せずに、入力待ちの状態になります。
 ここでは「abc」を入力後、エンターキーを押したと想定します。)
abc

p input # => "abc"

input = Readline.readline("> ")
(">"を表示し、入力待ちの状態になります。
 ここでは「ls」を入力後、エンターキーを押したと想定します。)
> ls

p input # => "ls"

input = Readline.readline("> ", true)
(">"を表示し、入力待ちの状態になります。
 ここでは「cd」を入力後、エンターキーを押したと想定します。)
> cd

p input # => "cd"

input = Readline.readline("> ", true)
(">"を表示し、入力待ちの状態になります。
 ここで、カーソルの上キー、または ^P を押すと、
 先ほど入力した「cd」が表示されます。
 そして、エンターキーを押したと想定します。)
> cd

p input # => "cd"

本メソッドには注意事項があります。入力待ちの状態で ^C すると ruby インタプリタが終了し、端末状態を復帰しません。これを回避するための例を2つ挙げます。

例: ^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

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

[SEE_ALSO] Readline.vi_editing_mode、Readline.emacs_editing_mode、 Readline::HISTORY

定数

FILENAME_COMPLETION_PROC -> Proc[permalink][rdoc][edit]

GNU Readline で定義されている関数を使用してファイル名の補完を行うための Proc オブジェクトです。 Readline.completion_proc= で使用します。

[SEE_ALSO] Readline.completion_proc=

USERNAME_COMPLETION_PROC -> Proc[permalink][rdoc][edit]

GNU Readline で定義されている関数を使用してユーザ名の補完を行うための Proc オブジェクトです。 Readline.completion_proc= で使用します。

[SEE_ALSO] Readline.completion_proc=

VERSION -> String[permalink][rdoc][edit]

Readlineモジュールが使用している GNU Readline や libedit のバージョンを示す文字列です。