1GNU Readline によるコマンドライン入力インタフェースを提供するモジュール
2です。GNU Readline の互換ライブラリのひとつである Edit Line(libedit) も
3サポートしています。
4
5GNU Readline:: http://www.gnu.org/directory/readline.html
6libedit::      http://www.thrysoee.dk/editline/
7
8Readline.readline を使用してユーザからの入力を取得できます。このとき、
9GNU Readline のように入力の補完やEmacs のようなキー操作などができます。
10
11  require "readline"
12  while buf = Readline.readline("> ", true)
13    p buf
14  end
15
16ユーザが入力した内容を履歴(以下、ヒストリ)として記録することができます。
17定数 Readline::HISTORY を使用してヒストリにアクセスできます。
18
19  require "readline"
20  while buf = Readline.readline("> ", true)
21    p Readline::HISTORY.to_a
22    print("-> ", buf, "\n")
23  end
24
25使用するライブラリにより、いくつかのメソッドで例外 NotImplementedError
26が発生します。
27
28== Readline モジュール
29
30=== モジュール関数
31
32readline([prompt, [add_hist]]) -> String | nil
33
34  prompt を出力し、ユーザからのキー入力を待ちます。
35  エンターキーの押下などでユーザが文字列を入力し終えると、
36  入力した文字列を返します。
37  このとき、add_hist が true であれば、入力した文字列をヒストリに追加します。
38
39  何も入力していない状態で EOF(UNIX では ^D) を入力するなどで、
40  ユーザからの入力がない場合は nil を返します。
41
42  次の条件を全て満たす場合、例外 IOError が発生します。
43  1. 標準入力が tty でない。
44  2. 標準入力をクローズしている。(isatty(2) の errno が EBADF である。)
45
46  本メソッドはスレッドに対応しています。
47  入力待ち状態のときはスレッドコンテキストの切替えが発生します。
48
49  入力時には行内編集が可能で、vi モードと Emacs モードが用意されています。
50  デフォルトは Emacs モードです。
51
52  本メソッドには注意事項があります。
53  入力待ちの状態で ^C すると ruby インタプリタが終了し、端末状態を復帰しません。
54  これを回避するための例を3つ挙げます。
55
56  * ^CによるInterrupt例外を補足して、端末状態を復帰します:
57
58      require "readline"
59
60      stty_save = `stty -g`.chomp
61      begin
62        while buf = Readline.readline
63            p buf
64            end
65          rescue Interrupt
66            system("stty", stty_save)
67            exit
68          end
69        end
70      end
71
72  * INTシグナルを補足して、端末状態を復帰します:
73
74      require "readline"
75
76      stty_save = `stty -g`.chomp
77      trap("INT") { system "stty", stty_save; exit }
78
79      while buf = Readline.readline
80        p buf
81      end
82
83  * 単に ^C を無視する方法もあります:
84
85      require "readline"
86
87      trap("INT", "SIG_IGN")
88
89      while buf = Readline.readline
90        p buf
91      end
92
93  入力履歴 Readline::HISTORY を使用して、空行や直前の入力と同じ内容は入力
94  履歴に残さないということもできます。
95
96    require "readline"
97
98    while buf = Readline.readline("> ", true)
99      # p Readline::HISTORY.to_a
100      Readline::HISTORY.pop if /^\s*$/ =~ buf
101
102      begin
103        if Readline::HISTORY[Readline::HISTORY.length-2] == buf
104          Readline::HISTORY.pop
105        end
106      rescue IndexError
107      end
108
109      # p Readline::HISTORY.to_a
110      print "-> ", buf, "\n"
111    end
112
113=== クラスメソッド
114
115Readline.input = input
116
117  Readline.readline メソッドで使用する入力用の File オブジェクト input
118  を指定します。
119
120Readline.output = output
121
122  Readline.readline メソッドで使用する出力用の File オブジェクト
123  output を指定します。
124
125Readline.completion_proc = proc
126
127  ユーザからの入力を補完する時の候補を取得する Proc オブジェクト proc を
128  指定します。proc は、次のものを想定しています。
129  1. call メソッドを持ちます。
130     call メソッドを持たない場合、例外 ArgumentError が発生します。
131  2. 引数にユーザからの入力文字列(注1)を取ります。
132  3. 候補の文字列の配列を返します。
133
134  注1:「/var/lib /v」の後で補完を行うと、
135  デフォルトでは proc の引数に「/v」が渡されます。
136  このように、ユーザが入力した文字列を
137  Readline.completer_word_break_characters に含まれる文字で区切ったも
138  のを単語とすると、カーソルがある単語の最初の文字から現在のカーソル位
139  置までの文字列が proc の引数に渡されます。
140
141Readline.completion_proc -> proc
142
143  ユーザからの入力を補完する時の候補を取得する Proc オブジェクト proc
144  を取得します。
145
146Readline.completion_case_fold = bool
147
148  ユーザの入力を補完する際、大文字と小文字を区別する／しないを指定します。
149  bool が真ならば区別しません。bool が偽ならば区別します。
150
151Readline.completion_case_fold -> bool
152
153  ユーザの入力を補完する際、大文字と小文字を区別する／しないを取得します。
154  bool が真ならば区別しません。bool が偽ならば区別します。
155
156  なお、Readline.completion_case_fold= メソッドで指定したオブジェクトを
157  そのまま取得するので、次のような動作をします。
158
159    require "readline"
160
161    Readline.completion_case_fold = "This is a String."
162    p Readline.completion_case_fold # => "This is a String."
163
164Readline.line_buffer -> string
165
166  入力中の行全体を返します。complete_proc の中で使用することを想定し
167  ています。Readline.line_buffer の長さは GNU Readline の rl_end 変数の
168  値と一致します。
169
170Readline.point -> int
171
172  現在のカーソルの位置を返します。
173  Readline モジュールは補完対象の単語の開始位置の情報を提供していません。
174  しかしながら、 completion_proc の中で入力した単語 text と
175  Readline.point を使用することで開始位置を導くことができます。
176
177    開始位置 = 入力した単語の長さ - Readline.point
178
179Readline.vi_editing_mode -> nil
180
181  編集モードを vi モードにします。
182  vi モードの詳細は、GNU Readline のマニュアルを参照してください。
183
184  サポートしていない環境では、例外 NotImplementedError が発生します。
185
186Readline.vi_editing_mode? -> bool
187
188  編集モードが vi モードの場合、true を返します。そうでなければ false
189  を返します。
190
191  サポートしていない環境では、例外 NotImplementedError が発生します。
192
193Readline.emacs_editing_mode -> nil
194
195  編集モードを Emacs モードにします。
196  デフォルトは Emacs モードです。
197  Emacs モードの詳細は、GNU Readline のマニュアルを参照してください。
198
199  サポートしていない環境では、例外 NotImplementedError が発生します。
200
201Readline.emacs_editing_mode? -> bool
202
203  編集モードが Emacs モードの場合、true を返します。そうでなければ false
204  を返します。
205
206  サポートしていない環境では、例外 NotImplementedError が発生します。
207
208Readline.completion_append_character = char
209
210  ユーザの入力の補完が完了した場合に、最後に付加する文字 char を指定し
211  ます。半角スペース「" "」などの単語を区切る文字を指定すれば、連続して
212  入力する際に便利です。
213
214  使用例:
215
216    require "readline"
217
218    Readline.readline("> ", true)
219    Readline.completion_append_character = " "
220
221  実行例:
222
223    >
224    ここで "/var/li" を入力します。
225
226    > /var/li
227    ここで TAB キーを入力します。
228
229    > /var/lib
230    "b" が補完され、最後に " " が追加されるので、"/usr" を連続して入力できます。
231
232    > /var/lib /usr
233
234  なお、1文字しか指定することはできません。
235  例えば、"string"を指定した場合は最初の文字である"s"だけを使用します。
236
237    require "readline"
238
239    Readline.completion_append_character = "string"
240    p Readline.completion_append_character # => "s"
241
242  サポートしていない環境では、例外 NotImplementedError が発生します。
243
244Readline.completion_append_character -> char
245
246  ユーザの入力の補完が完了した場合に、最後に付加する文字を取得します。
247  デフォルトは空白 (" ") です。
248
249  サポートしていない環境では、例外 NotImplementedError が発生します。
250
251Readline.basic_word_break_characters = string
252
253  ユーザの入力の補完を行う際、単語の区切りを示す複数の文字で構成される
254  文字列 string を指定します。
255
256  GNU Readline のデフォルトの値は、Bash の補完処理で使用している文字列
257  " \t\n\"\\'`@$><=;|&{(" (スペースを含む) になっています。
258
259  サポートしていない環境では、例外 NotImplementedError が発生します。
260
261Readline.basic_word_break_characters -> string
262
263  ユーザの入力の補完を行う際、単語の区切りを示す複数の文字で構成される
264  文字列を取得します。
265
266  サポートしていない環境では、例外 NotImplementedError が発生します。
267
268Readline.completer_word_break_characters = string
269
270  ユーザの入力の補完を行う際、単語の区切りを示す複数の文字で構成される
271  文字列 string を指定します。
272  Readline.basic_word_break_characters= との違いは、
273  GNU Readline の rl_complete_internal 関数で使用されることです。
274
275  GNU Readline のデフォルトの値は、
276  Readline.basic_word_break_characters と同じです。
277
278  サポートしていない環境では、例外 NotImplementedError が発生します。
279
280Readline.completer_word_break_characters -> string
281
282  ユーザの入力の補完を行う際、単語の区切りを示す複数の文字で構成された
283  文字列を取得します。
284
285  サポートしていない環境では、例外 NotImplementedError が発生します。
286
287Readline.basic_quote_characters = string
288
289  スペースなどの単語の区切りをクオートするための複数の文字で構成される
290  文字列 string を指定します。
291
292  サポートしていない環境では、例外 NotImplementedError が発生します。
293
294Readline.basic_quote_characters -> string
295
296  スペースなどの単語の区切りをクオートするための複数の文字で構成される
297  文字列を取得します。
298
299  サポートしていない環境では、例外 NotImplementedError が発生します。
300
301Readline.completer_quote_characters = string
302
303  ユーザの入力の補完を行う際、スペースなどの単語の区切りを
304  クオートするための複数の文字で構成される文字列 string を指定します。
305  指定した文字の間では、Readline.completer_word_break_characters=
306  で指定した文字列に含まれる文字も、普通の文字列として扱われます。
307
308  サポートしていない環境では、例外 NotImplementedError が発生します。
309
310Readline.completer_quote_characters -> string
311
312  ユーザの入力の補完を行う際、スペースなどの単語の区切りを
313  クオートするための複数の文字で構成される文字列を取得します。
314
315  サポートしていない環境では、例外 NotImplementedError が発生します。
316
317Readline.filename_quote_characters = string
318
319  ユーザの入力時にファイル名の補完を行う際、スペースなどの単語の区切りを
320  クオートするための複数の文字で構成される文字列 string を指定します。
321
322  GNU Readline のデフォルト値は nil です。
323
324  サポートしていない環境では、例外 NotImplementedError が発生します。
325
326Readline.filename_quote_characters -> string
327
328  ユーザの入力時にファイル名の補完を行う際、スペースなどの単語の区切りを
329  クオートするための複数の文字で構成される文字列を取得します。
330
331  サポートしていない環境では、例外 NotImplementedError が発生します。
332
333=== クラス定数
334
335HISTORY
336
337  定数 HISTORY を使用してヒストリにアクセスできます。
338  Enumerable モジュールを extend しており、
339  配列のように振る舞うことができます。
340  例えば、HISTORY[4] により 5 番目に入力した内容を取り出すことができます。
341
342    require "readline"
343
344    Readline::HISTORY.push("a", "b", "c", "d", "e")
345    p Readline::HISTORY[4] # => "e"
346
347  実装しているメソッドを次に挙げます。
348  * HISTORY.to_s -> "HISTORY"
349  * HISTORY[index] -> string
350  * HISTORY[index] = string
351  * HISTORY.push(string[, string, ...]) -> self
352  * HISTORY << string -> self
353  * HISTORY.pop -> string
354  * HISTORY.shift -> string
355  * HISTORY.each -> Enumerator
356  * HISTORY.each { |i| } -> [string]
357  * HISTORY.length -> Integer
358  * HISTORY.empty? -> true or false
359  * HISTORY.delete_at(index) -> string
360  * HISTORY.clear -> self
361
362  サポートしていない環境では、次のメソッドで例外 NotImplementedError が
363  発生します。
364  * HISTORY[index] = string
365  * HISTORY.pop -> string
366  * HISTORY.shift -> string
367  * HISTORY.delete_at(index) -> string
368  * HISTORY.clear -> self
369
370FILENAME_COMPLETION_PROC
371
372  ファイル名の補完を行う call メソッドを持つオブジェクトです。
373
374  Readline.completion_proc= により、ユーザの入力時にファイル名の補完を
375  行うように設定するために使用することを想定してます。
376
377USERNAME_COMPLETION_PROC
378
379  ユーザ名の補完を行う call メソッドを持つオブジェクトです。
380
381  Readline.completion_proc= により、ユーザの入力時にユーザ名の補完を行
382  うように設定するために使用することを想定してます。
383
384VERSION
385
386  使用している GNU Readline または libedit のバージョンです。
387