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--2020 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: @ifset BashFeatures
354: The @w{@code{bind}} builtin command can also be used to set Readline
355: keybindings and variables.
356: @xref{Bash Builtins}.
357: @end ifset
358:
359: When a program which uses the Readline library starts up, the
360: init file is read, and the key bindings are set.
361:
362: In addition, the @code{C-x C-r} command re-reads this init file, thus
363: incorporating any changes that you might have made to it.
364:
365: @menu
366: * Readline Init File Syntax:: Syntax for the commands in the inputrc file.
367:
368: * Conditional Init Constructs:: Conditional key bindings in the inputrc file.
369:
370: * Sample Init File:: An example inputrc file.
371: @end menu
372:
373: @node Readline Init File Syntax
374: @subsection Readline Init File Syntax
375:
376: There are only a few basic constructs allowed in the
377: Readline init file. Blank lines are ignored.
378: Lines beginning with a @samp{#} are comments.
379: Lines beginning with a @samp{$} indicate conditional
380: constructs (@pxref{Conditional Init Constructs}). Other lines
381: denote variable settings and key bindings.
382:
383: @table @asis
384: @item Variable Settings
385: You can modify the run-time behavior of Readline by
386: altering the values of variables in Readline
387: using the @code{set} command within the init file.
388: The syntax is simple:
389:
390: @example
391: set @var{variable} @var{value}
392: @end example
393:
394: @noindent
395: Here, for example, is how to
396: change from the default Emacs-like key binding to use
397: @code{vi} line editing commands:
398:
399: @example
400: set editing-mode vi
401: @end example
402:
403: Variable names and values, where appropriate, are recognized without regard
404: to case. Unrecognized variable names are ignored.
405:
406: Boolean variables (those that can be set to on or off) are set to on if
407: the value is null or empty, @var{on} (case-insensitive), or 1. Any other
408: value results in the variable being set to off.
409:
410: @ifset BashFeatures
411: The @w{@code{bind -V}} command lists the current Readline variable names
412: and values. @xref{Bash Builtins}.
413: @end ifset
414:
415: A great deal of run-time behavior is changeable with the following
416: variables.
417:
418: @cindex variables, readline
419: @table @code
420:
421: @item bell-style
422: @vindex bell-style
423: Controls what happens when Readline wants to ring the terminal bell.
424: If set to @samp{none}, Readline never rings the bell. If set to
425: @samp{visible}, Readline uses a visible bell if one is available.
426: If set to @samp{audible} (the default), Readline attempts to ring
427: the terminal's bell.
428:
429: @item bind-tty-special-chars
430: @vindex bind-tty-special-chars
431: If set to @samp{on} (the default), Readline attempts to bind the control
432: characters treated specially by the kernel's terminal driver to their
433: Readline equivalents.
434:
435: @item blink-matching-paren
436: @vindex blink-matching-paren
437: If set to @samp{on}, Readline attempts to briefly move the cursor to an
438: opening parenthesis when a closing parenthesis is inserted. The default
439: is @samp{off}.
440:
441: @item colored-completion-prefix
442: @vindex colored-completion-prefix
443: If set to @samp{on}, when listing completions, Readline displays the
444: common prefix of the set of possible completions using a different color.
445: The color definitions are taken from the value of the @env{LS_COLORS}
446: environment variable.
447: The default is @samp{off}.
448:
449: @item colored-stats
450: @vindex colored-stats
451: If set to @samp{on}, Readline displays possible completions using different
452: colors to indicate their file type.
453: The color definitions are taken from the value of the @env{LS_COLORS}
454: environment variable.
455: The default is @samp{off}.
456:
457: @item comment-begin
458: @vindex comment-begin
459: The string to insert at the beginning of the line when the
460: @code{insert-comment} command is executed. The default value
461: is @code{"#"}.
462:
463: @item completion-display-width
464: @vindex completion-display-width
465: The number of screen columns used to display possible matches
466: when performing completion.
467: The value is ignored if it is less than 0 or greater than the terminal
468: screen width.
469: A value of 0 will cause matches to be displayed one per line.
470: The default value is -1.
471:
472: @item completion-ignore-case
473: @vindex completion-ignore-case
474: If set to @samp{on}, Readline performs filename matching and completion
475: in a case-insensitive fashion.
476: The default value is @samp{off}.
477:
478: @item completion-map-case
479: @vindex completion-map-case
480: If set to @samp{on}, and @var{completion-ignore-case} is enabled, Readline
481: treats hyphens (@samp{-}) and underscores (@samp{_}) as equivalent when
482: performing case-insensitive filename matching and completion.
483: The default value is @samp{off}.
484:
485: @item completion-prefix-display-length
486: @vindex completion-prefix-display-length
487: The length in characters of the common prefix of a list of possible
488: completions that is displayed without modification. When set to a
489: value greater than zero, common prefixes longer than this value are
490: replaced with an ellipsis when displaying possible completions.
491:
492: @item completion-query-items
493: @vindex completion-query-items
494: The number of possible completions that determines when the user is
495: asked whether the list of possibilities should be displayed.
496: If the number of possible completions is greater than or equal to this value,
497: Readline will ask whether or not the user wishes to view them;
498: otherwise, they are simply listed.
499: This variable must be set to an integer value greater than or equal to 0.
500: A negative value means Readline should never ask.
501: The default limit is @code{100}.
502:
503: @item convert-meta
504: @vindex convert-meta
505: If set to @samp{on}, Readline will convert characters with the
506: eighth bit set to an @sc{ascii} key sequence by stripping the eighth
507: bit and prefixing an @key{ESC} character, converting them to a
508: meta-prefixed key sequence. The default value is @samp{on}, but
509: will be set to @samp{off} if the locale is one that contains
510: eight-bit characters.
511:
512: @item disable-completion
513: @vindex disable-completion
514: If set to @samp{On}, Readline will inhibit word completion.
515: Completion characters will be inserted into the line as if they had
516: been mapped to @code{self-insert}. The default is @samp{off}.
517:
518: @item echo-control-characters
519: @vindex echo-control-characters
520: When set to @samp{on}, on operating systems that indicate they support it,
521: readline echoes a character corresponding to a signal generated from the
522: keyboard. The default is @samp{on}.
523:
524: @item editing-mode
525: @vindex editing-mode
526: The @code{editing-mode} variable controls which default set of
527: key bindings is used. By default, Readline starts up in Emacs editing
528: mode, where the keystrokes are most similar to Emacs. This variable can be
529: set to either @samp{emacs} or @samp{vi}.
530:
531: @item emacs-mode-string
532: @vindex emacs-mode-string
533: If the @var{show-mode-in-prompt} variable is enabled,
534: this string is displayed immediately before the last line of the primary
535: prompt when emacs editing mode is active. The value is expanded like a
536: key binding, so the standard set of meta- and control prefixes and
537: backslash escape sequences is available.
538: Use the @samp{\1} and @samp{\2} escapes to begin and end sequences of
539: non-printing characters, which can be used to embed a terminal control
540: sequence into the mode string.
541: The default is @samp{@@}.
542:
543: @item enable-bracketed-paste
544: @vindex enable-bracketed-paste
545: When set to @samp{On}, Readline will configure the terminal in a way
546: that will enable it to insert each paste into the editing buffer as a
547: single string of characters, instead of treating each character as if
548: it had been read from the keyboard. This can prevent pasted characters
549: from being interpreted as editing commands. The default is @samp{On}.
550:
551: @item enable-keypad
552: @vindex enable-keypad
553: When set to @samp{on}, Readline will try to enable the application
554: keypad when it is called. Some systems need this to enable the
555: arrow keys. The default is @samp{off}.
556:
557: @item enable-meta-key
558: When set to @samp{on}, Readline will try to enable any meta modifier
559: key the terminal claims to support when it is called. On many terminals,
560: the meta key is used to send eight-bit characters.
561: The default is @samp{on}.
562:
563: @item expand-tilde
564: @vindex expand-tilde
565: If set to @samp{on}, tilde expansion is performed when Readline
566: attempts word completion. The default is @samp{off}.
567:
568: @item history-preserve-point
569: @vindex history-preserve-point
570: If set to @samp{on}, the history code attempts to place the point (the
571: current cursor position) at the
572: same location on each history line retrieved with @code{previous-history}
573: or @code{next-history}. The default is @samp{off}.
574:
575: @item history-size
576: @vindex history-size
577: Set the maximum number of history entries saved in the history list.
578: If set to zero, any existing history entries are deleted and no new entries
579: are saved.
580: If set to a value less than zero, the number of history entries is not
581: limited.
582: By default, the number of history entries is not limited.
583: If an attempt is made to set @var{history-size} to a non-numeric value,
584: the maximum number of history entries will be set to 500.
585:
586: @item horizontal-scroll-mode
587: @vindex horizontal-scroll-mode
588: This variable can be set to either @samp{on} or @samp{off}. Setting it
589: to @samp{on} means that the text of the lines being edited will scroll
590: horizontally on a single screen line when they are longer than the width
591: of the screen, instead of wrapping onto a new screen line.
592: This variable is automatically set to @samp{on} for terminals of height 1.
593: By default, this variable is set to @samp{off}.
594:
595: @item input-meta
596: @vindex input-meta
597: @vindex meta-flag
598: If set to @samp{on}, Readline will enable eight-bit input (it
599: will not clear the eighth bit in the characters it reads),
600: regardless of what the terminal claims it can support. The
601: default value is @samp{off}, but Readline will set it to @samp{on} if the
602: locale contains eight-bit characters.
603: The name @code{meta-flag} is a synonym for this variable.
604:
605: @item isearch-terminators
606: @vindex isearch-terminators
607: The string of characters that should terminate an incremental search without
608: subsequently executing the character as a command (@pxref{Searching}).
609: If this variable has not been given a value, the characters @key{ESC} and
610: @kbd{C-J} will terminate an incremental search.
611:
612: @item keymap
613: @vindex keymap
614: Sets Readline's idea of the current keymap for key binding commands.
615: Built-in @code{keymap} names are
616: @code{emacs},
617: @code{emacs-standard},
618: @code{emacs-meta},
619: @code{emacs-ctlx},
620: @code{vi},
621: @code{vi-move},
622: @code{vi-command}, and
623: @code{vi-insert}.
624: @code{vi} is equivalent to @code{vi-command} (@code{vi-move} is also a
625: synonym); @code{emacs} is equivalent to @code{emacs-standard}.
626: Applications may add additional names.
627: The default value is @code{emacs}.
628: The value of the @code{editing-mode} variable also affects the
629: default keymap.
630:
631: @item keyseq-timeout
632: Specifies the duration Readline will wait for a character when reading an
633: ambiguous key sequence (one that can form a complete key sequence using
634: the input read so far, or can take additional input to complete a longer
635: key sequence).
636: If no input is received within the timeout, Readline will use the shorter
637: but complete key sequence.
638: Readline uses this value to determine whether or not input is
639: available on the current input source (@code{rl_instream} by default).
640: The value is specified in milliseconds, so a value of 1000 means that
641: Readline will wait one second for additional input.
642: If this variable is set to a value less than or equal to zero, or to a
643: non-numeric value, Readline will wait until another key is pressed to
644: decide which key sequence to complete.
645: The default value is @code{500}.
646:
647: @item mark-directories
648: If set to @samp{on}, completed directory names have a slash
649: appended. The default is @samp{on}.
650:
651: @item mark-modified-lines
652: @vindex mark-modified-lines
653: This variable, when set to @samp{on}, causes Readline to display an
654: asterisk (@samp{*}) at the start of history lines which have been modified.
655: This variable is @samp{off} by default.
656:
657: @item mark-symlinked-directories
658: @vindex mark-symlinked-directories
659: If set to @samp{on}, completed names which are symbolic links
660: to directories have a slash appended (subject to the value of
661: @code{mark-directories}).
662: The default is @samp{off}.
663:
664: @item match-hidden-files
665: @vindex match-hidden-files
666: This variable, when set to @samp{on}, causes Readline to match files whose
667: names begin with a @samp{.} (hidden files) when performing filename
668: completion.
669: If set to @samp{off}, the leading @samp{.} must be
670: supplied by the user in the filename to be completed.
671: This variable is @samp{on} by default.
672:
673: @item menu-complete-display-prefix
674: @vindex menu-complete-display-prefix
675: If set to @samp{on}, menu completion displays the common prefix of the
676: list of possible completions (which may be empty) before cycling through
677: the list. The default is @samp{off}.
678:
679: @item output-meta
680: @vindex output-meta
681: If set to @samp{on}, Readline will display characters with the
682: eighth bit set directly rather than as a meta-prefixed escape
683: sequence.
684: The default is @samp{off}, but Readline will set it to @samp{on} if the
685: locale contains eight-bit characters.
686:
687: @item page-completions
688: @vindex page-completions
689: If set to @samp{on}, Readline uses an internal @code{more}-like pager
690: to display a screenful of possible completions at a time.
691: This variable is @samp{on} by default.
692:
693: @item print-completions-horizontally
694: If set to @samp{on}, Readline will display completions with matches
695: sorted horizontally in alphabetical order, rather than down the screen.
696: The default is @samp{off}.
697:
698: @item revert-all-at-newline
699: @vindex revert-all-at-newline
700: If set to @samp{on}, Readline will undo all changes to history lines
701: before returning when @code{accept-line} is executed. By default,
702: history lines may be modified and retain individual undo lists across
703: calls to @code{readline}. The default is @samp{off}.
704:
705: @item show-all-if-ambiguous
706: @vindex show-all-if-ambiguous
707: This alters the default behavior of the completion functions. If
708: set to @samp{on},
709: words which have more than one possible completion cause the
710: matches to be listed immediately instead of ringing the bell.
711: The default value is @samp{off}.
712:
713: @item show-all-if-unmodified
714: @vindex show-all-if-unmodified
715: This alters the default behavior of the completion functions in
716: a fashion similar to @var{show-all-if-ambiguous}.
717: If set to @samp{on},
718: words which have more than one possible completion without any
719: possible partial completion (the possible completions don't share
720: a common prefix) cause the matches to be listed immediately instead
721: of ringing the bell.
722: The default value is @samp{off}.
723:
724: @item show-mode-in-prompt
725: @vindex show-mode-in-prompt
726: If set to @samp{on}, add a string to the beginning of the prompt
727: indicating the editing mode: emacs, vi command, or vi insertion.
728: The mode strings are user-settable (e.g., @var{emacs-mode-string}).
729: The default value is @samp{off}.
730:
731: @item skip-completed-text
732: @vindex skip-completed-text
733: If set to @samp{on}, this alters the default completion behavior when
734: inserting a single match into the line. It's only active when
735: performing completion in the middle of a word. If enabled, readline
736: does not insert characters from the completion that match characters
737: after point in the word being completed, so portions of the word
738: following the cursor are not duplicated.
739: For instance, if this is enabled, attempting completion when the cursor
740: is after the @samp{e} in @samp{Makefile} will result in @samp{Makefile}
741: rather than @samp{Makefilefile}, assuming there is a single possible
742: completion.
743: The default value is @samp{off}.
744:
745: @item vi-cmd-mode-string
746: @vindex vi-cmd-mode-string
747: If the @var{show-mode-in-prompt} variable is enabled,
748: this string is displayed immediately before the last line of the primary
749: prompt when vi editing mode is active and in command mode.
750: The value is expanded like a
751: key binding, so the standard set of meta- and control prefixes and
752: backslash escape sequences is available.
753: Use the @samp{\1} and @samp{\2} escapes to begin and end sequences of
754: non-printing characters, which can be used to embed a terminal control
755: sequence into the mode string.
756: The default is @samp{(cmd)}.
757:
758: @item vi-ins-mode-string
759: @vindex vi-ins-mode-string
760: If the @var{show-mode-in-prompt} variable is enabled,
761: this string is displayed immediately before the last line of the primary
762: prompt when vi editing mode is active and in insertion mode.
763: The value is expanded like a
764: key binding, so the standard set of meta- and control prefixes and
765: backslash escape sequences is available.
766: Use the @samp{\1} and @samp{\2} escapes to begin and end sequences of
767: non-printing characters, which can be used to embed a terminal control
768: sequence into the mode string.
769: The default is @samp{(ins)}.
770:
771: @item visible-stats
772: @vindex visible-stats
773: If set to @samp{on}, a character denoting a file's type
774: is appended to the filename when listing possible
775: completions. The default is @samp{off}.
776:
777: @end table
778:
779: @item Key Bindings
780: The syntax for controlling key bindings in the init file is
781: simple. First you need to find the name of the command that you
782: want to change. The following sections contain tables of the command
783: name, the default keybinding, if any, and a short description of what
784: the command does.
785:
786: Once you know the name of the command, simply place on a line
787: in the init file the name of the key
788: you wish to bind the command to, a colon, and then the name of the
789: command.
790: There can be no space between the key name and the colon -- that will be
791: interpreted as part of the key name.
792: The name of the key can be expressed in different ways, depending on
793: what you find most comfortable.
794:
795: In addition to command names, readline allows keys to be bound
796: to a string that is inserted when the key is pressed (a @var{macro}).
797:
798: @ifset BashFeatures
799: The @w{@code{bind -p}} command displays Readline function names and
800: bindings in a format that can put directly into an initialization file.
801: @xref{Bash Builtins}.
802: @end ifset
803:
804: @table @asis
805: @item @w{@var{keyname}: @var{function-name} or @var{macro}}
806: @var{keyname} is the name of a key spelled out in English. For example:
807: @example
808: Control-u: universal-argument
809: Meta-Rubout: backward-kill-word
810: Control-o: "> output"
811: @end example
812:
813: In the example above, @kbd{C-u} is bound to the function
814: @code{universal-argument},
815: @kbd{M-DEL} is bound to the function @code{backward-kill-word}, and
816: @kbd{C-o} is bound to run the macro
817: expressed on the right hand side (that is, to insert the text
818: @samp{> output} into the line).
819:
820: A number of symbolic character names are recognized while
821: processing this key binding syntax:
822: @var{DEL},
823: @var{ESC},
824: @var{ESCAPE},
825: @var{LFD},
826: @var{NEWLINE},
827: @var{RET},
828: @var{RETURN},
829: @var{RUBOUT},
830: @var{SPACE},
831: @var{SPC},
832: and
833: @var{TAB}.
834:
835: @item @w{"@var{keyseq}": @var{function-name} or @var{macro}}
836: @var{keyseq} differs from @var{keyname} above in that strings
837: denoting an entire key sequence can be specified, by placing
838: the key sequence in double quotes. Some @sc{gnu} Emacs style key
839: escapes can be used, as in the following example, but the
840: special character names are not recognized.
841:
842: @example
843: "\C-u": universal-argument
844: "\C-x\C-r": re-read-init-file
845: "\e[11~": "Function Key 1"
846: @end example
847:
848: In the above example, @kbd{C-u} is again bound to the function
849: @code{universal-argument} (just as it was in the first example),
850: @samp{@kbd{C-x} @kbd{C-r}} is bound to the function @code{re-read-init-file},
851: and @samp{@key{ESC} @key{[} @key{1} @key{1} @key{~}} is bound to insert
852: the text @samp{Function Key 1}.
853:
854: @end table
855:
856: The following @sc{gnu} Emacs style escape sequences are available when
857: specifying key sequences:
858:
859: @table @code
860: @item @kbd{\C-}
861: control prefix
862: @item @kbd{\M-}
863: meta prefix
864: @item @kbd{\e}
865: an escape character
866: @item @kbd{\\}
867: backslash
868: @item @kbd{\"}
869: @key{"}, a double quotation mark
870: @item @kbd{\'}
871: @key{'}, a single quote or apostrophe
872: @end table
873:
874: In addition to the @sc{gnu} Emacs style escape sequences, a second
875: set of backslash escapes is available:
876:
877: @table @code
878: @item \a
879: alert (bell)
880: @item \b
881: backspace
882: @item \d
883: delete
884: @item \f
885: form feed
886: @item \n
887: newline
888: @item \r
889: carriage return
890: @item \t
891: horizontal tab
892: @item \v
893: vertical tab
894: @item \@var{nnn}
895: the eight-bit character whose value is the octal value @var{nnn}
896: (one to three digits)
897: @item \x@var{HH}
898: the eight-bit character whose value is the hexadecimal value @var{HH}
899: (one or two hex digits)
900: @end table
901:
902: When entering the text of a macro, single or double quotes must
903: be used to indicate a macro definition.
904: Unquoted text is assumed to be a function name.
905: In the macro body, the backslash escapes described above are expanded.
906: Backslash will quote any other character in the macro text,
907: including @samp{"} and @samp{'}.
908: For example, the following binding will make @samp{@kbd{C-x} \}
909: insert a single @samp{\} into the line:
910: @example
911: "\C-x\\": "\\"
912: @end example
913:
914: @end table
915:
916: @node Conditional Init Constructs
917: @subsection Conditional Init Constructs
918:
919: Readline implements a facility similar in spirit to the conditional
920: compilation features of the C preprocessor which allows key
921: bindings and variable settings to be performed as the result
922: of tests. There are four parser directives used.
923:
924: @table @code
925: @item $if
926: The @code{$if} construct allows bindings to be made based on the
927: editing mode, the terminal being used, or the application using
928: Readline. The text of the test, after any comparison operator,
929: extends to the end of the line;
930: unless otherwise noted, no characters are required to isolate it.
931:
932: @table @code
933: @item mode
934: The @code{mode=} form of the @code{$if} directive is used to test
935: whether Readline is in @code{emacs} or @code{vi} mode.
936: This may be used in conjunction
937: with the @samp{set keymap} command, for instance, to set bindings in
938: the @code{emacs-standard} and @code{emacs-ctlx} keymaps only if
939: Readline is starting out in @code{emacs} mode.
940:
941: @item term
942: The @code{term=} form may be used to include terminal-specific
943: key bindings, perhaps to bind the key sequences output by the
944: terminal's function keys. The word on the right side of the
945: @samp{=} is tested against both the full name of the terminal and
946: the portion of the terminal name before the first @samp{-}. This
947: allows @code{sun} to match both @code{sun} and @code{sun-cmd},
948: for instance.
949:
950: @item version
951: The @code{version} test may be used to perform comparisons against
952: specific Readline versions.
953: The @code{version} expands to the current Readline version.
954: The set of comparison operators includes
955: @samp{=} (and @samp{==}), @samp{!=}, @samp{<=}, @samp{>=}, @samp{<},
956: and @samp{>}.
957: The version number supplied on the right side of the operator consists
958: of a major version number, an optional decimal point, and an optional
959: minor version (e.g., @samp{7.1}). If the minor version is omitted, it
960: is assumed to be @samp{0}.
961: The operator may be separated from the string @code{version} and
962: from the version number argument by whitespace.
963: The following example sets a variable if the Readline version being used
964: is 7.0 or newer:
965: @example
966: $if version >= 7.0
967: set show-mode-in-prompt on
968: $endif
969: @end example
970:
971: @item application
972: The @var{application} construct is used to include
973: application-specific settings. Each program using the Readline
974: library sets the @var{application name}, and you can test for
975: a particular value.
976: This could be used to bind key sequences to functions useful for
977: a specific program. For instance, the following command adds a
978: key sequence that quotes the current or previous word in Bash:
979: @example
980: $if Bash
981: # Quote the current or previous word
982: "\C-xq": "\eb\"\ef\""
983: $endif
984: @end example
985:
986: @item variable
987: The @var{variable} construct provides simple equality tests for Readline
988: variables and values.
989: The permitted comparison operators are @samp{=}, @samp{==}, and @samp{!=}.
990: The variable name must be separated from the comparison operator by
991: whitespace; the operator may be separated from the value on the right hand
992: side by whitespace.
993: Both string and boolean variables may be tested. Boolean variables must be
994: tested against the values @var{on} and @var{off}.
995: The following example is equivalent to the @code{mode=emacs} test described
996: above:
997: @example
998: $if editing-mode == emacs
999: set show-mode-in-prompt on
1000: $endif
1001: @end example
1002: @end table
1003:
1004: @item $endif
1005: This command, as seen in the previous example, terminates an
1006: @code{$if} command.
1007:
1008: @item $else
1009: Commands in this branch of the @code{$if} directive are executed if
1010: the test fails.
1011:
1012: @item $include
1013: This directive takes a single filename as an argument and reads commands
1014: and bindings from that file.
1015: For example, the following directive reads from @file{/etc/inputrc}:
1016: @example
1017: $include /etc/inputrc
1018: @end example
1019: @end table
1020:
1021: @node Sample Init File
1022: @subsection Sample Init File
1023:
1024: Here is an example of an @var{inputrc} file. This illustrates key
1025: binding, variable assignment, and conditional syntax.
1026:
1027: @example
1028: @page
1029: # This file controls the behaviour of line input editing for
1030: # programs that use the GNU Readline library. Existing
1031: # programs include FTP, Bash, and GDB.
1032: #
1033: # You can re-read the inputrc file with C-x C-r.
1034: # Lines beginning with '#' are comments.
1035: #
1036: # First, include any system-wide bindings and variable
1037: # assignments from /etc/Inputrc
1038: $include /etc/Inputrc
1039:
1040: #
1041: # Set various bindings for emacs mode.
1042:
1043: set editing-mode emacs
1044:
1045: $if mode=emacs
1046:
1047: Meta-Control-h: backward-kill-word Text after the function name is ignored
1048:
1049: #
1050: # Arrow keys in keypad mode
1051: #
1052: #"\M-OD": backward-char
1053: #"\M-OC": forward-char
1054: #"\M-OA": previous-history
1055: #"\M-OB": next-history
1056: #
1057: # Arrow keys in ANSI mode
1058: #
1059: "\M-[D": backward-char
1060: "\M-[C": forward-char
1061: "\M-[A": previous-history
1062: "\M-[B": next-history
1063: #
1064: # Arrow keys in 8 bit keypad mode
1065: #
1066: #"\M-\C-OD": backward-char
1067: #"\M-\C-OC": forward-char
1068: #"\M-\C-OA": previous-history
1069: #"\M-\C-OB": next-history
1070: #
1071: # Arrow keys in 8 bit ANSI mode
1072: #
1073: #"\M-\C-[D": backward-char
1074: #"\M-\C-[C": forward-char
1075: #"\M-\C-[A": previous-history
1076: #"\M-\C-[B": next-history
1077:
1078: C-q: quoted-insert
1079:
1080: $endif
1081:
1082: # An old-style binding. This happens to be the default.
1083: TAB: complete
1084:
1085: # Macros that are convenient for shell interaction
1086: $if Bash
1087: # edit the path
1088: "\C-xp": "PATH=$@{PATH@}\e\C-e\C-a\ef\C-f"
1089: # prepare to type a quoted word --
1090: # insert open and close double quotes
1091: # and move to just after the open quote
1092: "\C-x\"": "\"\"\C-b"
1093: # insert a backslash (testing backslash escapes
1094: # in sequences and macros)
1095: "\C-x\\": "\\"
1096: # Quote the current or previous word
1097: "\C-xq": "\eb\"\ef\""
1098: # Add a binding to refresh the line, which is unbound
1099: "\C-xr": redraw-current-line
1100: # Edit variable on current line.
1101: "\M-\C-v": "\C-a\C-k$\C-y\M-\C-e\C-a\C-y="
1102: $endif
1103:
1104: # use a visible bell if one is available
1105: set bell-style visible
1106:
1107: # don't strip characters to 7 bits when reading
1108: set input-meta on
1109:
1110: # allow iso-latin1 characters to be inserted rather
1111: # than converted to prefix-meta sequences
1112: set convert-meta off
1113:
1114: # display characters with the eighth bit set directly
1115: # rather than as meta-prefixed characters
1116: set output-meta on
1117:
1118: # if there are 150 or more possible completions for a word,
1119: # ask whether or not the user wants to see all of them
1120: set completion-query-items 150
1121:
1122: # For FTP
1123: $if Ftp
1124: "\C-xg": "get \M-?"
1125: "\C-xt": "put \M-?"
1126: "\M-.": yank-last-arg
1127: $endif
1128: @end example
1129:
1130: @node Bindable Readline Commands
1131: @section Bindable Readline Commands
1132:
1133: @menu
1134: * Commands For Moving:: Moving about the line.
1135: * Commands For History:: Getting at previous lines.
1136: * Commands For Text:: Commands for changing text.
1137: * Commands For Killing:: Commands for killing and yanking.
1138: * Numeric Arguments:: Specifying numeric arguments, repeat counts.
1139: * Commands For Completion:: Getting Readline to do the typing for you.
1140: * Keyboard Macros:: Saving and re-executing typed characters
1141: * Miscellaneous Commands:: Other miscellaneous commands.
1142: @end menu
1143:
1144: This section describes Readline commands that may be bound to key
1145: sequences.
1146: @ifset BashFeatures
1147: You can list your key bindings by executing
1148: @w{@code{bind -P}} or, for a more terse format, suitable for an
1149: @var{inputrc} file, @w{@code{bind -p}}. (@xref{Bash Builtins}.)
1150: @end ifset
1151: Command names without an accompanying key sequence are unbound by default.
1152:
1153: In the following descriptions, @dfn{point} refers to the current cursor
1154: position, and @dfn{mark} refers to a cursor position saved by the
1155: @code{set-mark} command.
1156: The text between the point and mark is referred to as the @dfn{region}.
1157:
1158: @node Commands For Moving
1159: @subsection Commands For Moving
1160: @ftable @code
1161: @item beginning-of-line (C-a)
1162: Move to the start of the current line.
1163:
1164: @item end-of-line (C-e)
1165: Move to the end of the line.
1166:
1167: @item forward-char (C-f)
1168: Move forward a character.
1169:
1170: @item backward-char (C-b)
1171: Move back a character.
1172:
1173: @item forward-word (M-f)
1174: Move forward to the end of the next word.
1175: Words are composed of letters and digits.
1176:
1177: @item backward-word (M-b)
1178: Move back to the start of the current or previous word.
1179: Words are composed of letters and digits.
1180:
1181: @ifset BashFeatures
1182: @item shell-forward-word (M-C-f)
1183: Move forward to the end of the next word.
1184: Words are delimited by non-quoted shell metacharacters.
1185:
1186: @item shell-backward-word (M-C-b)
1187: Move back to the start of the current or previous word.
1188: Words are delimited by non-quoted shell metacharacters.
1189: @end ifset
1190:
1191: @item previous-screen-line ()
1192: Attempt to move point to the same physical screen column on the previous
1193: physical screen line. This will not have the desired effect if the current
1194: Readline line does not take up more than one physical line or if point is not
1195: greater than the length of the prompt plus the screen width.
1196:
1197: @item next-screen-line ()
1198: Attempt to move point to the same physical screen column on the next
1199: physical screen line. This will not have the desired effect if the current
1200: Readline line does not take up more than one physical line or if the length
1201: of the current Readline line is not greater than the length of the prompt
1202: plus the screen width.
1203:
1204: @item clear-display (M-C-l)
1205: Clear the screen and, if possible, the terminal's scrollback buffer,
1206: then redraw the current line,
1207: leaving the current line at the top of the screen.
1208:
1209: @item clear-screen (C-l)
1210: Clear the screen,
1211: then redraw the current line,
1212: leaving the current line at the top of the screen.
1213:
1214: @item redraw-current-line ()
1215: Refresh the current line. By default, this is unbound.
1216:
1217: @end ftable
1218:
1219: @node Commands For History
1220: @subsection Commands For Manipulating The History
1221:
1222: @ftable @code
1223: @item accept-line (Newline or Return)
1224: @ifset BashFeatures
1225: Accept the line regardless of where the cursor is.
1226: If this line is
1227: non-empty, add it to the history list according to the setting of
1228: the @env{HISTCONTROL} and @env{HISTIGNORE} variables.
1229: If this line is a modified history line, then restore the history line
1230: to its original state.
1231: @end ifset
1232: @ifclear BashFeatures
1233: Accept the line regardless of where the cursor is.
1234: If this line is
1235: non-empty, it may be added to the history list for future recall with
1236: @code{add_history()}.
1237: If this line is a modified history line, the history line is restored
1238: to its original state.
1239: @end ifclear
1240:
1241: @item previous-history (C-p)
1242: Move `back' through the history list, fetching the previous command.
1243:
1244: @item next-history (C-n)
1245: Move `forward' through the history list, fetching the next command.
1246:
1247: @item beginning-of-history (M-<)
1248: Move to the first line in the history.
1249:
1250: @item end-of-history (M->)
1251: Move to the end of the input history, i.e., the line currently
1252: being entered.
1253:
1254: @item reverse-search-history (C-r)
1255: Search backward starting at the current line and moving `up' through
1256: the history as necessary. This is an incremental search.
1257: This command sets the region to the matched text and activates the mark.
1258:
1259: @item forward-search-history (C-s)
1260: Search forward starting at the current line and moving `down' through
1261: the history as necessary. This is an incremental search.
1262: This command sets the region to the matched text and activates the mark.
1263:
1264: @item non-incremental-reverse-search-history (M-p)
1265: Search backward starting at the current line and moving `up'
1266: through the history as necessary using a non-incremental search
1267: for a string supplied by the user.
1268: The search string may match anywhere in a history line.
1269:
1270: @item non-incremental-forward-search-history (M-n)
1271: Search forward starting at the current line and moving `down'
1272: through the history as necessary using a non-incremental search
1273: for a string supplied by the user.
1274: The search string may match anywhere in a history line.
1275:
1276: @item history-search-forward ()
1277: Search forward through the history for the string of characters
1278: between the start of the current line and the point.
1279: The search string must match at the beginning of a history line.
1280: This is a non-incremental search.
1281: By default, this command is unbound.
1282:
1283: @item history-search-backward ()
1284: Search backward through the history for the string of characters
1285: between the start of the current line and the point.
1286: The search string must match at the beginning of a history line.
1287: This is a non-incremental search.
1288: By default, this command is unbound.
1289:
1290: @item history-substring-search-forward ()
1291: Search forward through the history for the string of characters
1292: between the start of the current line and the point.
1293: The search string may match anywhere in a history line.
1294: This is a non-incremental search.
1295: By default, this command is unbound.
1296:
1297: @item history-substring-search-backward ()
1298: Search backward through the history for the string of characters
1299: between the start of the current line and the point.
1300: The search string may match anywhere in a history line.
1301: This is a non-incremental search.
1302: By default, this command is unbound.
1303:
1304: @item yank-nth-arg (M-C-y)
1305: Insert the first argument to the previous command (usually
1306: the second word on the previous line) at point.
1307: With an argument @var{n},
1308: insert the @var{n}th word from the previous command (the words
1309: in the previous command begin with word 0). A negative argument
1310: inserts the @var{n}th word from the end of the previous command.
1311: Once the argument @var{n} is computed, the argument is extracted
1312: as if the @samp{!@var{n}} history expansion had been specified.
1313:
1314: @item yank-last-arg (M-. or M-_)
1315: Insert last argument to the previous command (the last word of the
1316: previous history entry).
1317: With a numeric argument, behave exactly like @code{yank-nth-arg}.
1318: Successive calls to @code{yank-last-arg} move back through the history
1319: list, inserting the last word (or the word specified by the argument to
1320: the first call) of each line in turn.
1321: Any numeric argument supplied to these successive calls determines
1322: the direction to move through the history. A negative argument switches
1323: the direction through the history (back or forward).
1324: The history expansion facilities are used to extract the last argument,
1325: as if the @samp{!$} history expansion had been specified.
1326:
1327: @item operate-and-get-next (C-o)
1328: Accept the current line for return to the calling application as if a
1329: newline had been entered,
1330: and fetch the next line relative to the current line from the history
1331: for editing.
1332: A numeric argument, if supplied, specifies the history entry to use instead
1333: of the current line.
1334:
1335: @end ftable
1336:
1337: @node Commands For Text
1338: @subsection Commands For Changing Text
1339:
1340: @ftable @code
1341:
1342: @item @i{end-of-file} (usually C-d)
1343: The character indicating end-of-file as set, for example, by
1344: @code{stty}. If this character is read when there are no characters
1345: on the line, and point is at the beginning of the line, Readline
1346: interprets it as the end of input and returns @sc{eof}.
1347:
1348: @item delete-char (C-d)
1349: Delete the character at point. If this function is bound to the
1350: same character as the tty @sc{eof} character, as @kbd{C-d}
1351: commonly is, see above for the effects.
1352:
1353: @item backward-delete-char (Rubout)
1354: Delete the character behind the cursor. A numeric argument means
1355: to kill the characters instead of deleting them.
1356:
1357: @item forward-backward-delete-char ()
1358: Delete the character under the cursor, unless the cursor is at the
1359: end of the line, in which case the character behind the cursor is
1360: deleted. By default, this is not bound to a key.
1361:
1362: @item quoted-insert (C-q or C-v)
1363: Add the next character typed to the line verbatim. This is
1364: how to insert key sequences like @kbd{C-q}, for example.
1365:
1366: @ifclear BashFeatures
1367: @item tab-insert (M-@key{TAB})
1368: Insert a tab character.
1369: @end ifclear
1370:
1371: @item self-insert (a, b, A, 1, !, @dots{})
1372: Insert yourself.
1373:
1374: @item bracketed-paste-begin ()
1375: This function is intended to be bound to the "bracketed paste" escape
1376: sequence sent by some terminals, and such a binding is assigned by default.
1377: It allows Readline to insert the pasted text as a single unit without treating
1378: each character as if it had been read from the keyboard. The characters
1379: are inserted as if each one was bound to @code{self-insert} instead of
1380: executing any editing commands.
1381:
1382: Bracketed paste sets the region (the characters between point and the mark)
1383: to the inserted text. It uses the concept of an @emph{active mark}: when the
1384: mark is active, Readline redisplay uses the terminal's standout mode to
1385: denote the region.
1386:
1387: @item transpose-chars (C-t)
1388: Drag the character before the cursor forward over
1389: the character at the cursor, moving the
1390: cursor forward as well. If the insertion point
1391: is at the end of the line, then this
1392: transposes the last two characters of the line.
1393: Negative arguments have no effect.
1394:
1395: @item transpose-words (M-t)
1396: Drag the word before point past the word after point,
1397: moving point past that word as well.
1398: If the insertion point is at the end of the line, this transposes
1399: the last two words on the line.
1400:
1401: @item upcase-word (M-u)
1402: Uppercase the current (or following) word. With a negative argument,
1403: uppercase the previous word, but do not move the cursor.
1404:
1405: @item downcase-word (M-l)
1406: Lowercase the current (or following) word. With a negative argument,
1407: lowercase the previous word, but do not move the cursor.
1408:
1409: @item capitalize-word (M-c)
1410: Capitalize the current (or following) word. With a negative argument,
1411: capitalize the previous word, but do not move the cursor.
1412:
1413: @item overwrite-mode ()
1414: Toggle overwrite mode. With an explicit positive numeric argument,
1415: switches to overwrite mode. With an explicit non-positive numeric
1416: argument, switches to insert mode. This command affects only
1417: @code{emacs} mode; @code{vi} mode does overwrite differently.
1418: Each call to @code{readline()} starts in insert mode.
1419:
1420: In overwrite mode, characters bound to @code{self-insert} replace
1421: the text at point rather than pushing the text to the right.
1422: Characters bound to @code{backward-delete-char} replace the character
1423: before point with a space.
1424:
1425: By default, this command is unbound.
1426:
1427: @end ftable
1428:
1429: @node Commands For Killing
1430: @subsection Killing And Yanking
1431:
1432: @ftable @code
1433:
1434: @item kill-line (C-k)
1435: Kill the text from point to the end of the line.
1436: With a negative numeric argument, kill backward from the cursor to the
1437: beginning of the current line.
1438:
1439: @item backward-kill-line (C-x Rubout)
1440: Kill backward from the cursor to the beginning of the current line.
1441: With a negative numeric argument, kill forward from the cursor to the
1442: end of the current line.
1443:
1444: @item unix-line-discard (C-u)
1445: Kill backward from the cursor to the beginning of the current line.
1446:
1447: @item kill-whole-line ()
1448: Kill all characters on the current line, no matter where point is.
1449: By default, this is unbound.
1450:
1451: @item kill-word (M-d)
1452: Kill from point to the end of the current word, or if between
1453: words, to the end of the next word.
1454: Word boundaries are the same as @code{forward-word}.
1455:
1456: @item backward-kill-word (M-@key{DEL})
1457: Kill the word behind point.
1458: Word boundaries are the same as @code{backward-word}.
1459:
1460: @ifset BashFeatures
1461: @item shell-kill-word (M-C-d)
1462: Kill from point to the end of the current word, or if between
1463: words, to the end of the next word.
1464: Word boundaries are the same as @code{shell-forward-word}.
1465:
1466: @item shell-backward-kill-word ()
1467: Kill the word behind point.
1468: Word boundaries are the same as @code{shell-backward-word}.
1469: @end ifset
1470:
1471: @item shell-transpose-words (M-C-t)
1472: Drag the word before point past the word after point,
1473: moving point past that word as well.
1474: If the insertion point is at the end of the line, this transposes
1475: the last two words on the line.
1476: Word boundaries are the same as @code{shell-forward-word} and
1477: @code{shell-backward-word}.
1478:
1479: @item unix-word-rubout (C-w)
1480: Kill the word behind point, using white space as a word boundary.
1481: The killed text is saved on the kill-ring.
1482:
1483: @item unix-filename-rubout ()
1484: Kill the word behind point, using white space and the slash character
1485: as the word boundaries.
1486: The killed text is saved on the kill-ring.
1487:
1488: @item delete-horizontal-space ()
1489: Delete all spaces and tabs around point. By default, this is unbound.
1490:
1491: @item kill-region ()
1492: Kill the text in the current region.
1493: By default, this command is unbound.
1494:
1495: @item copy-region-as-kill ()
1496: Copy the text in the region to the kill buffer, so it can be yanked
1497: right away. By default, this command is unbound.
1498:
1499: @item copy-backward-word ()
1500: Copy the word before point to the kill buffer.
1501: The word boundaries are the same as @code{backward-word}.
1502: By default, this command is unbound.
1503:
1504: @item copy-forward-word ()
1505: Copy the word following point to the kill buffer.
1506: The word boundaries are the same as @code{forward-word}.
1507: By default, this command is unbound.
1508:
1509: @item yank (C-y)
1510: Yank the top of the kill ring into the buffer at point.
1511:
1512: @item yank-pop (M-y)
1513: Rotate the kill-ring, and yank the new top. You can only do this if
1514: the prior command is @code{yank} or @code{yank-pop}.
1515: @end ftable
1516:
1517: @node Numeric Arguments
1518: @subsection Specifying Numeric Arguments
1519: @ftable @code
1520:
1521: @item digit-argument (@kbd{M-0}, @kbd{M-1}, @dots{} @kbd{M--})
1522: Add this digit to the argument already accumulating, or start a new
1523: argument. @kbd{M--} starts a negative argument.
1524:
1525: @item universal-argument ()
1526: This is another way to specify an argument.
1527: If this command is followed by one or more digits, optionally with a
1528: leading minus sign, those digits define the argument.
1529: If the command is followed by digits, executing @code{universal-argument}
1530: again ends the numeric argument, but is otherwise ignored.
1531: As a special case, if this command is immediately followed by a
1532: character that is neither a digit nor minus sign, the argument count
1533: for the next command is multiplied by four.
1534: The argument count is initially one, so executing this function the
1535: first time makes the argument count four, a second time makes the
1536: argument count sixteen, and so on.
1537: By default, this is not bound to a key.
1538: @end ftable
1539:
1540: @node Commands For Completion
1541: @subsection Letting Readline Type For You
1542:
1543: @ftable @code
1544: @item complete (@key{TAB})
1545: Attempt to perform completion on the text before point.
1546: The actual completion performed is application-specific.
1547: @ifset BashFeatures
1548: Bash attempts completion treating the text as a variable (if the
1549: text begins with @samp{$}), username (if the text begins with
1550: @samp{~}), hostname (if the text begins with @samp{@@}), or
1551: command (including aliases and functions) in turn. If none
1552: of these produces a match, filename completion is attempted.
1553: @end ifset
1554: @ifclear BashFeatures
1555: The default is filename completion.
1556: @end ifclear
1557:
1558: @item possible-completions (M-?)
1559: List the possible completions of the text before point.
1560: When displaying completions, Readline sets the number of columns used
1561: for display to the value of @code{completion-display-width}, the value of
1562: the environment variable @env{COLUMNS}, or the screen width, in that order.
1563:
1564: @item insert-completions (M-*)
1565: Insert all completions of the text before point that would have
1566: been generated by @code{possible-completions}.
1567:
1568: @item menu-complete ()
1569: Similar to @code{complete}, but replaces the word to be completed
1570: with a single match from the list of possible completions.
1571: Repeated execution of @code{menu-complete} steps through the list
1572: of possible completions, inserting each match in turn.
1573: At the end of the list of completions, the bell is rung
1574: (subject to the setting of @code{bell-style})
1575: and the original text is restored.
1576: An argument of @var{n} moves @var{n} positions forward in the list
1577: of matches; a negative argument may be used to move backward
1578: through the list.
1579: This command is intended to be bound to @key{TAB}, but is unbound
1580: by default.
1581:
1582: @item menu-complete-backward ()
1583: Identical to @code{menu-complete}, but moves backward through the list
1584: of possible completions, as if @code{menu-complete} had been given a
1585: negative argument.
1586:
1587: @item delete-char-or-list ()
1588: Deletes the character under the cursor if not at the beginning or
1589: end of the line (like @code{delete-char}).
1590: If at the end of the line, behaves identically to
1591: @code{possible-completions}.
1592: This command is unbound by default.
1593:
1594: @ifset BashFeatures
1595: @item complete-filename (M-/)
1596: Attempt filename completion on the text before point.
1597:
1598: @item possible-filename-completions (C-x /)
1599: List the possible completions of the text before point,
1600: treating it as a filename.
1601:
1602: @item complete-username (M-~)
1603: Attempt completion on the text before point, treating
1604: it as a username.
1605:
1606: @item possible-username-completions (C-x ~)
1607: List the possible completions of the text before point,
1608: treating it as a username.
1609:
1610: @item complete-variable (M-$)
1611: Attempt completion on the text before point, treating
1612: it as a shell variable.
1613:
1614: @item possible-variable-completions (C-x $)
1615: List the possible completions of the text before point,
1616: treating it as a shell variable.
1617:
1618: @item complete-hostname (M-@@)
1619: Attempt completion on the text before point, treating
1620: it as a hostname.
1621:
1622: @item possible-hostname-completions (C-x @@)
1623: List the possible completions of the text before point,
1624: treating it as a hostname.
1625:
1626: @item complete-command (M-!)
1627: Attempt completion on the text before point, treating
1628: it as a command name. Command completion attempts to
1629: match the text against aliases, reserved words, shell
1630: functions, shell builtins, and finally executable filenames,
1631: in that order.
1632:
1633: @item possible-command-completions (C-x !)
1634: List the possible completions of the text before point,
1635: treating it as a command name.
1636:
1637: @item dynamic-complete-history (M-@key{TAB})
1638: Attempt completion on the text before point, comparing
1639: the text against lines from the history list for possible
1640: completion matches.
1641:
1642: @item dabbrev-expand ()
1643: Attempt menu completion on the text before point, comparing
1644: the text against lines from the history list for possible
1645: completion matches.
1646:
1647: @item complete-into-braces (M-@{)
1648: Perform filename completion and insert the list of possible completions
1649: enclosed within braces so the list is available to the shell
1650: (@pxref{Brace Expansion}).
1651:
1652: @end ifset
1653: @end ftable
1654:
1655: @node Keyboard Macros
1656: @subsection Keyboard Macros
1657: @ftable @code
1658:
1659: @item start-kbd-macro (C-x ()
1660: Begin saving the characters typed into the current keyboard macro.
1661:
1662: @item end-kbd-macro (C-x ))
1663: Stop saving the characters typed into the current keyboard macro
1664: and save the definition.
1665:
1666: @item call-last-kbd-macro (C-x e)
1667: Re-execute the last keyboard macro defined, by making the characters
1668: in the macro appear as if typed at the keyboard.
1669:
1670: @item print-last-kbd-macro ()
1671: Print the last keboard macro defined in a format suitable for the
1672: @var{inputrc} file.
1673:
1674: @end ftable
1675:
1676: @node Miscellaneous Commands
1677: @subsection Some Miscellaneous Commands
1678: @ftable @code
1679:
1680: @item re-read-init-file (C-x C-r)
1681: Read in the contents of the @var{inputrc} file, and incorporate
1682: any bindings or variable assignments found there.
1683:
1684: @item abort (C-g)
1685: Abort the current editing command and
1686: ring the terminal's bell (subject to the setting of
1687: @code{bell-style}).
1688:
1689: @item do-lowercase-version (M-A, M-B, M-@var{x}, @dots{})
1690: If the metafied character @var{x} is upper case, run the command
1691: that is bound to the corresponding metafied lower case character.
1692: The behavior is undefined if @var{x} is already lower case.
1693:
1694: @item prefix-meta (@key{ESC})
1695: Metafy the next character typed. This is for keyboards
1696: without a meta key. Typing @samp{@key{ESC} f} is equivalent to typing
1697: @kbd{M-f}.
1698:
1699: @item undo (C-_ or C-x C-u)
1700: Incremental undo, separately remembered for each line.
1701:
1702: @item revert-line (M-r)
1703: Undo all changes made to this line. This is like executing the @code{undo}
1704: command enough times to get back to the beginning.
1705:
1706: @ifset BashFeatures
1707: @item tilde-expand (M-&)
1708: @end ifset
1709: @ifclear BashFeatures
1710: @item tilde-expand (M-~)
1711: @end ifclear
1712: Perform tilde expansion on the current word.
1713:
1714: @item set-mark (C-@@)
1715: Set the mark to the point. If a
1716: numeric argument is supplied, the mark is set to that position.
1717:
1718: @item exchange-point-and-mark (C-x C-x)
1719: Swap the point with the mark. The current cursor position is set to
1720: the saved position, and the old cursor position is saved as the mark.
1721:
1722: @item character-search (C-])
1723: A character is read and point is moved to the next occurrence of that
1724: character. A negative count searches for previous occurrences.
1725:
1726: @item character-search-backward (M-C-])
1727: A character is read and point is moved to the previous occurrence
1728: of that character. A negative count searches for subsequent
1729: occurrences.
1730:
1731: @item skip-csi-sequence ()
1732: Read enough characters to consume a multi-key sequence such as those
1733: defined for keys like Home and End. Such sequences begin with a
1734: Control Sequence Indicator (CSI), usually ESC-[. If this sequence is
1735: bound to "\e[", keys producing such sequences will have no effect
1736: unless explicitly bound to a readline command, instead of inserting
1737: stray characters into the editing buffer. This is unbound by default,
1738: but usually bound to ESC-[.
1739:
1740: @item insert-comment (M-#)
1741: Without a numeric argument, the value of the @code{comment-begin}
1742: variable is inserted at the beginning of the current line.
1743: If a numeric argument is supplied, this command acts as a toggle: if
1744: the characters at the beginning of the line do not match the value
1745: of @code{comment-begin}, the value is inserted, otherwise
1746: the characters in @code{comment-begin} are deleted from the beginning of
1747: the line.
1748: In either case, the line is accepted as if a newline had been typed.
1749: @ifset BashFeatures
1750: The default value of @code{comment-begin} causes this command
1751: to make the current line a shell comment.
1752: If a numeric argument causes the comment character to be removed, the line
1753: will be executed by the shell.
1754: @end ifset
1755:
1756: @item dump-functions ()
1757: Print all of the functions and their key bindings to the
1758: Readline output stream. If a numeric argument is supplied,
1759: the output is formatted in such a way that it can be made part
1760: of an @var{inputrc} file. This command is unbound by default.
1761:
1762: @item dump-variables ()
1763: Print all of the settable variables and their values to the
1764: Readline output stream. If a numeric argument is supplied,
1765: the output is formatted in such a way that it can be made part
1766: of an @var{inputrc} file. This command is unbound by default.
1767:
1768: @item dump-macros ()
1769: Print all of the Readline key sequences bound to macros and the
1770: strings they output. If a numeric argument is supplied,
1771: the output is formatted in such a way that it can be made part
1772: of an @var{inputrc} file. This command is unbound by default.
1773:
1774: @ifset BashFeatures
1775: @item glob-complete-word (M-g)
1776: The word before point is treated as a pattern for pathname expansion,
1777: with an asterisk implicitly appended. This pattern is used to
1778: generate a list of matching file names for possible completions.
1779:
1780: @item glob-expand-word (C-x *)
1781: The word before point is treated as a pattern for pathname expansion,
1782: and the list of matching file names is inserted, replacing the word.
1783: If a numeric argument is supplied, a @samp{*} is appended before
1784: pathname expansion.
1785:
1786: @item glob-list-expansions (C-x g)
1787: The list of expansions that would have been generated by
1788: @code{glob-expand-word} is displayed, and the line is redrawn.
1789: If a numeric argument is supplied, a @samp{*} is appended before
1790: pathname expansion.
1791:
1792: @item display-shell-version (C-x C-v)
1793: Display version information about the current instance of Bash.
1794:
1795: @item shell-expand-line (M-C-e)
1796: Expand the line as the shell does.
1797: This performs alias and history expansion as well as all of the shell
1798: word expansions (@pxref{Shell Expansions}).
1799:
1800: @item history-expand-line (M-^)
1801: Perform history expansion on the current line.
1802:
1803: @item magic-space ()
1804: Perform history expansion on the current line and insert a space
1805: (@pxref{History Interaction}).
1806:
1807: @item alias-expand-line ()
1808: Perform alias expansion on the current line (@pxref{Aliases}).
1809:
1810: @item history-and-alias-expand-line ()
1811: Perform history and alias expansion on the current line.
1812:
1813: @item insert-last-argument (M-. or M-_)
1814: A synonym for @code{yank-last-arg}.
1815:
1816: @item edit-and-execute-command (C-x C-e)
1817: Invoke an editor on the current command line, and execute the result as shell
1818: commands.
1819: Bash attempts to invoke
1820: @code{$VISUAL}, @code{$EDITOR}, and @code{emacs}
1821: as the editor, in that order.
1822:
1823: @end ifset
1824:
1825: @ifclear BashFeatures
1826: @item emacs-editing-mode (C-e)
1827: When in @code{vi} command mode, this causes a switch to @code{emacs}
1828: editing mode.
1829:
1830: @item vi-editing-mode (M-C-j)
1831: When in @code{emacs} editing mode, this causes a switch to @code{vi}
1832: editing mode.
1833:
1834: @end ifclear
1835:
1836: @end ftable
1837:
1838: @node Readline vi Mode
1839: @section Readline vi Mode
1840:
1841: While the Readline library does not have a full set of @code{vi}
1842: editing functions, it does contain enough to allow simple editing
1843: of the line. The Readline @code{vi} mode behaves as specified in
1844: the @sc{posix} standard.
1845:
1846: @ifset BashFeatures
1847: In order to switch interactively between @code{emacs} and @code{vi}
1848: editing modes, use the @samp{set -o emacs} and @samp{set -o vi}
1849: commands (@pxref{The Set Builtin}).
1850: @end ifset
1851: @ifclear BashFeatures
1852: In order to switch interactively between @code{emacs} and @code{vi}
1853: editing modes, use the command @kbd{M-C-j} (bound to emacs-editing-mode
1854: when in @code{vi} mode and to vi-editing-mode in @code{emacs} mode).
1855: @end ifclear
1856: The Readline default is @code{emacs} mode.
1857:
1858: When you enter a line in @code{vi} mode, you are already placed in
1859: `insertion' mode, as if you had typed an @samp{i}. Pressing @key{ESC}
1860: switches you into `command' mode, where you can edit the text of the
1861: line with the standard @code{vi} movement keys, move to previous
1862: history lines with @samp{k} and subsequent lines with @samp{j}, and
1863: so forth.
1864:
1865: @ifset BashFeatures
1866: @node Programmable Completion
1867: @section Programmable Completion
1868: @cindex programmable completion
1869:
1870: When word completion is attempted for an argument to a command for
1871: which a completion specification (a @var{compspec}) has been defined
1872: using the @code{complete} builtin (@pxref{Programmable Completion Builtins}),
1873: the programmable completion facilities are invoked.
1874:
1875: First, the command name is identified.
1876: If a compspec has been defined for that command, the
1877: compspec is used to generate the list of possible completions for the word.
1878: If the command word is the empty string (completion attempted at the
1879: beginning of an empty line), any compspec defined with
1880: the @option{-E} option to @code{complete} is used.
1881: If the command word is a full pathname, a compspec for the full
1882: pathname is searched for first.
1883: If no compspec is found for the full pathname, an attempt is made to
1884: find a compspec for the portion following the final slash.
1885: If those searches do not result in a compspec, any compspec defined with
1886: the @option{-D} option to @code{complete} is used as the default.
1887: If there is no default compspec, Bash attempts alias expansion
1888: on the command word as a final resort, and attempts to find a compspec
1889: for the command word from any successful expansion
1890:
1891: Once a compspec has been found, it is used to generate the list of
1892: matching words.
1893: If a compspec is not found, the default Bash completion
1894: described above (@pxref{Commands For Completion}) is performed.
1895:
1896: First, the actions specified by the compspec are used.
1897: Only matches which are prefixed by the word being completed are
1898: returned.
1899: When the @option{-f} or @option{-d} option is used for filename or
1900: directory name completion, the shell variable @env{FIGNORE} is
1901: used to filter the matches.
1902: @xref{Bash Variables}, for a description of @env{FIGNORE}.
1903:
1904: Any completions specified by a filename expansion pattern to the
1905: @option{-G} option are generated next.
1906: The words generated by the pattern need not match the word being completed.
1907: The @env{GLOBIGNORE} shell variable is not used to filter the matches,
1908: but the @env{FIGNORE} shell variable is used.
1909:
1910: Next, the string specified as the argument to the @option{-W} option
1911: is considered.
1912: The string is first split using the characters in the @env{IFS}
1913: special variable as delimiters.
1914: Shell quoting is honored within the string, in order to provide a
1915: mechanism for the words to contain shell metacharacters or characters
1916: in the value of @env{IFS}.
1917: Each word is then expanded using
1918: brace expansion, tilde expansion, parameter and variable expansion,
1919: command substitution, and arithmetic expansion,
1920: as described above (@pxref{Shell Expansions}).
1921: The results are split using the rules described above
1922: (@pxref{Word Splitting}).
1923: The results of the expansion are prefix-matched against the word being
1924: completed, and the matching words become the possible completions.
1925:
1926: After these matches have been generated, any shell function or command
1927: specified with the @option{-F} and @option{-C} options is invoked.
1928: When the command or function is invoked, the @env{COMP_LINE},
1929: @env{COMP_POINT}, @env{COMP_KEY}, and @env{COMP_TYPE} variables are
1930: assigned values as described above (@pxref{Bash Variables}).
1931: If a shell function is being invoked, the @env{COMP_WORDS} and
1932: @env{COMP_CWORD} variables are also set.
1933: When the function or command is invoked, the first argument ($1) is the
1934: name of the command whose arguments are being completed, the
1935: second argument ($2) is the word being completed, and the third argument
1936: ($3) is the word preceding the word being completed on the current command
1937: line.
1938: No filtering of the generated completions against the word being completed
1939: is performed; the function or command has complete freedom in generating
1940: the matches.
1941:
1942: Any function specified with @option{-F} is invoked first.
1943: The function may use any of the shell facilities, including the
1944: @code{compgen} and @code{compopt} builtins described below
1945: (@pxref{Programmable Completion Builtins}), to generate the matches.
1946: It must put the possible completions in the @env{COMPREPLY} array
1947: variable, one per array element.
1948:
1949: Next, any command specified with the @option{-C} option is invoked
1950: in an environment equivalent to command substitution.
1951: It should print a list of completions, one per line, to
1952: the standard output.
1953: Backslash may be used to escape a newline, if necessary.
1954:
1955: After all of the possible completions are generated, any filter
1956: specified with the @option{-X} option is applied to the list.
1957: The filter is a pattern as used for pathname expansion; a @samp{&}
1958: in the pattern is replaced with the text of the word being completed.
1959: A literal @samp{&} may be escaped with a backslash; the backslash
1960: is removed before attempting a match.
1961: Any completion that matches the pattern will be removed from the list.
1962: A leading @samp{!} negates the pattern; in this case any completion
1963: not matching the pattern will be removed.
1964: If the @code{nocasematch} shell option
1965: (see the description of @code{shopt} in @ref{The Shopt Builtin})
1966: is enabled, the match is performed without regard to the case
1967: of alphabetic characters.
1968:
1969: Finally, any prefix and suffix specified with the @option{-P} and @option{-S}
1970: options are added to each member of the completion list, and the result is
1971: returned to the Readline completion code as the list of possible
1972: completions.
1973:
1974: If the previously-applied actions do not generate any matches, and the
1975: @option{-o dirnames} option was supplied to @code{complete} when the
1976: compspec was defined, directory name completion is attempted.
1977:
1978: If the @option{-o plusdirs} option was supplied to @code{complete} when
1979: the compspec was defined, directory name completion is attempted and any
1980: matches are added to the results of the other actions.
1981:
1982: By default, if a compspec is found, whatever it generates is returned to
1983: the completion code as the full set of possible completions.
1984: The default Bash completions are not attempted, and the Readline default
1985: of filename completion is disabled.
1986: If the @option{-o bashdefault} option was supplied to @code{complete} when
1987: the compspec was defined, the default Bash completions are attempted
1988: if the compspec generates no matches.
1989: If the @option{-o default} option was supplied to @code{complete} when the
1990: compspec was defined, Readline's default completion will be performed
1991: if the compspec (and, if attempted, the default Bash completions)
1992: generate no matches.
1993:
1994: When a compspec indicates that directory name completion is desired,
1995: the programmable completion functions force Readline to append a slash
1996: to completed names which are symbolic links to directories, subject to
1997: the value of the @var{mark-directories} Readline variable, regardless
1998: of the setting of the @var{mark-symlinked-directories} Readline variable.
1999:
2000: There is some support for dynamically modifying completions. This is
2001: most useful when used in combination with a default completion specified
2002: with @option{-D}. It's possible for shell functions executed as completion
2003: handlers to indicate that completion should be retried by returning an
2004: exit status of 124. If a shell function returns 124, and changes
2005: the compspec associated with the command on which completion is being
2006: attempted (supplied as the first argument when the function is executed),
2007: programmable completion restarts from the beginning, with an
2008: attempt to find a new compspec for that command. This allows a set of
2009: completions to be built dynamically as completion is attempted, rather than
2010: being loaded all at once.
2011:
2012: For instance, assuming that there is a library of compspecs, each kept in a
2013: file corresponding to the name of the command, the following default
2014: completion function would load completions dynamically:
2015:
2016: @example
2017: _completion_loader()
2018: @{
2019: . "/etc/bash_completion.d/$1.sh" >/dev/null 2>&1 && return 124
2020: @}
2021: complete -D -F _completion_loader -o bashdefault -o default
2022: @end example
2023:
2024: @node Programmable Completion Builtins
2025: @section Programmable Completion Builtins
2026: @cindex completion builtins
2027:
2028: Three builtin commands are available to manipulate the programmable completion
2029: facilities: one to specify how the arguments to a particular command are to
2030: be completed, and two to modify the completion as it is happening.
2031:
2032: @table @code
2033: @item compgen
2034: @btindex compgen
2035: @example
2036: @code{compgen [@var{option}] [@var{word}]}
2037: @end example
2038:
2039: Generate possible completion matches for @var{word} according to
2040: the @var{option}s, which may be any option accepted by the
2041: @code{complete}
2042: builtin with the exception of @option{-p} and @option{-r}, and write
2043: the matches to the standard output.
2044: When using the @option{-F} or @option{-C} options, the various shell variables
2045: set by the programmable completion facilities, while available, will not
2046: have useful values.
2047:
2048: The matches will be generated in the same way as if the programmable
2049: completion code had generated them directly from a completion specification
2050: with the same flags.
2051: If @var{word} is specified, only those completions matching @var{word}
2052: will be displayed.
2053:
2054: The return value is true unless an invalid option is supplied, or no
2055: matches were generated.
2056:
2057: @item complete
2058: @btindex complete
2059: @example
2060: @code{complete [-abcdefgjksuv] [-o @var{comp-option}] [-DEI] [-A @var{action}] [-G @var{globpat}]
2061: [-W @var{wordlist}] [-F @var{function}] [-C @var{command}] [-X @var{filterpat}]
2062: [-P @var{prefix}] [-S @var{suffix}] @var{name} [@var{name} @dots{}]}
2063: @code{complete -pr [-DEI] [@var{name} @dots{}]}
2064: @end example
2065:
2066: Specify how arguments to each @var{name} should be completed.
2067: If the @option{-p} option is supplied, or if no options are supplied, existing
2068: completion specifications are printed in a way that allows them to be
2069: reused as input.
2070: The @option{-r} option removes a completion specification for
2071: each @var{name}, or, if no @var{name}s are supplied, all
2072: completion specifications.
2073: The @option{-D} option indicates that other supplied options and actions should
2074: apply to the ``default'' command completion; that is, completion attempted
2075: on a command for which no completion has previously been defined.
2076: The @option{-E} option indicates that other supplied options and actions should
2077: apply to ``empty'' command completion; that is, completion attempted on a
2078: blank line.
2079: The @option{-I} option indicates that other supplied options and actions should
2080: apply to completion on the initial non-assignment word on the line, or after a
2081: command delimiter such as @samp{;} or @samp{|}, which is usually command
2082: name completion.
2083: If multiple options are supplied, the @option{-D} option takes precedence
2084: over @option{-E}, and both take precedence over @option{-I}.
2085: If any of @option{-D}, @option{-E}, or @option{-I} are supplied, any other
2086: @var{name} arguments are ignored; these completions only apply to the case
2087: specified by the option.
2088:
2089: The process of applying these completion specifications when word completion
2090: is attempted is described above (@pxref{Programmable Completion}).
2091:
2092: Other options, if specified, have the following meanings.
2093: The arguments to the @option{-G}, @option{-W}, and @option{-X} options
2094: (and, if necessary, the @option{-P} and @option{-S} options)
2095: should be quoted to protect them from expansion before the
2096: @code{complete} builtin is invoked.
2097:
2098:
2099: @table @code
2100: @item -o @var{comp-option}
2101: The @var{comp-option} controls several aspects of the compspec's behavior
2102: beyond the simple generation of completions.
2103: @var{comp-option} may be one of:
2104:
2105: @table @code
2106:
2107: @item bashdefault
2108: Perform the rest of the default Bash completions if the compspec
2109: generates no matches.
2110:
2111: @item default
2112: Use Readline's default filename completion if the compspec generates
2113: no matches.
2114:
2115: @item dirnames
2116: Perform directory name completion if the compspec generates no matches.
2117:
2118: @item filenames
2119: Tell Readline that the compspec generates filenames, so it can perform any
2120: filename-specific processing (like adding a slash to directory names,
2121: quoting special characters, or suppressing trailing spaces).
2122: This option is intended to be used with shell functions specified
2123: with @option{-F}.
2124:
2125: @item noquote
2126: Tell Readline not to quote the completed words if they are filenames
2127: (quoting filenames is the default).
2128:
2129: @item nosort
2130: Tell Readline not to sort the list of possible completions alphabetically.
2131:
2132: @item nospace
2133: Tell Readline not to append a space (the default) to words completed at
2134: the end of the line.
2135:
2136: @item plusdirs
2137: After any matches defined by the compspec are generated,
2138: directory name completion is attempted and any
2139: matches are added to the results of the other actions.
2140:
2141: @end table
2142:
2143: @item -A @var{action}
2144: The @var{action} may be one of the following to generate a list of possible
2145: completions:
2146:
2147: @table @code
2148: @item alias
2149: Alias names. May also be specified as @option{-a}.
2150:
2151: @item arrayvar
2152: Array variable names.
2153:
2154: @item binding
2155: Readline key binding names (@pxref{Bindable Readline Commands}).
2156:
2157: @item builtin
2158: Names of shell builtin commands. May also be specified as @option{-b}.
2159:
2160: @item command
2161: Command names. May also be specified as @option{-c}.
2162:
2163: @item directory
2164: Directory names. May also be specified as @option{-d}.
2165:
2166: @item disabled
2167: Names of disabled shell builtins.
2168:
2169: @item enabled
2170: Names of enabled shell builtins.
2171:
2172: @item export
2173: Names of exported shell variables. May also be specified as @option{-e}.
2174:
2175: @item file
2176: File names. May also be specified as @option{-f}.
2177:
2178: @item function
2179: Names of shell functions.
2180:
2181: @item group
2182: Group names. May also be specified as @option{-g}.
2183:
2184: @item helptopic
2185: Help topics as accepted by the @code{help} builtin (@pxref{Bash Builtins}).
2186:
2187: @item hostname
2188: Hostnames, as taken from the file specified by the
2189: @env{HOSTFILE} shell variable (@pxref{Bash Variables}).
2190:
2191: @item job
2192: Job names, if job control is active. May also be specified as @option{-j}.
2193:
2194: @item keyword
2195: Shell reserved words. May also be specified as @option{-k}.
2196:
2197: @item running
2198: Names of running jobs, if job control is active.
2199:
2200: @item service
2201: Service names. May also be specified as @option{-s}.
2202:
2203: @item setopt
2204: Valid arguments for the @option{-o} option to the @code{set} builtin
2205: (@pxref{The Set Builtin}).
2206:
2207: @item shopt
2208: Shell option names as accepted by the @code{shopt} builtin
2209: (@pxref{Bash Builtins}).
2210:
2211: @item signal
2212: Signal names.
2213:
2214: @item stopped
2215: Names of stopped jobs, if job control is active.
2216:
2217: @item user
2218: User names. May also be specified as @option{-u}.
2219:
2220: @item variable
2221: Names of all shell variables. May also be specified as @option{-v}.
2222: @end table
2223:
2224: @item -C @var{command}
2225: @var{command} is executed in a subshell environment, and its output is
2226: used as the possible completions.
2227:
2228: @item -F @var{function}
2229: The shell function @var{function} is executed in the current shell
2230: environment.
2231: When it is executed, $1 is the name of the command whose arguments are
2232: being completed, $2 is the word being completed, and $3 is the word
2233: preceding the word being completed, as described above
2234: (@pxref{Programmable Completion}).
2235: When it finishes, the possible completions are retrieved from the value
2236: of the @env{COMPREPLY} array variable.
2237:
2238: @item -G @var{globpat}
2239: The filename expansion pattern @var{globpat} is expanded to generate
2240: the possible completions.
2241:
2242: @item -P @var{prefix}
2243: @var{prefix} is added at the beginning of each possible completion
2244: after all other options have been applied.
2245:
2246: @item -S @var{suffix}
2247: @var{suffix} is appended to each possible completion
2248: after all other options have been applied.
2249:
2250: @item -W @var{wordlist}
2251: The @var{wordlist} is split using the characters in the
2252: @env{IFS} special variable as delimiters, and each resultant word
2253: is expanded.
2254: The possible completions are the members of the resultant list which
2255: match the word being completed.
2256:
2257: @item -X @var{filterpat}
2258: @var{filterpat} is a pattern as used for filename expansion.
2259: It is applied to the list of possible completions generated by the
2260: preceding options and arguments, and each completion matching
2261: @var{filterpat} is removed from the list.
2262: A leading @samp{!} in @var{filterpat} negates the pattern; in this
2263: case, any completion not matching @var{filterpat} is removed.
2264: @end table
2265:
2266: The return value is true unless an invalid option is supplied, an option
2267: other than @option{-p} or @option{-r} is supplied without a @var{name}
2268: argument, an attempt is made to remove a completion specification for
2269: a @var{name} for which no specification exists, or
2270: an error occurs adding a completion specification.
2271:
2272: @item compopt
2273: @btindex compopt
2274: @example
2275: @code{compopt} [-o @var{option}] [-DEI] [+o @var{option}] [@var{name}]
2276: @end example
2277: Modify completion options for each @var{name} according to the
2278: @var{option}s, or for the currently-executing completion if no @var{name}s
2279: are supplied.
2280: If no @var{option}s are given, display the completion options for each
2281: @var{name} or the current completion.
2282: The possible values of @var{option} are those valid for the @code{complete}
2283: builtin described above.
2284: The @option{-D} option indicates that other supplied options should
2285: apply to the ``default'' command completion; that is, completion attempted
2286: on a command for which no completion has previously been defined.
2287: The @option{-E} option indicates that other supplied options should
2288: apply to ``empty'' command completion; that is, completion attempted on a
2289: blank line.
2290: The @option{-I} option indicates that other supplied options should
2291: apply to completion on the initial non-assignment word on the line, or after a
2292: command delimiter such as @samp{;} or @samp{|}, which is usually command
2293: name completion.
2294:
2295: If multiple options are supplied, the @option{-D} option takes precedence
2296: over @option{-E}, and both take precedence over @option{-I}
2297:
2298: The return value is true unless an invalid option is supplied, an attempt
2299: is made to modify the options for a @var{name} for which no completion
2300: specification exists, or an output error occurs.
2301:
2302: @end table
2303:
2304: @node A Programmable Completion Example
2305: @section A Programmable Completion Example
2306:
2307: The most common way to obtain additional completion functionality beyond
2308: the default actions @code{complete} and @code{compgen} provide is to use
2309: a shell function and bind it to a particular command using @code{complete -F}.
2310:
2311: The following function provides completions for the @code{cd} builtin.
2312: It is a reasonably good example of what shell functions must do when
2313: used for completion. This function uses the word passed as @code{$2}
2314: to determine the directory name to complete. You can also use the
2315: @code{COMP_WORDS} array variable; the current word is indexed by the
2316: @code{COMP_CWORD} variable.
2317:
2318: The function relies on the @code{complete} and @code{compgen} builtins
2319: to do much of the work, adding only the things that the Bash @code{cd}
2320: does beyond accepting basic directory names:
2321: tilde expansion (@pxref{Tilde Expansion}),
2322: searching directories in @var{$CDPATH}, which is described above
2323: (@pxref{Bourne Shell Builtins}),
2324: and basic support for the @code{cdable_vars} shell option
2325: (@pxref{The Shopt Builtin}).
2326: @code{_comp_cd} modifies the value of @var{IFS} so that it contains only
2327: a newline to accommodate file names containing spaces and tabs --
2328: @code{compgen} prints the possible completions it generates one per line.
2329:
2330: Possible completions go into the @var{COMPREPLY} array variable, one
2331: completion per array element. The programmable completion system retrieves
2332: the completions from there when the function returns.
2333:
2334: @example
2335: # A completion function for the cd builtin
2336: # based on the cd completion function from the bash_completion package
2337: _comp_cd()
2338: @{
2339: local IFS=$' \t\n' # normalize IFS
2340: local cur _skipdot _cdpath
2341: local i j k
2342:
2343: # Tilde expansion, which also expands tilde to full pathname
2344: case "$2" in
2345: \~*) eval cur="$2" ;;
2346: *) cur=$2 ;;
2347: esac
2348:
2349: # no cdpath or absolute pathname -- straight directory completion
2350: if [[ -z "$@{CDPATH:-@}" ]] || [[ "$cur" == @@(./*|../*|/*) ]]; then
2351: # compgen prints paths one per line; could also use while loop
2352: IFS=$'\n'
2353: COMPREPLY=( $(compgen -d -- "$cur") )
2354: IFS=$' \t\n'
2355: # CDPATH+directories in the current directory if not in CDPATH
2356: else
2357: IFS=$'\n'
2358: _skipdot=false
2359: # preprocess CDPATH to convert null directory names to .
2360: _cdpath=$@{CDPATH/#:/.:@}
2361: _cdpath=$@{_cdpath//::/:.:@}
2362: _cdpath=$@{_cdpath/%:/:.@}
2363: for i in $@{_cdpath//:/$'\n'@}; do
2364: if [[ $i -ef . ]]; then _skipdot=true; fi
2365: k="$@{#COMPREPLY[@@]@}"
2366: for j in $( compgen -d -- "$i/$cur" ); do
2367: COMPREPLY[k++]=$@{j#$i/@} # cut off directory
2368: done
2369: done
2370: $_skipdot || COMPREPLY+=( $(compgen -d -- "$cur") )
2371: IFS=$' \t\n'
2372: fi
2373:
2374: # variable names if appropriate shell option set and no completions
2375: if shopt -q cdable_vars && [[ $@{#COMPREPLY[@@]@} -eq 0 ]]; then
2376: COMPREPLY=( $(compgen -v -- "$cur") )
2377: fi
2378:
2379: return 0
2380: @}
2381: @end example
2382:
2383: We install the completion function using the @option{-F} option to
2384: @code{complete}:
2385:
2386: @example
2387: # Tell readline to quote appropriate and append slashes to directories;
2388: # use the bash default completion for other arguments
2389: complete -o filenames -o nospace -o bashdefault -F _comp_cd cd
2390: @end example
2391:
2392: @noindent
2393: Since we'd like Bash and Readline to take care of some
2394: of the other details for us, we use several other options to tell Bash
2395: and Readline what to do. The @option{-o filenames} option tells Readline
2396: that the possible completions should be treated as filenames, and quoted
2397: appropriately. That option will also cause Readline to append a slash to
2398: filenames it can determine are directories (which is why we might want to
2399: extend @code{_comp_cd} to append a slash if we're using directories found
2400: via @var{CDPATH}: Readline can't tell those completions are directories).
2401: The @option{-o nospace} option tells Readline to not append a space
2402: character to the directory name, in case we want to append to it.
2403: The @option{-o bashdefault} option brings in the rest of the "Bash default"
2404: completions -- possible completion that Bash adds to the default Readline
2405: set. These include things like command name completion, variable completion
2406: for words beginning with @samp{$} or @samp{$@{}, completions containing pathname
2407: expansion patterns (@pxref{Filename Expansion}), and so on.
2408:
2409: Once installed using @code{complete}, @code{_comp_cd} will be called every
2410: time we attempt word completion for a @code{cd} command.
2411:
2412: Many more examples -- an extensive collection of completions for most of
2413: the common GNU, Unix, and Linux commands -- are available as part of the
2414: bash_completion project. This is installed by default on many GNU/Linux
2415: distributions. Originally written by Ian Macdonald, the project now lives
2416: at @url{https://github.com/scop/bash-completion/}. There are ports for
2417: other systems such as Solaris and Mac OS X.
2418:
2419: An older version of the bash_completion package is distributed with bash
2420: in the @file{examples/complete} subdirectory.
2421:
2422: @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