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