1: @comment %**start of header (This is for running Texinfo on a region.)
2: @setfilename rluser.info
3: @comment %**end of header (This is for running Texinfo on a region.)
4:
5: @ignore
6: This file documents the end user interface to the GNU command line
7: editing features. It is to be an appendix to manuals for programs which
8: use these features. There is a document entitled "readline.texinfo"
9: which contains both end-user and programmer documentation for the
10: GNU Readline Library.
11:
12: Copyright (C) 1988--2014 Free Software Foundation, Inc.
13:
14: Authored by Brian Fox and Chet Ramey.
15:
16: Permission is granted to process this file through Tex and print the
17: results, provided the printed document carries copying permission notice
18: identical to this one except for the removal of this paragraph (this
19: paragraph not being relevant to the printed manual).
20:
21: Permission is granted to make and distribute verbatim copies of this manual
22: provided the copyright notice and this permission notice are preserved on
23: all copies.
24:
25: Permission is granted to copy and distribute modified versions of this
26: manual under the conditions for verbatim copying, provided also that the
27: GNU Copyright statement is available to the distributee, and provided that
28: the entire resulting derived work is distributed under the terms of a
29: permission notice identical to this one.
30:
31: Permission is granted to copy and distribute translations of this manual
32: into another language, under the above conditions for modified versions.
33: @end ignore
34:
35: @comment If you are including this manual as an appendix, then set the
36: @comment variable readline-appendix.
37:
38: @ifclear BashFeatures
39: @defcodeindex bt
40: @end ifclear
41:
42: @node Command Line Editing
43: @chapter Command Line Editing
44:
45: This chapter describes the basic features of the @sc{gnu}
46: command line editing interface.
47: @ifset BashFeatures
48: Command line editing is provided by the Readline library, which is
49: used by several different programs, including Bash.
50: Command line editing is enabled by default when using an interactive shell,
51: unless the @option{--noediting} option is supplied at shell invocation.
52: Line editing is also used when using the @option{-e} option to the
53: @code{read} builtin command (@pxref{Bash Builtins}).
54: By default, the line editing commands are similar to those of Emacs.
55: A vi-style line editing interface is also available.
56: Line editing can be enabled at any time using the @option{-o emacs} or
57: @option{-o vi} options to the @code{set} builtin command
58: (@pxref{The Set Builtin}), or disabled using the @option{+o emacs} or
59: @option{+o vi} options to @code{set}.
60: @end ifset
61:
62: @menu
63: * Introduction and Notation:: Notation used in this text.
64: * Readline Interaction:: The minimum set of commands for editing a line.
65: * Readline Init File:: Customizing Readline from a user's view.
66: * Bindable Readline Commands:: A description of most of the Readline commands
67: available for binding
68: * Readline vi Mode:: A short description of how to make Readline
69: behave like the vi editor.
70: @ifset BashFeatures
71: * Programmable Completion:: How to specify the possible completions for
72: a specific command.
73: * Programmable Completion Builtins:: Builtin commands to specify how to
74: complete arguments for a particular command.
75: * A Programmable Completion Example:: An example shell function for
76: generating possible completions.
77: @end ifset
78: @end menu
79:
80: @node Introduction and Notation
81: @section Introduction to Line Editing
82:
83: The following paragraphs describe the notation used to represent
84: keystrokes.
85:
86: The text @kbd{C-k} is read as `Control-K' and describes the character
87: produced when the @key{k} key is pressed while the Control key
88: is depressed.
89:
90: The text @kbd{M-k} is read as `Meta-K' and describes the character
91: produced when the Meta key (if you have one) is depressed, and the @key{k}
92: key is pressed.
93: The Meta key is labeled @key{ALT} on many keyboards.
94: On keyboards with two keys labeled @key{ALT} (usually to either side of
95: the space bar), the @key{ALT} on the left side is generally set to
96: work as a Meta key.
97: The @key{ALT} key on the right may also be configured to work as a
98: Meta key or may be configured as some other modifier, such as a
99: Compose key for typing accented characters.
100:
101: If you do not have a Meta or @key{ALT} key, or another key working as
102: a Meta key, the identical keystroke can be generated by typing @key{ESC}
103: @emph{first}, and then typing @key{k}.
104: Either process is known as @dfn{metafying} the @key{k} key.
105:
106: The text @kbd{M-C-k} is read as `Meta-Control-k' and describes the
107: character produced by @dfn{metafying} @kbd{C-k}.
108:
109: In addition, several keys have their own names. Specifically,
110: @key{DEL}, @key{ESC}, @key{LFD}, @key{SPC}, @key{RET}, and @key{TAB} all
111: stand for themselves when seen in this text, or in an init file
112: (@pxref{Readline Init File}).
113: If your keyboard lacks a @key{LFD} key, typing @key{C-j} will
114: produce the desired character.
115: The @key{RET} key may be labeled @key{Return} or @key{Enter} on
116: some keyboards.
117:
118: @node Readline Interaction
119: @section Readline Interaction
120: @cindex interaction, readline
121:
122: Often during an interactive session you type in a long line of text,
123: only to notice that the first word on the line is misspelled. The
124: Readline library gives you a set of commands for manipulating the text
125: as you type it in, allowing you to just fix your typo, and not forcing
126: you to retype the majority of the line. Using these editing commands,
127: you move the cursor to the place that needs correction, and delete or
128: insert the text of the corrections. Then, when you are satisfied with
129: the line, you simply press @key{RET}. You do not have to be at the
130: end of the line to press @key{RET}; the entire line is accepted
131: regardless of the location of the cursor within the line.
132:
133: @menu
134: * Readline Bare Essentials:: The least you need to know about Readline.
135: * Readline Movement Commands:: Moving about the input line.
136: * Readline Killing Commands:: How to delete text, and how to get it back!
137: * Readline Arguments:: Giving numeric arguments to commands.
138: * Searching:: Searching through previous lines.
139: @end menu
140:
141: @node Readline Bare Essentials
142: @subsection Readline Bare Essentials
143: @cindex notation, readline
144: @cindex command editing
145: @cindex editing command lines
146:
147: In order to enter characters into the line, simply type them. The typed
148: character appears where the cursor was, and then the cursor moves one
149: space to the right. If you mistype a character, you can use your
150: erase character to back up and delete the mistyped character.
151:
152: Sometimes you may mistype a character, and
153: not notice the error until you have typed several other characters. In
154: that case, you can type @kbd{C-b} to move the cursor to the left, and then
155: correct your mistake. Afterwards, you can move the cursor to the right
156: with @kbd{C-f}.
157:
158: When you add text in the middle of a line, you will notice that characters
159: to the right of the cursor are `pushed over' to make room for the text
160: that you have inserted. Likewise, when you delete text behind the cursor,
161: characters to the right of the cursor are `pulled back' to fill in the
162: blank space created by the removal of the text. A list of the bare
163: essentials for editing the text of an input line follows.
164:
165: @table @asis
166: @item @kbd{C-b}
167: Move back one character.
168: @item @kbd{C-f}
169: Move forward one character.
170: @item @key{DEL} or @key{Backspace}
171: Delete the character to the left of the cursor.
172: @item @kbd{C-d}
173: Delete the character underneath the cursor.
174: @item @w{Printing characters}
175: Insert the character into the line at the cursor.
176: @item @kbd{C-_} or @kbd{C-x C-u}
177: Undo the last editing command. You can undo all the way back to an
178: empty line.
179: @end table
180:
181: @noindent
182: (Depending on your configuration, the @key{Backspace} key be set to
183: delete the character to the left of the cursor and the @key{DEL} key set
184: to delete the character underneath the cursor, like @kbd{C-d}, rather
185: than the character to the left of the cursor.)
186:
187: @node Readline Movement Commands
188: @subsection Readline Movement Commands
189:
190:
191: The above table describes the most basic keystrokes that you need
192: in order to do editing of the input line. For your convenience, many
193: other commands have been added in addition to @kbd{C-b}, @kbd{C-f},
194: @kbd{C-d}, and @key{DEL}. Here are some commands for moving more rapidly
195: about the line.
196:
197: @table @kbd
198: @item C-a
199: Move to the start of the line.
200: @item C-e
201: Move to the end of the line.
202: @item M-f
203: Move forward a word, where a word is composed of letters and digits.
204: @item M-b
205: Move backward a word.
206: @item C-l
207: Clear the screen, reprinting the current line at the top.
208: @end table
209:
210: Notice how @kbd{C-f} moves forward a character, while @kbd{M-f} moves
211: forward a word. It is a loose convention that control keystrokes
212: operate on characters while meta keystrokes operate on words.
213:
214: @node Readline Killing Commands
215: @subsection Readline Killing Commands
216:
217: @cindex killing text
218: @cindex yanking text
219:
220: @dfn{Killing} text means to delete the text from the line, but to save
221: it away for later use, usually by @dfn{yanking} (re-inserting)
222: it back into the line.
223: (`Cut' and `paste' are more recent jargon for `kill' and `yank'.)
224:
225: If the description for a command says that it `kills' text, then you can
226: be sure that you can get the text back in a different (or the same)
227: place later.
228:
229: When you use a kill command, the text is saved in a @dfn{kill-ring}.
230: Any number of consecutive kills save all of the killed text together, so
231: that when you yank it back, you get it all. The kill
232: ring is not line specific; the text that you killed on a previously
233: typed line is available to be yanked back later, when you are typing
234: another line.
235: @cindex kill ring
236:
237: Here is the list of commands for killing text.
238:
239: @table @kbd
240: @item C-k
241: Kill the text from the current cursor position to the end of the line.
242:
243: @item M-d
244: Kill from the cursor to the end of the current word, or, if between
245: words, to the end of the next word.
246: Word boundaries are the same as those used by @kbd{M-f}.
247:
248: @item M-@key{DEL}
249: Kill from the cursor the start of the current word, or, if between
250: words, to the start of the previous word.
251: Word boundaries are the same as those used by @kbd{M-b}.
252:
253: @item C-w
254: Kill from the cursor to the previous whitespace. This is different than
255: @kbd{M-@key{DEL}} because the word boundaries differ.
256:
257: @end table
258:
259: Here is how to @dfn{yank} the text back into the line. Yanking
260: means to copy the most-recently-killed text from the kill buffer.
261:
262: @table @kbd
263: @item C-y
264: Yank the most recently killed text back into the buffer at the cursor.
265:
266: @item M-y
267: Rotate the kill-ring, and yank the new top. You can only do this if
268: the prior command is @kbd{C-y} or @kbd{M-y}.
269: @end table
270:
271: @node Readline Arguments
272: @subsection Readline Arguments
273:
274: You can pass numeric arguments to Readline commands. Sometimes the
275: argument acts as a repeat count, other times it is the @i{sign} of the
276: argument that is significant. If you pass a negative argument to a
277: command which normally acts in a forward direction, that command will
278: act in a backward direction. For example, to kill text back to the
279: start of the line, you might type @samp{M-- C-k}.
280:
281: The general way to pass numeric arguments to a command is to type meta
282: digits before the command. If the first `digit' typed is a minus
283: sign (@samp{-}), then the sign of the argument will be negative. Once
284: you have typed one meta digit to get the argument started, you can type
285: the remainder of the digits, and then the command. For example, to give
286: the @kbd{C-d} command an argument of 10, you could type @samp{M-1 0 C-d},
287: which will delete the next ten characters on the input line.
288:
289: @node Searching
290: @subsection Searching for Commands in the History
291:
292: Readline provides commands for searching through the command history
293: @ifset BashFeatures
294: (@pxref{Bash History Facilities})
295: @end ifset
296: for lines containing a specified string.
297: There are two search modes: @dfn{incremental} and @dfn{non-incremental}.
298:
299: Incremental searches begin before the user has finished typing the
300: search string.
301: As each character of the search string is typed, Readline displays
302: the next entry from the history matching the string typed so far.
303: An incremental search requires only as many characters as needed to
304: find the desired history entry.
305: To search backward in the history for a particular string, type
306: @kbd{C-r}. Typing @kbd{C-s} searches forward through the history.
307: The characters present in the value of the @code{isearch-terminators} variable
308: are used to terminate an incremental search.
309: If that variable has not been assigned a value, the @key{ESC} and
310: @kbd{C-J} characters will terminate an incremental search.
311: @kbd{C-g} will abort an incremental search and restore the original line.
312: When the search is terminated, the history entry containing the
313: search string becomes the current line.
314:
315: To find other matching entries in the history list, type @kbd{C-r} or
316: @kbd{C-s} as appropriate.
317: This will search backward or forward in the history for the next
318: entry matching the search string typed so far.
319: Any other key sequence bound to a Readline command will terminate
320: the search and execute that command.
321: For instance, a @key{RET} will terminate the search and accept
322: the line, thereby executing the command from the history list.
323: A movement command will terminate the search, make the last line found
324: the current line, and begin editing.
325:
326: Readline remembers the last incremental search string. If two
327: @kbd{C-r}s are typed without any intervening characters defining a new
328: search string, any remembered search string is used.
329:
330: Non-incremental searches read the entire search string before starting
331: to search for matching history lines. The search string may be
332: typed by the user or be part of the contents of the current line.
333:
334: @node Readline Init File
335: @section Readline Init File
336: @cindex initialization file, readline
337:
338: Although the Readline library comes with a set of Emacs-like
339: keybindings installed by default, it is possible to use a different set
340: of keybindings.
341: Any user can customize programs that use Readline by putting
342: commands in an @dfn{inputrc} file, conventionally in his home directory.
343: The name of this
344: @ifset BashFeatures
345: file is taken from the value of the shell variable @env{INPUTRC}. If
346: @end ifset
347: @ifclear BashFeatures
348: file is taken from the value of the environment variable @env{INPUTRC}. If
349: @end ifclear
350: that variable is unset, the default is @file{~/.inputrc}. If that
351: file does not exist or cannot be read, the ultimate default is
352: @file{/etc/inputrc}.
353:
354: When a program which uses the Readline library starts up, the
355: init file is read, and the key bindings are set.
356:
357: In addition, the @code{C-x C-r} command re-reads this init file, thus
358: incorporating any changes that you might have made to it.
359:
360: @menu
361: * Readline Init File Syntax:: Syntax for the commands in the inputrc file.
362:
363: * Conditional Init Constructs:: Conditional key bindings in the inputrc file.
364:
365: * Sample Init File:: An example inputrc file.
366: @end menu
367:
368: @node Readline Init File Syntax
369: @subsection Readline Init File Syntax
370:
371: There are only a few basic constructs allowed in the
372: Readline init file. Blank lines are ignored.
373: Lines beginning with a @samp{#} are comments.
374: Lines beginning with a @samp{$} indicate conditional
375: constructs (@pxref{Conditional Init Constructs}). Other lines
376: denote variable settings and key bindings.
377:
378: @table @asis
379: @item Variable Settings
380: You can modify the run-time behavior of Readline by
381: altering the values of variables in Readline
382: using the @code{set} command within the init file.
383: The syntax is simple:
384:
385: @example
386: set @var{variable} @var{value}
387: @end example
388:
389: @noindent
390: Here, for example, is how to
391: change from the default Emacs-like key binding to use
392: @code{vi} line editing commands:
393:
394: @example
395: set editing-mode vi
396: @end example
397:
398: Variable names and values, where appropriate, are recognized without regard
399: to case. Unrecognized variable names are ignored.
400:
401: Boolean variables (those that can be set to on or off) are set to on if
402: the value is null or empty, @var{on} (case-insensitive), or 1. Any other
403: value results in the variable being set to off.
404:
405: @ifset BashFeatures
406: The @w{@code{bind -V}} command lists the current Readline variable names
407: and values. @xref{Bash Builtins}.
408: @end ifset
409:
410: A great deal of run-time behavior is changeable with the following
411: variables.
412:
413: @cindex variables, readline
414: @table @code
415:
416: @item bell-style
417: @vindex bell-style
418: Controls what happens when Readline wants to ring the terminal bell.
419: If set to @samp{none}, Readline never rings the bell. If set to
420: @samp{visible}, Readline uses a visible bell if one is available.
421: If set to @samp{audible} (the default), Readline attempts to ring
422: the terminal's bell.
423:
424: @item bind-tty-special-chars
425: @vindex bind-tty-special-chars
426: If set to @samp{on}, Readline attempts to bind the control characters
427: treated specially by the kernel's terminal driver to their Readline
428: equivalents.
429:
430: @item colored-stats
431: @vindex colored-stats
432: If set to @samp{on}, Readline displays possible completions using different
433: colors to indicate their file type.
434: The color definitions are taken from the value of the @env{LS_COLORS}
435: environment variable.
436: The default is @samp{off}.
437:
438: @item comment-begin
439: @vindex comment-begin
440: The string to insert at the beginning of the line when the
441: @code{insert-comment} command is executed. The default value
442: is @code{"#"}.
443:
444: @item completion-display-width
445: @vindex completion-display-width
446: The number of screen columns used to display possible matches
447: when performing completion.
448: The value is ignored if it is less than 0 or greater than the terminal
449: screen width.
450: A value of 0 will cause matches to be displayed one per line.
451: The default value is -1.
452:
453: @item completion-ignore-case
454: @vindex completion-ignore-case
455: If set to @samp{on}, Readline performs filename matching and completion
456: in a case-insensitive fashion.
457: The default value is @samp{off}.
458:
459: @item completion-map-case
460: @vindex completion-map-case
461: If set to @samp{on}, and @var{completion-ignore-case} is enabled, Readline
462: treats hyphens (@samp{-}) and underscores (@samp{_}) as equivalent when
463: performing case-insensitive filename matching and completion.
464:
465: @item completion-prefix-display-length
466: @vindex completion-prefix-display-length
467: The length in characters of the common prefix of a list of possible
468: completions that is displayed without modification. When set to a
469: value greater than zero, common prefixes longer than this value are
470: replaced with an ellipsis when displaying possible completions.
471:
472: @item completion-query-items
473: @vindex completion-query-items
474: The number of possible completions that determines when the user is
475: asked whether the list of possibilities should be displayed.
476: If the number of possible completions is greater than this value,
477: Readline will ask the user whether or not he wishes to view
478: them; otherwise, they are simply listed.
479: This variable must be set to an integer value greater than or equal to 0.
480: A negative value means Readline should never ask.
481: The default limit is @code{100}.
482:
483: @item convert-meta
484: @vindex convert-meta
485: If set to @samp{on}, Readline will convert characters with the
486: eighth bit set to an @sc{ascii} key sequence by stripping the eighth
487: bit and prefixing an @key{ESC} character, converting them to a
488: meta-prefixed key sequence. The default value is @samp{on}.
489:
490: @item disable-completion
491: @vindex disable-completion
492: If set to @samp{On}, Readline will inhibit word completion.
493: Completion characters will be inserted into the line as if they had
494: been mapped to @code{self-insert}. The default is @samp{off}.
495:
496: @item editing-mode
497: @vindex editing-mode
498: The @code{editing-mode} variable controls which default set of
499: key bindings is used. By default, Readline starts up in Emacs editing
500: mode, where the keystrokes are most similar to Emacs. This variable can be
501: set to either @samp{emacs} or @samp{vi}.
502:
503: @item echo-control-characters
504: When set to @samp{on}, on operating systems that indicate they support it,
505: readline echoes a character corresponding to a signal generated from the
506: keyboard. The default is @samp{on}.
507:
508: @item enable-keypad
509: @vindex enable-keypad
510: When set to @samp{on}, Readline will try to enable the application
511: keypad when it is called. Some systems need this to enable the
512: arrow keys. The default is @samp{off}.
513:
514: @item enable-meta-key
515: When set to @samp{on}, Readline will try to enable any meta modifier
516: key the terminal claims to support when it is called. On many terminals,
517: the meta key is used to send eight-bit characters.
518: The default is @samp{on}.
519:
520: @item expand-tilde
521: @vindex expand-tilde
522: If set to @samp{on}, tilde expansion is performed when Readline
523: attempts word completion. The default is @samp{off}.
524:
525: @item history-preserve-point
526: @vindex history-preserve-point
527: If set to @samp{on}, the history code attempts to place the point (the
528: current cursor position) at the
529: same location on each history line retrieved with @code{previous-history}
530: or @code{next-history}. The default is @samp{off}.
531:
532: @item history-size
533: @vindex history-size
534: Set the maximum number of history entries saved in the history list.
535: If set to zero, any existing history entries are deleted and no new entries
536: are saved.
537: If set to a value less than zero, the number of history entries is not
538: limited.
539: By default, the number of history entries is not limited.
540:
541: @item horizontal-scroll-mode
542: @vindex horizontal-scroll-mode
543: This variable can be set to either @samp{on} or @samp{off}. Setting it
544: to @samp{on} means that the text of the lines being edited will scroll
545: horizontally on a single screen line when they are longer than the width
546: of the screen, instead of wrapping onto a new screen line. By default,
547: this variable is set to @samp{off}.
548:
549: @item input-meta
550: @vindex input-meta
551: @vindex meta-flag
552: If set to @samp{on}, Readline will enable eight-bit input (it
553: will not clear the eighth bit in the characters it reads),
554: regardless of what the terminal claims it can support. The
555: default value is @samp{off}. The name @code{meta-flag} is a
556: synonym for this variable.
557:
558: @item isearch-terminators
559: @vindex isearch-terminators
560: The string of characters that should terminate an incremental search without
561: subsequently executing the character as a command (@pxref{Searching}).
562: If this variable has not been given a value, the characters @key{ESC} and
563: @kbd{C-J} will terminate an incremental search.
564:
565: @item keymap
566: @vindex keymap
567: Sets Readline's idea of the current keymap for key binding commands.
568: Acceptable @code{keymap} names are
569: @code{emacs},
570: @code{emacs-standard},
571: @code{emacs-meta},
572: @code{emacs-ctlx},
573: @code{vi},
574: @code{vi-move},
575: @code{vi-command}, and
576: @code{vi-insert}.
577: @code{vi} is equivalent to @code{vi-command}; @code{emacs} is
578: equivalent to @code{emacs-standard}. The default value is @code{emacs}.
579: The value of the @code{editing-mode} variable also affects the
580: default keymap.
581:
582: @item keyseq-timeout
583: Specifies the duration Readline will wait for a character when reading an
584: ambiguous key sequence (one that can form a complete key sequence using
585: the input read so far, or can take additional input to complete a longer
586: key sequence).
587: If no input is received within the timeout, Readline will use the shorter
588: but complete key sequence.
589: Readline uses this value to determine whether or not input is
590: available on the current input source (@code{rl_instream} by default).
591: The value is specified in milliseconds, so a value of 1000 means that
592: Readline will wait one second for additional input.
593: If this variable is set to a value less than or equal to zero, or to a
594: non-numeric value, Readline will wait until another key is pressed to
595: decide which key sequence to complete.
596: The default value is @code{500}.
597:
598: @item mark-directories
599: If set to @samp{on}, completed directory names have a slash
600: appended. The default is @samp{on}.
601:
602: @item mark-modified-lines
603: @vindex mark-modified-lines
604: This variable, when set to @samp{on}, causes Readline to display an
605: asterisk (@samp{*}) at the start of history lines which have been modified.
606: This variable is @samp{off} by default.
607:
608: @item mark-symlinked-directories
609: @vindex mark-symlinked-directories
610: If set to @samp{on}, completed names which are symbolic links
611: to directories have a slash appended (subject to the value of
612: @code{mark-directories}).
613: The default is @samp{off}.
614:
615: @item match-hidden-files
616: @vindex match-hidden-files
617: This variable, when set to @samp{on}, causes Readline to match files whose
618: names begin with a @samp{.} (hidden files) when performing filename
619: completion.
620: If set to @samp{off}, the leading @samp{.} must be
621: supplied by the user in the filename to be completed.
622: This variable is @samp{on} by default.
623:
624: @item menu-complete-display-prefix
625: @vindex menu-complete-display-prefix
626: If set to @samp{on}, menu completion displays the common prefix of the
627: list of possible completions (which may be empty) before cycling through
628: the list. The default is @samp{off}.
629:
630: @item output-meta
631: @vindex output-meta
632: If set to @samp{on}, Readline will display characters with the
633: eighth bit set directly rather than as a meta-prefixed escape
634: sequence. The default is @samp{off}.
635:
636: @item page-completions
637: @vindex page-completions
638: If set to @samp{on}, Readline uses an internal @code{more}-like pager
639: to display a screenful of possible completions at a time.
640: This variable is @samp{on} by default.
641:
642: @item print-completions-horizontally
643: If set to @samp{on}, Readline will display completions with matches
644: sorted horizontally in alphabetical order, rather than down the screen.
645: The default is @samp{off}.
646:
647: @item revert-all-at-newline
648: @vindex revert-all-at-newline
649: If set to @samp{on}, Readline will undo all changes to history lines
650: before returning when @code{accept-line} is executed. By default,
651: history lines may be modified and retain individual undo lists across
652: calls to @code{readline}. The default is @samp{off}.
653:
654: @item show-all-if-ambiguous
655: @vindex show-all-if-ambiguous
656: This alters the default behavior of the completion functions. If
657: set to @samp{on},
658: words which have more than one possible completion cause the
659: matches to be listed immediately instead of ringing the bell.
660: The default value is @samp{off}.
661:
662: @item show-all-if-unmodified
663: @vindex show-all-if-unmodified
664: This alters the default behavior of the completion functions in
665: a fashion similar to @var{show-all-if-ambiguous}.
666: If set to @samp{on},
667: words which have more than one possible completion without any
668: possible partial completion (the possible completions don't share
669: a common prefix) cause the matches to be listed immediately instead
670: of ringing the bell.
671: The default value is @samp{off}.
672:
673: @item show-mode-in-prompt
674: @vindex show-mode-in-prompt
675: If set to @samp{on}, add a character to the beginning of the prompt
676: indicating the editing mode: emacs (@samp{@@}), vi command (@samp{:}),
677: or vi insertion (@samp{+}).
678: The default value is @samp{off}.
679:
680: @item skip-completed-text
681: @vindex skip-completed-text
682: If set to @samp{on}, this alters the default completion behavior when
683: inserting a single match into the line. It's only active when
684: performing completion in the middle of a word. If enabled, readline
685: does not insert characters from the completion that match characters
686: after point in the word being completed, so portions of the word
687: following the cursor are not duplicated.
688: For instance, if this is enabled, attempting completion when the cursor
689: is after the @samp{e} in @samp{Makefile} will result in @samp{Makefile}
690: rather than @samp{Makefilefile}, assuming there is a single possible
691: completion.
692: The default value is @samp{off}.
693:
694: @item visible-stats
695: @vindex visible-stats
696: If set to @samp{on}, a character denoting a file's type
697: is appended to the filename when listing possible
698: completions. The default is @samp{off}.
699:
700: @end table
701:
702: @item Key Bindings
703: The syntax for controlling key bindings in the init file is
704: simple. First you need to find the name of the command that you
705: want to change. The following sections contain tables of the command
706: name, the default keybinding, if any, and a short description of what
707: the command does.
708:
709: Once you know the name of the command, simply place on a line
710: in the init file the name of the key
711: you wish to bind the command to, a colon, and then the name of the
712: command.
713: There can be no space between the key name and the colon -- that will be
714: interpreted as part of the key name.
715: The name of the key can be expressed in different ways, depending on
716: what you find most comfortable.
717:
718: In addition to command names, readline allows keys to be bound
719: to a string that is inserted when the key is pressed (a @var{macro}).
720:
721: @ifset BashFeatures
722: The @w{@code{bind -p}} command displays Readline function names and
723: bindings in a format that can put directly into an initialization file.
724: @xref{Bash Builtins}.
725: @end ifset
726:
727: @table @asis
728: @item @w{@var{keyname}: @var{function-name} or @var{macro}}
729: @var{keyname} is the name of a key spelled out in English. For example:
730: @example
731: Control-u: universal-argument
732: Meta-Rubout: backward-kill-word
733: Control-o: "> output"
734: @end example
735:
736: In the above example, @kbd{C-u} is bound to the function
737: @code{universal-argument},
738: @kbd{M-DEL} is bound to the function @code{backward-kill-word}, and
739: @kbd{C-o} is bound to run the macro
740: expressed on the right hand side (that is, to insert the text
741: @samp{> output} into the line).
742:
743: A number of symbolic character names are recognized while
744: processing this key binding syntax:
745: @var{DEL},
746: @var{ESC},
747: @var{ESCAPE},
748: @var{LFD},
749: @var{NEWLINE},
750: @var{RET},
751: @var{RETURN},
752: @var{RUBOUT},
753: @var{SPACE},
754: @var{SPC},
755: and
756: @var{TAB}.
757:
758: @item @w{"@var{keyseq}": @var{function-name} or @var{macro}}
759: @var{keyseq} differs from @var{keyname} above in that strings
760: denoting an entire key sequence can be specified, by placing
761: the key sequence in double quotes. Some @sc{gnu} Emacs style key
762: escapes can be used, as in the following example, but the
763: special character names are not recognized.
764:
765: @example
766: "\C-u": universal-argument
767: "\C-x\C-r": re-read-init-file
768: "\e[11~": "Function Key 1"
769: @end example
770:
771: In the above example, @kbd{C-u} is again bound to the function
772: @code{universal-argument} (just as it was in the first example),
773: @samp{@kbd{C-x} @kbd{C-r}} is bound to the function @code{re-read-init-file},
774: and @samp{@key{ESC} @key{[} @key{1} @key{1} @key{~}} is bound to insert
775: the text @samp{Function Key 1}.
776:
777: @end table
778:
779: The following @sc{gnu} Emacs style escape sequences are available when
780: specifying key sequences:
781:
782: @table @code
783: @item @kbd{\C-}
784: control prefix
785: @item @kbd{\M-}
786: meta prefix
787: @item @kbd{\e}
788: an escape character
789: @item @kbd{\\}
790: backslash
791: @item @kbd{\"}
792: @key{"}, a double quotation mark
793: @item @kbd{\'}
794: @key{'}, a single quote or apostrophe
795: @end table
796:
797: In addition to the @sc{gnu} Emacs style escape sequences, a second
798: set of backslash escapes is available:
799:
800: @table @code
801: @item \a
802: alert (bell)
803: @item \b
804: backspace
805: @item \d
806: delete
807: @item \f
808: form feed
809: @item \n
810: newline
811: @item \r
812: carriage return
813: @item \t
814: horizontal tab
815: @item \v
816: vertical tab
817: @item \@var{nnn}
818: the eight-bit character whose value is the octal value @var{nnn}
819: (one to three digits)
820: @item \x@var{HH}
821: the eight-bit character whose value is the hexadecimal value @var{HH}
822: (one or two hex digits)
823: @end table
824:
825: When entering the text of a macro, single or double quotes must
826: be used to indicate a macro definition.
827: Unquoted text is assumed to be a function name.
828: In the macro body, the backslash escapes described above are expanded.
829: Backslash will quote any other character in the macro text,
830: including @samp{"} and @samp{'}.
831: For example, the following binding will make @samp{@kbd{C-x} \}
832: insert a single @samp{\} into the line:
833: @example
834: "\C-x\\": "\\"
835: @end example
836:
837: @end table
838:
839: @node Conditional Init Constructs
840: @subsection Conditional Init Constructs
841:
842: Readline implements a facility similar in spirit to the conditional
843: compilation features of the C preprocessor which allows key
844: bindings and variable settings to be performed as the result
845: of tests. There are four parser directives used.
846:
847: @table @code
848: @item $if
849: The @code{$if} construct allows bindings to be made based on the
850: editing mode, the terminal being used, or the application using
851: Readline. The text of the test extends to the end of the line;
852: no characters are required to isolate it.
853:
854: @table @code
855: @item mode
856: The @code{mode=} form of the @code{$if} directive is used to test
857: whether Readline is in @code{emacs} or @code{vi} mode.
858: This may be used in conjunction
859: with the @samp{set keymap} command, for instance, to set bindings in
860: the @code{emacs-standard} and @code{emacs-ctlx} keymaps only if
861: Readline is starting out in @code{emacs} mode.
862:
863: @item term
864: The @code{term=} form may be used to include terminal-specific
865: key bindings, perhaps to bind the key sequences output by the
866: terminal's function keys. The word on the right side of the
867: @samp{=} is tested against both the full name of the terminal and
868: the portion of the terminal name before the first @samp{-}. This
869: allows @code{sun} to match both @code{sun} and @code{sun-cmd},
870: for instance.
871:
872: @item application
873: The @var{application} construct is used to include
874: application-specific settings. Each program using the Readline
875: library sets the @var{application name}, and you can test for
876: a particular value.
877: This could be used to bind key sequences to functions useful for
878: a specific program. For instance, the following command adds a
879: key sequence that quotes the current or previous word in Bash:
880: @example
881: $if Bash
882: # Quote the current or previous word
883: "\C-xq": "\eb\"\ef\""
884: $endif
885: @end example
886: @end table
887:
888: @item $endif
889: This command, as seen in the previous example, terminates an
890: @code{$if} command.
891:
892: @item $else
893: Commands in this branch of the @code{$if} directive are executed if
894: the test fails.
895:
896: @item $include
897: This directive takes a single filename as an argument and reads commands
898: and bindings from that file.
899: For example, the following directive reads from @file{/etc/inputrc}:
900: @example
901: $include /etc/inputrc
902: @end example
903: @end table
904:
905: @node Sample Init File
906: @subsection Sample Init File
907:
908: Here is an example of an @var{inputrc} file. This illustrates key
909: binding, variable assignment, and conditional syntax.
910:
911: @example
912: @page
913: # This file controls the behaviour of line input editing for
914: # programs that use the GNU Readline library. Existing
915: # programs include FTP, Bash, and GDB.
916: #
917: # You can re-read the inputrc file with C-x C-r.
918: # Lines beginning with '#' are comments.
919: #
920: # First, include any system-wide bindings and variable
921: # assignments from /etc/Inputrc
922: $include /etc/Inputrc
923:
924: #
925: # Set various bindings for emacs mode.
926:
927: set editing-mode emacs
928:
929: $if mode=emacs
930:
931: Meta-Control-h: backward-kill-word Text after the function name is ignored
932:
933: #
934: # Arrow keys in keypad mode
935: #
936: #"\M-OD": backward-char
937: #"\M-OC": forward-char
938: #"\M-OA": previous-history
939: #"\M-OB": next-history
940: #
941: # Arrow keys in ANSI mode
942: #
943: "\M-[D": backward-char
944: "\M-[C": forward-char
945: "\M-[A": previous-history
946: "\M-[B": next-history
947: #
948: # Arrow keys in 8 bit keypad mode
949: #
950: #"\M-\C-OD": backward-char
951: #"\M-\C-OC": forward-char
952: #"\M-\C-OA": previous-history
953: #"\M-\C-OB": next-history
954: #
955: # Arrow keys in 8 bit ANSI mode
956: #
957: #"\M-\C-[D": backward-char
958: #"\M-\C-[C": forward-char
959: #"\M-\C-[A": previous-history
960: #"\M-\C-[B": next-history
961:
962: C-q: quoted-insert
963:
964: $endif
965:
966: # An old-style binding. This happens to be the default.
967: TAB: complete
968:
969: # Macros that are convenient for shell interaction
970: $if Bash
971: # edit the path
972: "\C-xp": "PATH=$@{PATH@}\e\C-e\C-a\ef\C-f"
973: # prepare to type a quoted word --
974: # insert open and close double quotes
975: # and move to just after the open quote
976: "\C-x\"": "\"\"\C-b"
977: # insert a backslash (testing backslash escapes
978: # in sequences and macros)
979: "\C-x\\": "\\"
980: # Quote the current or previous word
981: "\C-xq": "\eb\"\ef\""
982: # Add a binding to refresh the line, which is unbound
983: "\C-xr": redraw-current-line
984: # Edit variable on current line.
985: "\M-\C-v": "\C-a\C-k$\C-y\M-\C-e\C-a\C-y="
986: $endif
987:
988: # use a visible bell if one is available
989: set bell-style visible
990:
991: # don't strip characters to 7 bits when reading
992: set input-meta on
993:
994: # allow iso-latin1 characters to be inserted rather
995: # than converted to prefix-meta sequences
996: set convert-meta off
997:
998: # display characters with the eighth bit set directly
999: # rather than as meta-prefixed characters
1000: set output-meta on
1001:
1002: # if there are more than 150 possible completions for
1003: # a word, ask the user if he wants to see all of them
1004: set completion-query-items 150
1005:
1006: # For FTP
1007: $if Ftp
1008: "\C-xg": "get \M-?"
1009: "\C-xt": "put \M-?"
1010: "\M-.": yank-last-arg
1011: $endif
1012: @end example
1013:
1014: @node Bindable Readline Commands
1015: @section Bindable Readline Commands
1016:
1017: @menu
1018: * Commands For Moving:: Moving about the line.
1019: * Commands For History:: Getting at previous lines.
1020: * Commands For Text:: Commands for changing text.
1021: * Commands For Killing:: Commands for killing and yanking.
1022: * Numeric Arguments:: Specifying numeric arguments, repeat counts.
1023: * Commands For Completion:: Getting Readline to do the typing for you.
1024: * Keyboard Macros:: Saving and re-executing typed characters
1025: * Miscellaneous Commands:: Other miscellaneous commands.
1026: @end menu
1027:
1028: This section describes Readline commands that may be bound to key
1029: sequences.
1030: @ifset BashFeatures
1031: You can list your key bindings by executing
1032: @w{@code{bind -P}} or, for a more terse format, suitable for an
1033: @var{inputrc} file, @w{@code{bind -p}}. (@xref{Bash Builtins}.)
1034: @end ifset
1035: Command names without an accompanying key sequence are unbound by default.
1036:
1037: In the following descriptions, @dfn{point} refers to the current cursor
1038: position, and @dfn{mark} refers to a cursor position saved by the
1039: @code{set-mark} command.
1040: The text between the point and mark is referred to as the @dfn{region}.
1041:
1042: @node Commands For Moving
1043: @subsection Commands For Moving
1044: @ftable @code
1045: @item beginning-of-line (C-a)
1046: Move to the start of the current line.
1047:
1048: @item end-of-line (C-e)
1049: Move to the end of the line.
1050:
1051: @item forward-char (C-f)
1052: Move forward a character.
1053:
1054: @item backward-char (C-b)
1055: Move back a character.
1056:
1057: @item forward-word (M-f)
1058: Move forward to the end of the next word.
1059: Words are composed of letters and digits.
1060:
1061: @item backward-word (M-b)
1062: Move back to the start of the current or previous word.
1063: Words are composed of letters and digits.
1064:
1065: @ifset BashFeatures
1066: @item shell-forward-word ()
1067: Move forward to the end of the next word.
1068: Words are delimited by non-quoted shell metacharacters.
1069:
1070: @item shell-backward-word ()
1071: Move back to the start of the current or previous word.
1072: Words are delimited by non-quoted shell metacharacters.
1073: @end ifset
1074:
1075: @item clear-screen (C-l)
1076: Clear the screen and redraw the current line,
1077: leaving the current line at the top of the screen.
1078:
1079: @item redraw-current-line ()
1080: Refresh the current line. By default, this is unbound.
1081:
1082: @end ftable
1083:
1084: @node Commands For History
1085: @subsection Commands For Manipulating The History
1086:
1087: @ftable @code
1088: @item accept-line (Newline or Return)
1089: @ifset BashFeatures
1090: Accept the line regardless of where the cursor is.
1091: If this line is
1092: non-empty, add it to the history list according to the setting of
1093: the @env{HISTCONTROL} and @env{HISTIGNORE} variables.
1094: If this line is a modified history line, then restore the history line
1095: to its original state.
1096: @end ifset
1097: @ifclear BashFeatures
1098: Accept the line regardless of where the cursor is.
1099: If this line is
1100: non-empty, it may be added to the history list for future recall with
1101: @code{add_history()}.
1102: If this line is a modified history line, the history line is restored
1103: to its original state.
1104: @end ifclear
1105:
1106: @item previous-history (C-p)
1107: Move `back' through the history list, fetching the previous command.
1108:
1109: @item next-history (C-n)
1110: Move `forward' through the history list, fetching the next command.
1111:
1112: @item beginning-of-history (M-<)
1113: Move to the first line in the history.
1114:
1115: @item end-of-history (M->)
1116: Move to the end of the input history, i.e., the line currently
1117: being entered.
1118:
1119: @item reverse-search-history (C-r)
1120: Search backward starting at the current line and moving `up' through
1121: the history as necessary. This is an incremental search.
1122:
1123: @item forward-search-history (C-s)
1124: Search forward starting at the current line and moving `down' through
1125: the the history as necessary. This is an incremental search.
1126:
1127: @item non-incremental-reverse-search-history (M-p)
1128: Search backward starting at the current line and moving `up'
1129: through the history as necessary using a non-incremental search
1130: for a string supplied by the user.
1131:
1132: @item non-incremental-forward-search-history (M-n)
1133: Search forward starting at the current line and moving `down'
1134: through the the history as necessary using a non-incremental search
1135: for a string supplied by the user.
1136:
1137: @item history-search-forward ()
1138: Search forward through the history for the string of characters
1139: between the start of the current line and the point.
1140: The search string must match at the beginning of a history line.
1141: This is a non-incremental search.
1142: By default, this command is unbound.
1143:
1144: @item history-search-backward ()
1145: Search backward through the history for the string of characters
1146: between the start of the current line and the point.
1147: The search string must match at the beginning of a history line.
1148: This is a non-incremental search.
1149: By default, this command is unbound.
1150:
1151: @item history-substr-search-forward ()
1152: Search forward through the history for the string of characters
1153: between the start of the current line and the point.
1154: The search string may match anywhere in a history line.
1155: This is a non-incremental search.
1156: By default, this command is unbound.
1157:
1158: @item history-substr-search-backward ()
1159: Search backward through the history for the string of characters
1160: between the start of the current line and the point.
1161: The search string may match anywhere in a history line.
1162: This is a non-incremental search.
1163: By default, this command is unbound.
1164:
1165: @item yank-nth-arg (M-C-y)
1166: Insert the first argument to the previous command (usually
1167: the second word on the previous line) at point.
1168: With an argument @var{n},
1169: insert the @var{n}th word from the previous command (the words
1170: in the previous command begin with word 0). A negative argument
1171: inserts the @var{n}th word from the end of the previous command.
1172: Once the argument @var{n} is computed, the argument is extracted
1173: as if the @samp{!@var{n}} history expansion had been specified.
1174:
1175: @item yank-last-arg (M-. or M-_)
1176: Insert last argument to the previous command (the last word of the
1177: previous history entry).
1178: With a numeric argument, behave exactly like @code{yank-nth-arg}.
1179: Successive calls to @code{yank-last-arg} move back through the history
1180: list, inserting the last word (or the word specified by the argument to
1181: the first call) of each line in turn.
1182: Any numeric argument supplied to these successive calls determines
1183: the direction to move through the history. A negative argument switches
1184: the direction through the history (back or forward).
1185: The history expansion facilities are used to extract the last argument,
1186: as if the @samp{!$} history expansion had been specified.
1187:
1188: @end ftable
1189:
1190: @node Commands For Text
1191: @subsection Commands For Changing Text
1192:
1193: @ftable @code
1194:
1195: @item @i{end-of-file} (usually C-d)
1196: The character indicating end-of-file as set, for example, by
1197: @code{stty}. If this character is read when there are no characters
1198: on the line, and point is at the beginning of the line, Readline
1199: interprets it as the end of input and returns @sc{eof}.
1200:
1201: @item delete-char (C-d)
1202: Delete the character at point. If this function is bound to the
1203: same character as the tty @sc{eof} character, as @kbd{C-d}
1204: commonly is, see above for the effects.
1205:
1206: @item backward-delete-char (Rubout)
1207: Delete the character behind the cursor. A numeric argument means
1208: to kill the characters instead of deleting them.
1209:
1210: @item forward-backward-delete-char ()
1211: Delete the character under the cursor, unless the cursor is at the
1212: end of the line, in which case the character behind the cursor is
1213: deleted. By default, this is not bound to a key.
1214:
1215: @item quoted-insert (C-q or C-v)
1216: Add the next character typed to the line verbatim. This is
1217: how to insert key sequences like @kbd{C-q}, for example.
1218:
1219: @ifclear BashFeatures
1220: @item tab-insert (M-@key{TAB})
1221: Insert a tab character.
1222: @end ifclear
1223:
1224: @item self-insert (a, b, A, 1, !, @dots{})
1225: Insert yourself.
1226:
1227: @item transpose-chars (C-t)
1228: Drag the character before the cursor forward over
1229: the character at the cursor, moving the
1230: cursor forward as well. If the insertion point
1231: is at the end of the line, then this
1232: transposes the last two characters of the line.
1233: Negative arguments have no effect.
1234:
1235: @item transpose-words (M-t)
1236: Drag the word before point past the word after point,
1237: moving point past that word as well.
1238: If the insertion point is at the end of the line, this transposes
1239: the last two words on the line.
1240:
1241: @item upcase-word (M-u)
1242: Uppercase the current (or following) word. With a negative argument,
1243: uppercase the previous word, but do not move the cursor.
1244:
1245: @item downcase-word (M-l)
1246: Lowercase the current (or following) word. With a negative argument,
1247: lowercase the previous word, but do not move the cursor.
1248:
1249: @item capitalize-word (M-c)
1250: Capitalize the current (or following) word. With a negative argument,
1251: capitalize the previous word, but do not move the cursor.
1252:
1253: @item overwrite-mode ()
1254: Toggle overwrite mode. With an explicit positive numeric argument,
1255: switches to overwrite mode. With an explicit non-positive numeric
1256: argument, switches to insert mode. This command affects only
1257: @code{emacs} mode; @code{vi} mode does overwrite differently.
1258: Each call to @code{readline()} starts in insert mode.
1259:
1260: In overwrite mode, characters bound to @code{self-insert} replace
1261: the text at point rather than pushing the text to the right.
1262: Characters bound to @code{backward-delete-char} replace the character
1263: before point with a space.
1264:
1265: By default, this command is unbound.
1266:
1267: @end ftable
1268:
1269: @node Commands For Killing
1270: @subsection Killing And Yanking
1271:
1272: @ftable @code
1273:
1274: @item kill-line (C-k)
1275: Kill the text from point to the end of the line.
1276:
1277: @item backward-kill-line (C-x Rubout)
1278: Kill backward to the beginning of the line.
1279:
1280: @item unix-line-discard (C-u)
1281: Kill backward from the cursor to the beginning of the current line.
1282:
1283: @item kill-whole-line ()
1284: Kill all characters on the current line, no matter where point is.
1285: By default, this is unbound.
1286:
1287: @item kill-word (M-d)
1288: Kill from point to the end of the current word, or if between
1289: words, to the end of the next word.
1290: Word boundaries are the same as @code{forward-word}.
1291:
1292: @item backward-kill-word (M-@key{DEL})
1293: Kill the word behind point.
1294: Word boundaries are the same as @code{backward-word}.
1295:
1296: @ifset BashFeatures
1297: @item shell-kill-word ()
1298: Kill from point to the end of the current word, or if between
1299: words, to the end of the next word.
1300: Word boundaries are the same as @code{shell-forward-word}.
1301:
1302: @item shell-backward-kill-word ()
1303: Kill the word behind point.
1304: Word boundaries are the same as @code{shell-backward-word}.
1305: @end ifset
1306:
1307: @item unix-word-rubout (C-w)
1308: Kill the word behind point, using white space as a word boundary.
1309: The killed text is saved on the kill-ring.
1310:
1311: @item unix-filename-rubout ()
1312: Kill the word behind point, using white space and the slash character
1313: as the word boundaries.
1314: The killed text is saved on the kill-ring.
1315:
1316: @item delete-horizontal-space ()
1317: Delete all spaces and tabs around point. By default, this is unbound.
1318:
1319: @item kill-region ()
1320: Kill the text in the current region.
1321: By default, this command is unbound.
1322:
1323: @item copy-region-as-kill ()
1324: Copy the text in the region to the kill buffer, so it can be yanked
1325: right away. By default, this command is unbound.
1326:
1327: @item copy-backward-word ()
1328: Copy the word before point to the kill buffer.
1329: The word boundaries are the same as @code{backward-word}.
1330: By default, this command is unbound.
1331:
1332: @item copy-forward-word ()
1333: Copy the word following point to the kill buffer.
1334: The word boundaries are the same as @code{forward-word}.
1335: By default, this command is unbound.
1336:
1337: @item yank (C-y)
1338: Yank the top of the kill ring into the buffer at point.
1339:
1340: @item yank-pop (M-y)
1341: Rotate the kill-ring, and yank the new top. You can only do this if
1342: the prior command is @code{yank} or @code{yank-pop}.
1343: @end ftable
1344:
1345: @node Numeric Arguments
1346: @subsection Specifying Numeric Arguments
1347: @ftable @code
1348:
1349: @item digit-argument (@kbd{M-0}, @kbd{M-1}, @dots{} @kbd{M--})
1350: Add this digit to the argument already accumulating, or start a new
1351: argument. @kbd{M--} starts a negative argument.
1352:
1353: @item universal-argument ()
1354: This is another way to specify an argument.
1355: If this command is followed by one or more digits, optionally with a
1356: leading minus sign, those digits define the argument.
1357: If the command is followed by digits, executing @code{universal-argument}
1358: again ends the numeric argument, but is otherwise ignored.
1359: As a special case, if this command is immediately followed by a
1360: character that is neither a digit or minus sign, the argument count
1361: for the next command is multiplied by four.
1362: The argument count is initially one, so executing this function the
1363: first time makes the argument count four, a second time makes the
1364: argument count sixteen, and so on.
1365: By default, this is not bound to a key.
1366: @end ftable
1367:
1368: @node Commands For Completion
1369: @subsection Letting Readline Type For You
1370:
1371: @ftable @code
1372: @item complete (@key{TAB})
1373: Attempt to perform completion on the text before point.
1374: The actual completion performed is application-specific.
1375: @ifset BashFeatures
1376: Bash attempts completion treating the text as a variable (if the
1377: text begins with @samp{$}), username (if the text begins with
1378: @samp{~}), hostname (if the text begins with @samp{@@}), or
1379: command (including aliases and functions) in turn. If none
1380: of these produces a match, filename completion is attempted.
1381: @end ifset
1382: @ifclear BashFeatures
1383: The default is filename completion.
1384: @end ifclear
1385:
1386: @item possible-completions (M-?)
1387: List the possible completions of the text before point.
1388: When displaying completions, Readline sets the number of columns used
1389: for display to the value of @code{completion-display-width}, the value of
1390: the environment variable @env{COLUMNS}, or the screen width, in that order.
1391:
1392: @item insert-completions (M-*)
1393: Insert all completions of the text before point that would have
1394: been generated by @code{possible-completions}.
1395:
1396: @item menu-complete ()
1397: Similar to @code{complete}, but replaces the word to be completed
1398: with a single match from the list of possible completions.
1399: Repeated execution of @code{menu-complete} steps through the list
1400: of possible completions, inserting each match in turn.
1401: At the end of the list of completions, the bell is rung
1402: (subject to the setting of @code{bell-style})
1403: and the original text is restored.
1404: An argument of @var{n} moves @var{n} positions forward in the list
1405: of matches; a negative argument may be used to move backward
1406: through the list.
1407: This command is intended to be bound to @key{TAB}, but is unbound
1408: by default.
1409:
1410: @item menu-complete-backward ()
1411: Identical to @code{menu-complete}, but moves backward through the list
1412: of possible completions, as if @code{menu-complete} had been given a
1413: negative argument.
1414:
1415: @item delete-char-or-list ()
1416: Deletes the character under the cursor if not at the beginning or
1417: end of the line (like @code{delete-char}).
1418: If at the end of the line, behaves identically to
1419: @code{possible-completions}.
1420: This command is unbound by default.
1421:
1422: @ifset BashFeatures
1423: @item complete-filename (M-/)
1424: Attempt filename completion on the text before point.
1425:
1426: @item possible-filename-completions (C-x /)
1427: List the possible completions of the text before point,
1428: treating it as a filename.
1429:
1430: @item complete-username (M-~)
1431: Attempt completion on the text before point, treating
1432: it as a username.
1433:
1434: @item possible-username-completions (C-x ~)
1435: List the possible completions of the text before point,
1436: treating it as a username.
1437:
1438: @item complete-variable (M-$)
1439: Attempt completion on the text before point, treating
1440: it as a shell variable.
1441:
1442: @item possible-variable-completions (C-x $)
1443: List the possible completions of the text before point,
1444: treating it as a shell variable.
1445:
1446: @item complete-hostname (M-@@)
1447: Attempt completion on the text before point, treating
1448: it as a hostname.
1449:
1450: @item possible-hostname-completions (C-x @@)
1451: List the possible completions of the text before point,
1452: treating it as a hostname.
1453:
1454: @item complete-command (M-!)
1455: Attempt completion on the text before point, treating
1456: it as a command name. Command completion attempts to
1457: match the text against aliases, reserved words, shell
1458: functions, shell builtins, and finally executable filenames,
1459: in that order.
1460:
1461: @item possible-command-completions (C-x !)
1462: List the possible completions of the text before point,
1463: treating it as a command name.
1464:
1465: @item dynamic-complete-history (M-@key{TAB})
1466: Attempt completion on the text before point, comparing
1467: the text against lines from the history list for possible
1468: completion matches.
1469:
1470: @item dabbrev-expand ()
1471: Attempt menu completion on the text before point, comparing
1472: the text against lines from the history list for possible
1473: completion matches.
1474:
1475: @item complete-into-braces (M-@{)
1476: Perform filename completion and insert the list of possible completions
1477: enclosed within braces so the list is available to the shell
1478: (@pxref{Brace Expansion}).
1479:
1480: @end ifset
1481: @end ftable
1482:
1483: @node Keyboard Macros
1484: @subsection Keyboard Macros
1485: @ftable @code
1486:
1487: @item start-kbd-macro (C-x ()
1488: Begin saving the characters typed into the current keyboard macro.
1489:
1490: @item end-kbd-macro (C-x ))
1491: Stop saving the characters typed into the current keyboard macro
1492: and save the definition.
1493:
1494: @item call-last-kbd-macro (C-x e)
1495: Re-execute the last keyboard macro defined, by making the characters
1496: in the macro appear as if typed at the keyboard.
1497:
1498: @item print-last-kbd-macro ()
1499: Print the last keboard macro defined in a format suitable for the
1500: @var{inputrc} file.
1501:
1502: @end ftable
1503:
1504: @node Miscellaneous Commands
1505: @subsection Some Miscellaneous Commands
1506: @ftable @code
1507:
1508: @item re-read-init-file (C-x C-r)
1509: Read in the contents of the @var{inputrc} file, and incorporate
1510: any bindings or variable assignments found there.
1511:
1512: @item abort (C-g)
1513: Abort the current editing command and
1514: ring the terminal's bell (subject to the setting of
1515: @code{bell-style}).
1516:
1517: @item do-uppercase-version (M-a, M-b, M-@var{x}, @dots{})
1518: If the metafied character @var{x} is lowercase, run the command
1519: that is bound to the corresponding uppercase character.
1520:
1521: @item prefix-meta (@key{ESC})
1522: Metafy the next character typed. This is for keyboards
1523: without a meta key. Typing @samp{@key{ESC} f} is equivalent to typing
1524: @kbd{M-f}.
1525:
1526: @item undo (C-_ or C-x C-u)
1527: Incremental undo, separately remembered for each line.
1528:
1529: @item revert-line (M-r)
1530: Undo all changes made to this line. This is like executing the @code{undo}
1531: command enough times to get back to the beginning.
1532:
1533: @ifset BashFeatures
1534: @item tilde-expand (M-&)
1535: @end ifset
1536: @ifclear BashFeatures
1537: @item tilde-expand (M-~)
1538: @end ifclear
1539: Perform tilde expansion on the current word.
1540:
1541: @item set-mark (C-@@)
1542: Set the mark to the point. If a
1543: numeric argument is supplied, the mark is set to that position.
1544:
1545: @item exchange-point-and-mark (C-x C-x)
1546: Swap the point with the mark. The current cursor position is set to
1547: the saved position, and the old cursor position is saved as the mark.
1548:
1549: @item character-search (C-])
1550: A character is read and point is moved to the next occurrence of that
1551: character. A negative count searches for previous occurrences.
1552:
1553: @item character-search-backward (M-C-])
1554: A character is read and point is moved to the previous occurrence
1555: of that character. A negative count searches for subsequent
1556: occurrences.
1557:
1558: @item skip-csi-sequence ()
1559: Read enough characters to consume a multi-key sequence such as those
1560: defined for keys like Home and End. Such sequences begin with a
1561: Control Sequence Indicator (CSI), usually ESC-[. If this sequence is
1562: bound to "\e[", keys producing such sequences will have no effect
1563: unless explicitly bound to a readline command, instead of inserting
1564: stray characters into the editing buffer. This is unbound by default,
1565: but usually bound to ESC-[.
1566:
1567: @item insert-comment (M-#)
1568: Without a numeric argument, the value of the @code{comment-begin}
1569: variable is inserted at the beginning of the current line.
1570: If a numeric argument is supplied, this command acts as a toggle: if
1571: the characters at the beginning of the line do not match the value
1572: of @code{comment-begin}, the value is inserted, otherwise
1573: the characters in @code{comment-begin} are deleted from the beginning of
1574: the line.
1575: In either case, the line is accepted as if a newline had been typed.
1576: @ifset BashFeatures
1577: The default value of @code{comment-begin} causes this command
1578: to make the current line a shell comment.
1579: If a numeric argument causes the comment character to be removed, the line
1580: will be executed by the shell.
1581: @end ifset
1582:
1583: @item dump-functions ()
1584: Print all of the functions and their key bindings to the
1585: Readline output stream. If a numeric argument is supplied,
1586: the output is formatted in such a way that it can be made part
1587: of an @var{inputrc} file. This command is unbound by default.
1588:
1589: @item dump-variables ()
1590: Print all of the settable variables and their values to the
1591: Readline output stream. If a numeric argument is supplied,
1592: the output is formatted in such a way that it can be made part
1593: of an @var{inputrc} file. This command is unbound by default.
1594:
1595: @item dump-macros ()
1596: Print all of the Readline key sequences bound to macros and the
1597: strings they output. If a numeric argument is supplied,
1598: the output is formatted in such a way that it can be made part
1599: of an @var{inputrc} file. This command is unbound by default.
1600:
1601: @ifset BashFeatures
1602: @item glob-complete-word (M-g)
1603: The word before point is treated as a pattern for pathname expansion,
1604: with an asterisk implicitly appended. This pattern is used to
1605: generate a list of matching file names for possible completions.
1606:
1607: @item glob-expand-word (C-x *)
1608: The word before point is treated as a pattern for pathname expansion,
1609: and the list of matching file names is inserted, replacing the word.
1610: If a numeric argument is supplied, a @samp{*} is appended before
1611: pathname expansion.
1612:
1613: @item glob-list-expansions (C-x g)
1614: The list of expansions that would have been generated by
1615: @code{glob-expand-word} is displayed, and the line is redrawn.
1616: If a numeric argument is supplied, a @samp{*} is appended before
1617: pathname expansion.
1618:
1619: @item display-shell-version (C-x C-v)
1620: Display version information about the current instance of Bash.
1621:
1622: @item shell-expand-line (M-C-e)
1623: Expand the line as the shell does.
1624: This performs alias and history expansion as well as all of the shell
1625: word expansions (@pxref{Shell Expansions}).
1626:
1627: @item history-expand-line (M-^)
1628: Perform history expansion on the current line.
1629:
1630: @item magic-space ()
1631: Perform history expansion on the current line and insert a space
1632: (@pxref{History Interaction}).
1633:
1634: @item alias-expand-line ()
1635: Perform alias expansion on the current line (@pxref{Aliases}).
1636:
1637: @item history-and-alias-expand-line ()
1638: Perform history and alias expansion on the current line.
1639:
1640: @item insert-last-argument (M-. or M-_)
1641: A synonym for @code{yank-last-arg}.
1642:
1643: @item operate-and-get-next (C-o)
1644: Accept the current line for execution and fetch the next line
1645: relative to the current line from the history for editing. Any
1646: argument is ignored.
1647:
1648: @item edit-and-execute-command (C-xC-e)
1649: Invoke an editor on the current command line, and execute the result as shell
1650: commands.
1651: Bash attempts to invoke
1652: @code{$VISUAL}, @code{$EDITOR}, and @code{emacs}
1653: as the editor, in that order.
1654:
1655: @end ifset
1656:
1657: @ifclear BashFeatures
1658: @item emacs-editing-mode (C-e)
1659: When in @code{vi} command mode, this causes a switch to @code{emacs}
1660: editing mode.
1661:
1662: @item vi-editing-mode (M-C-j)
1663: When in @code{emacs} editing mode, this causes a switch to @code{vi}
1664: editing mode.
1665:
1666: @end ifclear
1667:
1668: @end ftable
1669:
1670: @node Readline vi Mode
1671: @section Readline vi Mode
1672:
1673: While the Readline library does not have a full set of @code{vi}
1674: editing functions, it does contain enough to allow simple editing
1675: of the line. The Readline @code{vi} mode behaves as specified in
1676: the @sc{posix} standard.
1677:
1678: @ifset BashFeatures
1679: In order to switch interactively between @code{emacs} and @code{vi}
1680: editing modes, use the @samp{set -o emacs} and @samp{set -o vi}
1681: commands (@pxref{The Set Builtin}).
1682: @end ifset
1683: @ifclear BashFeatures
1684: In order to switch interactively between @code{emacs} and @code{vi}
1685: editing modes, use the command @kbd{M-C-j} (bound to emacs-editing-mode
1686: when in @code{vi} mode and to vi-editing-mode in @code{emacs} mode).
1687: @end ifclear
1688: The Readline default is @code{emacs} mode.
1689:
1690: When you enter a line in @code{vi} mode, you are already placed in
1691: `insertion' mode, as if you had typed an @samp{i}. Pressing @key{ESC}
1692: switches you into `command' mode, where you can edit the text of the
1693: line with the standard @code{vi} movement keys, move to previous
1694: history lines with @samp{k} and subsequent lines with @samp{j}, and
1695: so forth.
1696:
1697: @ifset BashFeatures
1698: @node Programmable Completion
1699: @section Programmable Completion
1700: @cindex programmable completion
1701:
1702: When word completion is attempted for an argument to a command for
1703: which a completion specification (a @var{compspec}) has been defined
1704: using the @code{complete} builtin (@pxref{Programmable Completion Builtins}),
1705: the programmable completion facilities are invoked.
1706:
1707: First, the command name is identified.
1708: If a compspec has been defined for that command, the
1709: compspec is used to generate the list of possible completions for the word.
1710: If the command word is the empty string (completion attempted at the
1711: beginning of an empty line), any compspec defined with
1712: the @option{-E} option to @code{complete} is used.
1713: If the command word is a full pathname, a compspec for the full
1714: pathname is searched for first.
1715: If no compspec is found for the full pathname, an attempt is made to
1716: find a compspec for the portion following the final slash.
1717: If those searches do not result in a compspec, any compspec defined with
1718: the @option{-D} option to @code{complete} is used as the default.
1719:
1720: Once a compspec has been found, it is used to generate the list of
1721: matching words.
1722: If a compspec is not found, the default Bash completion
1723: described above (@pxref{Commands For Completion}) is performed.
1724:
1725: First, the actions specified by the compspec are used.
1726: Only matches which are prefixed by the word being completed are
1727: returned.
1728: When the @option{-f} or @option{-d} option is used for filename or
1729: directory name completion, the shell variable @env{FIGNORE} is
1730: used to filter the matches.
1731: @xref{Bash Variables}, for a description of @env{FIGNORE}.
1732:
1733: Any completions specified by a filename expansion pattern to the
1734: @option{-G} option are generated next.
1735: The words generated by the pattern need not match the word being completed.
1736: The @env{GLOBIGNORE} shell variable is not used to filter the matches,
1737: but the @env{FIGNORE} shell variable is used.
1738:
1739: Next, the string specified as the argument to the @option{-W} option
1740: is considered.
1741: The string is first split using the characters in the @env{IFS}
1742: special variable as delimiters.
1743: Shell quoting is honored.
1744: Each word is then expanded using
1745: brace expansion, tilde expansion, parameter and variable expansion,
1746: command substitution, and arithmetic expansion,
1747: as described above (@pxref{Shell Expansions}).
1748: The results are split using the rules described above
1749: (@pxref{Word Splitting}).
1750: The results of the expansion are prefix-matched against the word being
1751: completed, and the matching words become the possible completions.
1752:
1753: After these matches have been generated, any shell function or command
1754: specified with the @option{-F} and @option{-C} options is invoked.
1755: When the command or function is invoked, the @env{COMP_LINE},
1756: @env{COMP_POINT}, @env{COMP_KEY}, and @env{COMP_TYPE} variables are
1757: assigned values as described above (@pxref{Bash Variables}).
1758: If a shell function is being invoked, the @env{COMP_WORDS} and
1759: @env{COMP_CWORD} variables are also set.
1760: When the function or command is invoked, the first argument ($1) is the
1761: name of the command whose arguments are being completed, the
1762: second argument ($2) is the word being completed, and the third argument
1763: ($3) is the word preceding the word being completed on the current command
1764: line.
1765: No filtering of the generated completions against the word being completed
1766: is performed; the function or command has complete freedom in generating
1767: the matches.
1768:
1769: Any function specified with @option{-F} is invoked first.
1770: The function may use any of the shell facilities, including the
1771: @code{compgen} and @code{compopt} builtins described below
1772: (@pxref{Programmable Completion Builtins}), to generate the matches.
1773: It must put the possible completions in the @env{COMPREPLY} array
1774: variable, one per array element.
1775:
1776: Next, any command specified with the @option{-C} option is invoked
1777: in an environment equivalent to command substitution.
1778: It should print a list of completions, one per line, to
1779: the standard output.
1780: Backslash may be used to escape a newline, if necessary.
1781:
1782: After all of the possible completions are generated, any filter
1783: specified with the @option{-X} option is applied to the list.
1784: The filter is a pattern as used for pathname expansion; a @samp{&}
1785: in the pattern is replaced with the text of the word being completed.
1786: A literal @samp{&} may be escaped with a backslash; the backslash
1787: is removed before attempting a match.
1788: Any completion that matches the pattern will be removed from the list.
1789: A leading @samp{!} negates the pattern; in this case any completion
1790: not matching the pattern will be removed.
1791:
1792: Finally, any prefix and suffix specified with the @option{-P} and @option{-S}
1793: options are added to each member of the completion list, and the result is
1794: returned to the Readline completion code as the list of possible
1795: completions.
1796:
1797: If the previously-applied actions do not generate any matches, and the
1798: @option{-o dirnames} option was supplied to @code{complete} when the
1799: compspec was defined, directory name completion is attempted.
1800:
1801: If the @option{-o plusdirs} option was supplied to @code{complete} when
1802: the compspec was defined, directory name completion is attempted and any
1803: matches are added to the results of the other actions.
1804:
1805: By default, if a compspec is found, whatever it generates is returned to
1806: the completion code as the full set of possible completions.
1807: The default Bash completions are not attempted, and the Readline default
1808: of filename completion is disabled.
1809: If the @option{-o bashdefault} option was supplied to @code{complete} when
1810: the compspec was defined, the default Bash completions are attempted
1811: if the compspec generates no matches.
1812: If the @option{-o default} option was supplied to @code{complete} when the
1813: compspec was defined, Readline's default completion will be performed
1814: if the compspec (and, if attempted, the default Bash completions)
1815: generate no matches.
1816:
1817: When a compspec indicates that directory name completion is desired,
1818: the programmable completion functions force Readline to append a slash
1819: to completed names which are symbolic links to directories, subject to
1820: the value of the @var{mark-directories} Readline variable, regardless
1821: of the setting of the @var{mark-symlinked-directories} Readline variable.
1822:
1823: There is some support for dynamically modifying completions. This is
1824: most useful when used in combination with a default completion specified
1825: with @option{-D}. It's possible for shell functions executed as completion
1826: handlers to indicate that completion should be retried by returning an
1827: exit status of 124. If a shell function returns 124, and changes
1828: the compspec associated with the command on which completion is being
1829: attempted (supplied as the first argument when the function is executed),
1830: programmable completion restarts from the beginning, with an
1831: attempt to find a new compspec for that command. This allows a set of
1832: completions to be built dynamically as completion is attempted, rather than
1833: being loaded all at once.
1834:
1835: For instance, assuming that there is a library of compspecs, each kept in a
1836: file corresponding to the name of the command, the following default
1837: completion function would load completions dynamically:
1838:
1839: @example
1840: _completion_loader()
1841: @{
1842: . "/etc/bash_completion.d/$1.sh" >/dev/null 2>&1 && return 124
1843: @}
1844: complete -D -F _completion_loader -o bashdefault -o default
1845: @end example
1846:
1847: @node Programmable Completion Builtins
1848: @section Programmable Completion Builtins
1849: @cindex completion builtins
1850:
1851: Three builtin commands are available to manipulate the programmable completion
1852: facilities: one to specify how the arguments to a particular command are to
1853: be completed, and two to modify the completion as it is happening.
1854:
1855: @table @code
1856: @item compgen
1857: @btindex compgen
1858: @example
1859: @code{compgen [@var{option}] [@var{word}]}
1860: @end example
1861:
1862: Generate possible completion matches for @var{word} according to
1863: the @var{option}s, which may be any option accepted by the
1864: @code{complete}
1865: builtin with the exception of @option{-p} and @option{-r}, and write
1866: the matches to the standard output.
1867: When using the @option{-F} or @option{-C} options, the various shell variables
1868: set by the programmable completion facilities, while available, will not
1869: have useful values.
1870:
1871: The matches will be generated in the same way as if the programmable
1872: completion code had generated them directly from a completion specification
1873: with the same flags.
1874: If @var{word} is specified, only those completions matching @var{word}
1875: will be displayed.
1876:
1877: The return value is true unless an invalid option is supplied, or no
1878: matches were generated.
1879:
1880: @item complete
1881: @btindex complete
1882: @example
1883: @code{complete [-abcdefgjksuv] [-o @var{comp-option}] [-DE] [-A @var{action}] [-G @var{globpat}] [-W @var{wordlist}]
1884: [-F @var{function}] [-C @var{command}] [-X @var{filterpat}]
1885: [-P @var{prefix}] [-S @var{suffix}] @var{name} [@var{name} @dots{}]}
1886: @code{complete -pr [-DE] [@var{name} @dots{}]}
1887: @end example
1888:
1889: Specify how arguments to each @var{name} should be completed.
1890: If the @option{-p} option is supplied, or if no options are supplied, existing
1891: completion specifications are printed in a way that allows them to be
1892: reused as input.
1893: The @option{-r} option removes a completion specification for
1894: each @var{name}, or, if no @var{name}s are supplied, all
1895: completion specifications.
1896: The @option{-D} option indicates that the remaining options and actions should
1897: apply to the ``default'' command completion; that is, completion attempted
1898: on a command for which no completion has previously been defined.
1899: The @option{-E} option indicates that the remaining options and actions should
1900: apply to ``empty'' command completion; that is, completion attempted on a
1901: blank line.
1902:
1903: The process of applying these completion specifications when word completion
1904: is attempted is described above (@pxref{Programmable Completion}). The
1905: @option{-D} option takes precedence over @option{-E}.
1906:
1907: Other options, if specified, have the following meanings.
1908: The arguments to the @option{-G}, @option{-W}, and @option{-X} options
1909: (and, if necessary, the @option{-P} and @option{-S} options)
1910: should be quoted to protect them from expansion before the
1911: @code{complete} builtin is invoked.
1912:
1913:
1914: @table @code
1915: @item -o @var{comp-option}
1916: The @var{comp-option} controls several aspects of the compspec's behavior
1917: beyond the simple generation of completions.
1918: @var{comp-option} may be one of:
1919:
1920: @table @code
1921:
1922: @item bashdefault
1923: Perform the rest of the default Bash completions if the compspec
1924: generates no matches.
1925:
1926: @item default
1927: Use Readline's default filename completion if the compspec generates
1928: no matches.
1929:
1930: @item dirnames
1931: Perform directory name completion if the compspec generates no matches.
1932:
1933: @item filenames
1934: Tell Readline that the compspec generates filenames, so it can perform any
1935: filename-specific processing (like adding a slash to directory names
1936: quoting special characters, or suppressing trailing spaces).
1937: This option is intended to be used with shell functions specified
1938: with @option{-F}.
1939:
1940: @item noquote
1941: Tell Readline not to quote the completed words if they are filenames
1942: (quoting filenames is the default).
1943:
1944: @item nospace
1945: Tell Readline not to append a space (the default) to words completed at
1946: the end of the line.
1947:
1948: @item plusdirs
1949: After any matches defined by the compspec are generated,
1950: directory name completion is attempted and any
1951: matches are added to the results of the other actions.
1952:
1953: @end table
1954:
1955: @item -A @var{action}
1956: The @var{action} may be one of the following to generate a list of possible
1957: completions:
1958:
1959: @table @code
1960: @item alias
1961: Alias names. May also be specified as @option{-a}.
1962:
1963: @item arrayvar
1964: Array variable names.
1965:
1966: @item binding
1967: Readline key binding names (@pxref{Bindable Readline Commands}).
1968:
1969: @item builtin
1970: Names of shell builtin commands. May also be specified as @option{-b}.
1971:
1972: @item command
1973: Command names. May also be specified as @option{-c}.
1974:
1975: @item directory
1976: Directory names. May also be specified as @option{-d}.
1977:
1978: @item disabled
1979: Names of disabled shell builtins.
1980:
1981: @item enabled
1982: Names of enabled shell builtins.
1983:
1984: @item export
1985: Names of exported shell variables. May also be specified as @option{-e}.
1986:
1987: @item file
1988: File names. May also be specified as @option{-f}.
1989:
1990: @item function
1991: Names of shell functions.
1992:
1993: @item group
1994: Group names. May also be specified as @option{-g}.
1995:
1996: @item helptopic
1997: Help topics as accepted by the @code{help} builtin (@pxref{Bash Builtins}).
1998:
1999: @item hostname
2000: Hostnames, as taken from the file specified by the
2001: @env{HOSTFILE} shell variable (@pxref{Bash Variables}).
2002:
2003: @item job
2004: Job names, if job control is active. May also be specified as @option{-j}.
2005:
2006: @item keyword
2007: Shell reserved words. May also be specified as @option{-k}.
2008:
2009: @item running
2010: Names of running jobs, if job control is active.
2011:
2012: @item service
2013: Service names. May also be specified as @option{-s}.
2014:
2015: @item setopt
2016: Valid arguments for the @option{-o} option to the @code{set} builtin
2017: (@pxref{The Set Builtin}).
2018:
2019: @item shopt
2020: Shell option names as accepted by the @code{shopt} builtin
2021: (@pxref{Bash Builtins}).
2022:
2023: @item signal
2024: Signal names.
2025:
2026: @item stopped
2027: Names of stopped jobs, if job control is active.
2028:
2029: @item user
2030: User names. May also be specified as @option{-u}.
2031:
2032: @item variable
2033: Names of all shell variables. May also be specified as @option{-v}.
2034: @end table
2035:
2036: @item -C @var{command}
2037: @var{command} is executed in a subshell environment, and its output is
2038: used as the possible completions.
2039:
2040: @item -F @var{function}
2041: The shell function @var{function} is executed in the current shell
2042: environment.
2043: When it is executed, $1 is the name of the command whose arguments are
2044: being completed, $2 is the word being completed, and $3 is the word
2045: preceding the word being completed, as described above
2046: (@pxref{Programmable Completion}).
2047: When it finishes, the possible completions are retrieved from the value
2048: of the @env{COMPREPLY} array variable.
2049:
2050: @item -G @var{globpat}
2051: The filename expansion pattern @var{globpat} is expanded to generate
2052: the possible completions.
2053:
2054: @item -P @var{prefix}
2055: @var{prefix} is added at the beginning of each possible completion
2056: after all other options have been applied.
2057:
2058: @item -S @var{suffix}
2059: @var{suffix} is appended to each possible completion
2060: after all other options have been applied.
2061:
2062: @item -W @var{wordlist}
2063: The @var{wordlist} is split using the characters in the
2064: @env{IFS} special variable as delimiters, and each resultant word
2065: is expanded.
2066: The possible completions are the members of the resultant list which
2067: match the word being completed.
2068:
2069: @item -X @var{filterpat}
2070: @var{filterpat} is a pattern as used for filename expansion.
2071: It is applied to the list of possible completions generated by the
2072: preceding options and arguments, and each completion matching
2073: @var{filterpat} is removed from the list.
2074: A leading @samp{!} in @var{filterpat} negates the pattern; in this
2075: case, any completion not matching @var{filterpat} is removed.
2076: @end table
2077:
2078: The return value is true unless an invalid option is supplied, an option
2079: other than @option{-p} or @option{-r} is supplied without a @var{name}
2080: argument, an attempt is made to remove a completion specification for
2081: a @var{name} for which no specification exists, or
2082: an error occurs adding a completion specification.
2083:
2084: @item compopt
2085: @btindex compopt
2086: @example
2087: @code{compopt} [-o @var{option}] [-DE] [+o @var{option}] [@var{name}]
2088: @end example
2089: Modify completion options for each @var{name} according to the
2090: @var{option}s, or for the currently-executing completion if no @var{name}s
2091: are supplied.
2092: If no @var{option}s are given, display the completion options for each
2093: @var{name} or the current completion.
2094: The possible values of @var{option} are those valid for the @code{complete}
2095: builtin described above.
2096: The @option{-D} option indicates that the remaining options should
2097: apply to the ``default'' command completion; that is, completion attempted
2098: on a command for which no completion has previously been defined.
2099: The @option{-E} option indicates that the remaining options should
2100: apply to ``empty'' command completion; that is, completion attempted on a
2101: blank line.
2102:
2103: The @option{-D} option takes precedence over @option{-E}.
2104:
2105: The return value is true unless an invalid option is supplied, an attempt
2106: is made to modify the options for a @var{name} for which no completion
2107: specification exists, or an output error occurs.
2108:
2109: @end table
2110:
2111: @node A Programmable Completion Example
2112: @section A Programmable Completion Example
2113:
2114: The most common way to obtain additional completion functionality beyond
2115: the default actions @code{complete} and @code{compgen} provide is to use
2116: a shell function and bind it to a particular command using @code{complete -F}.
2117:
2118: The following function provides completions for the @code{cd} builtin.
2119: It is a reasonably good example of what shell functions must do when
2120: used for completion. This function uses the word passsed as @code{$2}
2121: to determine the directory name to complete. You can also use the
2122: @code{COMP_WORDS} array variable; the current word is indexed by the
2123: @code{COMP_CWORD} variable.
2124:
2125: The function relies on the @code{complete} and @code{compgen} builtins
2126: to do much of the work, adding only the things that the Bash @code{cd}
2127: does beyond accepting basic directory names:
2128: tilde expansion (@pxref{Tilde Expansion}),
2129: searching directories in @var{$CDPATH}, which is described above
2130: (@pxref{Bourne Shell Builtins}),
2131: and basic support for the @code{cdable_vars} shell option
2132: (@pxref{The Shopt Builtin}).
2133: @code{_comp_cd} modifies the value of @var{IFS} so that it contains only
2134: a newline to accommodate file names containing spaces and tabs --
2135: @code{compgen} prints the possible completions it generates one per line.
2136:
2137: Possible completions go into the @var{COMPREPLY} array variable, one
2138: completion per array element. The programmable completion system retrieves
2139: the completions from there when the function returns.
2140:
2141: @example
2142: # A completion function for the cd builtin
2143: # based on the cd completion function from the bash_completion package
2144: _comp_cd()
2145: @{
2146: local IFS=$' \t\n' # normalize IFS
2147: local cur _skipdot _cdpath
2148: local i j k
2149:
2150: # Tilde expansion, with side effect of expanding tilde to full pathname
2151: case "$2" in
2152: \~*) eval cur="$2" ;;
2153: *) cur=$2 ;;
2154: esac
2155:
2156: # no cdpath or absolute pathname -- straight directory completion
2157: if [[ -z "$@{CDPATH:-@}" ]] || [[ "$cur" == @@(./*|../*|/*) ]]; then
2158: # compgen prints paths one per line; could also use while loop
2159: IFS=$'\n'
2160: COMPREPLY=( $(compgen -d -- "$cur") )
2161: IFS=$' \t\n'
2162: # CDPATH+directories in the current directory if not in CDPATH
2163: else
2164: IFS=$'\n'
2165: _skipdot=false
2166: # preprocess CDPATH to convert null directory names to .
2167: _cdpath=$@{CDPATH/#:/.:@}
2168: _cdpath=$@{_cdpath//::/:.:@}
2169: _cdpath=$@{_cdpath/%:/:.@}
2170: for i in $@{_cdpath//:/$'\n'@}; do
2171: if [[ $i -ef . ]]; then _skipdot=true; fi
2172: k="$@{#COMPREPLY[@@]@}"
2173: for j in $( compgen -d -- "$i/$cur" ); do
2174: COMPREPLY[k++]=$@{j#$i/@} # cut off directory
2175: done
2176: done
2177: $_skipdot || COMPREPLY+=( $(compgen -d -- "$cur") )
2178: IFS=$' \t\n'
2179: fi
2180:
2181: # variable names if appropriate shell option set and no completions
2182: if shopt -q cdable_vars && [[ $@{#COMPREPLY[@@]@} -eq 0 ]]; then
2183: COMPREPLY=( $(compgen -v -- "$cur") )
2184: fi
2185:
2186: return 0
2187: @}
2188: @end example
2189:
2190: We install the completion function using the @option{-F} option to
2191: @code{complete}:
2192:
2193: @example
2194: # Tell readline to quote appropriate and append slashes to directories;
2195: # use the bash default completion for other arguments
2196: complete -o filenames -o nospace -o bashdefault -F _comp_cd cd
2197: @end example
2198:
2199: @noindent
2200: Since we'd like Bash and Readline to take care of some
2201: of the other details for us, we use several other options to tell Bash
2202: and Readline what to do. The @option{-o filenames} option tells Readline
2203: that the possible completions should be treated as filenames, and quoted
2204: appropriately. That option will also cause Readline to append a slash to
2205: filenames it can determine are directories (which is why we might want to
2206: extend @code{_comp_cd} to append a slash if we're using directories found
2207: via @var{CDPATH}: Readline can't tell those completions are directories).
2208: The @option{-o nospace} option tells Readline to not append a space
2209: character to the directory name, in case we want to append to it.
2210: The @option{-o bashdefault} option brings in the rest of the "Bash default"
2211: completions -- possible completion that Bash adds to the default Readline
2212: set. These include things like command name completion, variable completion
2213: for words beginning with @samp{@{}, completions containing pathname
2214: expansion patterns (@pxref{Filename Expansion}), and so on.
2215:
2216: Once installed using @code{complete}, @code{_comp_cd} will be called every
2217: time we attempt word completion for a @code{cd} command.
2218:
2219: Many more examples -- an extensive collection of completions for most of
2220: the common GNU, Unix, and Linux commands -- are available as part of the
2221: bash_completion project. This is installed by default on many GNU/Linux
2222: distributions. Originally written by Ian Macdonald, the project now lives
2223: at @url{http://bash-completion.alioth.debian.org/}. There are ports for
2224: other systems such as Solaris and Mac OS X.
2225:
2226: An older version of the bash_completion package is distributed with bash
2227: in the @file{examples/complete} subdirectory.
2228:
2229: @end ifset
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to rluser.texi CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / readline / doc