diff options
Diffstat (limited to 'readline/doc/rluser.texi')
| -rw-r--r-- | readline/doc/rluser.texi | 1846 |
1 files changed, 0 insertions, 1846 deletions
diff --git a/readline/doc/rluser.texi b/readline/doc/rluser.texi deleted file mode 100644 index 478b41f..0000000 --- a/readline/doc/rluser.texi +++ /dev/null @@ -1,1846 +0,0 @@ -@comment %**start of header (This is for running Texinfo on a region.) -@setfilename rluser.info -@comment %**end of header (This is for running Texinfo on a region.) -@setchapternewpage odd - -@ignore -This file documents the end user interface to the GNU command line -editing features. It is to be an appendix to manuals for programs which -use these features. There is a document entitled "readline.texinfo" -which contains both end-user and programmer documentation for the -GNU Readline Library. - -Copyright (C) 1988-2005 Free Software Foundation, Inc. - -Authored by Brian Fox and Chet Ramey. - -Permission is granted to process this file through Tex and print the -results, provided the printed document carries copying permission notice -identical to this one except for the removal of this paragraph (this -paragraph not being relevant to the printed manual). - -Permission is granted to make and distribute verbatim copies of this manual -provided the copyright notice and this permission notice are preserved on -all copies. - -Permission is granted to copy and distribute modified versions of this -manual under the conditions for verbatim copying, provided also that the -GNU Copyright statement is available to the distributee, and provided that -the entire resulting derived work is distributed under the terms of a -permission notice identical to this one. - -Permission is granted to copy and distribute translations of this manual -into another language, under the above conditions for modified versions. -@end ignore - -@comment If you are including this manual as an appendix, then set the -@comment variable readline-appendix. - -@ifclear BashFeatures -@defcodeindex bt -@end ifclear - -@node Command Line Editing -@chapter Command Line Editing - -This chapter describes the basic features of the @sc{gnu} -command line editing interface. -@ifset BashFeatures -Command line editing is provided by the Readline library, which is -used by several different programs, including Bash. -@end ifset - -@menu -* Introduction and Notation:: Notation used in this text. -* Readline Interaction:: The minimum set of commands for editing a line. -* Readline Init File:: Customizing Readline from a user's view. -* Bindable Readline Commands:: A description of most of the Readline commands - available for binding -* Readline vi Mode:: A short description of how to make Readline - behave like the vi editor. -@ifset BashFeatures -* Programmable Completion:: How to specify the possible completions for - a specific command. -* Programmable Completion Builtins:: Builtin commands to specify how to - complete arguments for a particular command. -@end ifset -@end menu - -@node Introduction and Notation -@section Introduction to Line Editing - -The following paragraphs describe the notation used to represent -keystrokes. - -The text @kbd{C-k} is read as `Control-K' and describes the character -produced when the @key{k} key is pressed while the Control key -is depressed. - -The text @kbd{M-k} is read as `Meta-K' and describes the character -produced when the Meta key (if you have one) is depressed, and the @key{k} -key is pressed. -The Meta key is labeled @key{ALT} on many keyboards. -On keyboards with two keys labeled @key{ALT} (usually to either side of -the space bar), the @key{ALT} on the left side is generally set to -work as a Meta key. -The @key{ALT} key on the right may also be configured to work as a -Meta key or may be configured as some other modifier, such as a -Compose key for typing accented characters. - -If you do not have a Meta or @key{ALT} key, or another key working as -a Meta key, the identical keystroke can be generated by typing @key{ESC} -@emph{first}, and then typing @key{k}. -Either process is known as @dfn{metafying} the @key{k} key. - -The text @kbd{M-C-k} is read as `Meta-Control-k' and describes the -character produced by @dfn{metafying} @kbd{C-k}. - -In addition, several keys have their own names. Specifically, -@key{DEL}, @key{ESC}, @key{LFD}, @key{SPC}, @key{RET}, and @key{TAB} all -stand for themselves when seen in this text, or in an init file -(@pxref{Readline Init File}). -If your keyboard lacks a @key{LFD} key, typing @key{C-j} will -produce the desired character. -The @key{RET} key may be labeled @key{Return} or @key{Enter} on -some keyboards. - -@node Readline Interaction -@section Readline Interaction -@cindex interaction, readline - -Often during an interactive session you type in a long line of text, -only to notice that the first word on the line is misspelled. The -Readline library gives you a set of commands for manipulating the text -as you type it in, allowing you to just fix your typo, and not forcing -you to retype the majority of the line. Using these editing commands, -you move the cursor to the place that needs correction, and delete or -insert the text of the corrections. Then, when you are satisfied with -the line, you simply press @key{RET}. You do not have to be at the -end of the line to press @key{RET}; the entire line is accepted -regardless of the location of the cursor within the line. - -@menu -* Readline Bare Essentials:: The least you need to know about Readline. -* Readline Movement Commands:: Moving about the input line. -* Readline Killing Commands:: How to delete text, and how to get it back! -* Readline Arguments:: Giving numeric arguments to commands. -* Searching:: Searching through previous lines. -@end menu - -@node Readline Bare Essentials -@subsection Readline Bare Essentials -@cindex notation, readline -@cindex command editing -@cindex editing command lines - -In order to enter characters into the line, simply type them. The typed -character appears where the cursor was, and then the cursor moves one -space to the right. If you mistype a character, you can use your -erase character to back up and delete the mistyped character. - -Sometimes you may mistype a character, and -not notice the error until you have typed several other characters. In -that case, you can type @kbd{C-b} to move the cursor to the left, and then -correct your mistake. Afterwards, you can move the cursor to the right -with @kbd{C-f}. - -When you add text in the middle of a line, you will notice that characters -to the right of the cursor are `pushed over' to make room for the text -that you have inserted. Likewise, when you delete text behind the cursor, -characters to the right of the cursor are `pulled back' to fill in the -blank space created by the removal of the text. A list of the bare -essentials for editing the text of an input line follows. - -@table @asis -@item @kbd{C-b} -Move back one character. -@item @kbd{C-f} -Move forward one character. -@item @key{DEL} or @key{Backspace} -Delete the character to the left of the cursor. -@item @kbd{C-d} -Delete the character underneath the cursor. -@item @w{Printing characters} -Insert the character into the line at the cursor. -@item @kbd{C-_} or @kbd{C-x C-u} -Undo the last editing command. You can undo all the way back to an -empty line. -@end table - -@noindent -(Depending on your configuration, the @key{Backspace} key be set to -delete the character to the left of the cursor and the @key{DEL} key set -to delete the character underneath the cursor, like @kbd{C-d}, rather -than the character to the left of the cursor.) - -@node Readline Movement Commands -@subsection Readline Movement Commands - - -The above table describes the most basic keystrokes that you need -in order to do editing of the input line. For your convenience, many -other commands have been added in addition to @kbd{C-b}, @kbd{C-f}, -@kbd{C-d}, and @key{DEL}. Here are some commands for moving more rapidly -about the line. - -@table @kbd -@item C-a -Move to the start of the line. -@item C-e -Move to the end of the line. -@item M-f -Move forward a word, where a word is composed of letters and digits. -@item M-b -Move backward a word. -@item C-l -Clear the screen, reprinting the current line at the top. -@end table - -Notice how @kbd{C-f} moves forward a character, while @kbd{M-f} moves -forward a word. It is a loose convention that control keystrokes -operate on characters while meta keystrokes operate on words. - -@node Readline Killing Commands -@subsection Readline Killing Commands - -@cindex killing text -@cindex yanking text - -@dfn{Killing} text means to delete the text from the line, but to save -it away for later use, usually by @dfn{yanking} (re-inserting) -it back into the line. -(`Cut' and `paste' are more recent jargon for `kill' and `yank'.) - -If the description for a command says that it `kills' text, then you can -be sure that you can get the text back in a different (or the same) -place later. - -When you use a kill command, the text is saved in a @dfn{kill-ring}. -Any number of consecutive kills save all of the killed text together, so -that when you yank it back, you get it all. The kill -ring is not line specific; the text that you killed on a previously -typed line is available to be yanked back later, when you are typing -another line. -@cindex kill ring - -Here is the list of commands for killing text. - -@table @kbd -@item C-k -Kill the text from the current cursor position to the end of the line. - -@item M-d -Kill from the cursor to the end of the current word, or, if between -words, to the end of the next word. -Word boundaries are the same as those used by @kbd{M-f}. - -@item M-@key{DEL} -Kill from the cursor the start of the current word, or, if between -words, to the start of the previous word. -Word boundaries are the same as those used by @kbd{M-b}. - -@item C-w -Kill from the cursor to the previous whitespace. This is different than -@kbd{M-@key{DEL}} because the word boundaries differ. - -@end table - -Here is how to @dfn{yank} the text back into the line. Yanking -means to copy the most-recently-killed text from the kill buffer. - -@table @kbd -@item C-y -Yank the most recently killed text back into the buffer at the cursor. - -@item M-y -Rotate the kill-ring, and yank the new top. You can only do this if -the prior command is @kbd{C-y} or @kbd{M-y}. -@end table - -@node Readline Arguments -@subsection Readline Arguments - -You can pass numeric arguments to Readline commands. Sometimes the -argument acts as a repeat count, other times it is the @i{sign} of the -argument that is significant. If you pass a negative argument to a -command which normally acts in a forward direction, that command will -act in a backward direction. For example, to kill text back to the -start of the line, you might type @samp{M-- C-k}. - -The general way to pass numeric arguments to a command is to type meta -digits before the command. If the first `digit' typed is a minus -sign (@samp{-}), then the sign of the argument will be negative. Once -you have typed one meta digit to get the argument started, you can type -the remainder of the digits, and then the command. For example, to give -the @kbd{C-d} command an argument of 10, you could type @samp{M-1 0 C-d}, -which will delete the next ten characters on the input line. - -@node Searching -@subsection Searching for Commands in the History - -Readline provides commands for searching through the command history -@ifset BashFeatures -(@pxref{Bash History Facilities}) -@end ifset -for lines containing a specified string. -There are two search modes: @dfn{incremental} and @dfn{non-incremental}. - -Incremental searches begin before the user has finished typing the -search string. -As each character of the search string is typed, Readline displays -the next entry from the history matching the string typed so far. -An incremental search requires only as many characters as needed to -find the desired history entry. -To search backward in the history for a particular string, type -@kbd{C-r}. Typing @kbd{C-s} searches forward through the history. -The characters present in the value of the @code{isearch-terminators} variable -are used to terminate an incremental search. -If that variable has not been assigned a value, the @key{ESC} and -@kbd{C-J} characters will terminate an incremental search. -@kbd{C-g} will abort an incremental search and restore the original line. -When the search is terminated, the history entry containing the -search string becomes the current line. - -To find other matching entries in the history list, type @kbd{C-r} or -@kbd{C-s} as appropriate. -This will search backward or forward in the history for the next -entry matching the search string typed so far. -Any other key sequence bound to a Readline command will terminate -the search and execute that command. -For instance, a @key{RET} will terminate the search and accept -the line, thereby executing the command from the history list. -A movement command will terminate the search, make the last line found -the current line, and begin editing. - -Readline remembers the last incremental search string. If two -@kbd{C-r}s are typed without any intervening characters defining a new -search string, any remembered search string is used. - -Non-incremental searches read the entire search string before starting -to search for matching history lines. The search string may be -typed by the user or be part of the contents of the current line. - -@node Readline Init File -@section Readline Init File -@cindex initialization file, readline - -Although the Readline library comes with a set of Emacs-like -keybindings installed by default, it is possible to use a different set -of keybindings. -Any user can customize programs that use Readline by putting -commands in an @dfn{inputrc} file, conventionally in his home directory. -The name of this -@ifset BashFeatures -file is taken from the value of the shell variable @env{INPUTRC}. If -@end ifset -@ifclear BashFeatures -file is taken from the value of the environment variable @env{INPUTRC}. If -@end ifclear -that variable is unset, the default is @file{~/.inputrc}. - -When a program which uses the Readline library starts up, the -init file is read, and the key bindings are set. - -In addition, the @code{C-x C-r} command re-reads this init file, thus -incorporating any changes that you might have made to it. - -@menu -* Readline Init File Syntax:: Syntax for the commands in the inputrc file. - -* Conditional Init Constructs:: Conditional key bindings in the inputrc file. - -* Sample Init File:: An example inputrc file. -@end menu - -@node Readline Init File Syntax -@subsection Readline Init File Syntax - -There are only a few basic constructs allowed in the -Readline init file. Blank lines are ignored. -Lines beginning with a @samp{#} are comments. -Lines beginning with a @samp{$} indicate conditional -constructs (@pxref{Conditional Init Constructs}). Other lines -denote variable settings and key bindings. - -@table @asis -@item Variable Settings -You can modify the run-time behavior of Readline by -altering the values of variables in Readline -using the @code{set} command within the init file. -The syntax is simple: - -@example -set @var{variable} @var{value} -@end example - -@noindent -Here, for example, is how to -change from the default Emacs-like key binding to use -@code{vi} line editing commands: - -@example -set editing-mode vi -@end example - -Variable names and values, where appropriate, are recognized without regard -to case. Unrecognized variable names are ignored. - -Boolean variables (those that can be set to on or off) are set to on if -the value is null or empty, @var{on} (case-insensitive), or 1. Any other -value results in the variable being set to off. - -@ifset BashFeatures -The @w{@code{bind -V}} command lists the current Readline variable names -and values. @xref{Bash Builtins}. -@end ifset - -A great deal of run-time behavior is changeable with the following -variables. - -@cindex variables, readline -@table @code - -@item bell-style -@vindex bell-style -Controls what happens when Readline wants to ring the terminal bell. -If set to @samp{none}, Readline never rings the bell. If set to -@samp{visible}, Readline uses a visible bell if one is available. -If set to @samp{audible} (the default), Readline attempts to ring -the terminal's bell. - -@item bind-tty-special-chars -@vindex bind-tty-special-chars -If set to @samp{on}, Readline attempts to bind the control characters -treated specially by the kernel's terminal driver to their Readline -equivalents. - -@item comment-begin -@vindex comment-begin -The string to insert at the beginning of the line when the -@code{insert-comment} command is executed. The default value -is @code{"#"}. - -@item completion-ignore-case -If set to @samp{on}, Readline performs filename matching and completion -in a case-insensitive fashion. -The default value is @samp{off}. - -@item completion-query-items -@vindex completion-query-items -The number of possible completions that determines when the user is -asked whether the list of possibilities should be displayed. -If the number of possible completions is greater than this value, -Readline will ask the user whether or not he wishes to view -them; otherwise, they are simply listed. -This variable must be set to an integer value greater than or equal to 0. -A negative value means Readline should never ask. -The default limit is @code{100}. - -@item convert-meta -@vindex convert-meta -If set to @samp{on}, Readline will convert characters with the -eighth bit set to an @sc{ascii} key sequence by stripping the eighth -bit and prefixing an @key{ESC} character, converting them to a -meta-prefixed key sequence. The default value is @samp{on}. - -@item disable-completion -@vindex disable-completion -If set to @samp{On}, Readline will inhibit word completion. -Completion characters will be inserted into the line as if they had -been mapped to @code{self-insert}. The default is @samp{off}. - -@item editing-mode -@vindex editing-mode -The @code{editing-mode} variable controls which default set of -key bindings is used. By default, Readline starts up in Emacs editing -mode, where the keystrokes are most similar to Emacs. This variable can be -set to either @samp{emacs} or @samp{vi}. - -@item enable-keypad -@vindex enable-keypad -When set to @samp{on}, Readline will try to enable the application -keypad when it is called. Some systems need this to enable the -arrow keys. The default is @samp{off}. - -@item expand-tilde -@vindex expand-tilde -If set to @samp{on}, tilde expansion is performed when Readline -attempts word completion. The default is @samp{off}. - -@item history-preserve-point -@vindex history-preserve-point -If set to @samp{on}, the history code attempts to place point at the -same location on each history line retrieved with @code{previous-history} -or @code{next-history}. The default is @samp{off}. - -@item horizontal-scroll-mode -@vindex horizontal-scroll-mode -This variable can be set to either @samp{on} or @samp{off}. Setting it -to @samp{on} means that the text of the lines being edited will scroll -horizontally on a single screen line when they are longer than the width -of the screen, instead of wrapping onto a new screen line. By default, -this variable is set to @samp{off}. - -@item input-meta -@vindex input-meta -@vindex meta-flag -If set to @samp{on}, Readline will enable eight-bit input (it -will not clear the eighth bit in the characters it reads), -regardless of what the terminal claims it can support. The -default value is @samp{off}. The name @code{meta-flag} is a -synonym for this variable. - -@item isearch-terminators -@vindex isearch-terminators -The string of characters that should terminate an incremental search without -subsequently executing the character as a command (@pxref{Searching}). -If this variable has not been given a value, the characters @key{ESC} and -@kbd{C-J} will terminate an incremental search. - -@item keymap -@vindex keymap -Sets Readline's idea of the current keymap for key binding commands. -Acceptable @code{keymap} names are -@code{emacs}, -@code{emacs-standard}, -@code{emacs-meta}, -@code{emacs-ctlx}, -@code{vi}, -@code{vi-move}, -@code{vi-command}, and -@code{vi-insert}. -@code{vi} is equivalent to @code{vi-command}; @code{emacs} is -equivalent to @code{emacs-standard}. The default value is @code{emacs}. -The value of the @code{editing-mode} variable also affects the -default keymap. - -@item mark-directories -If set to @samp{on}, completed directory names have a slash -appended. The default is @samp{on}. - -@item mark-modified-lines -@vindex mark-modified-lines -This variable, when set to @samp{on}, causes Readline to display an -asterisk (@samp{*}) at the start of history lines which have been modified. -This variable is @samp{off} by default. - -@item mark-symlinked-directories -@vindex mark-symlinked-directories -If set to @samp{on}, completed names which are symbolic links -to directories have a slash appended (subject to the value of -@code{mark-directories}). -The default is @samp{off}. - -@item match-hidden-files -@vindex match-hidden-files -This variable, when set to @samp{on}, causes Readline to match files whose -names begin with a @samp{.} (hidden files) when performing filename -completion, unless the leading @samp{.} is -supplied by the user in the filename to be completed. -This variable is @samp{on} by default. - -@item output-meta -@vindex output-meta -If set to @samp{on}, Readline will display characters with the -eighth bit set directly rather than as a meta-prefixed escape -sequence. The default is @samp{off}. - -@item page-completions -@vindex page-completions -If set to @samp{on}, Readline uses an internal @code{more}-like pager -to display a screenful of possible completions at a time. -This variable is @samp{on} by default. - -@item print-completions-horizontally -If set to @samp{on}, Readline will display completions with matches -sorted horizontally in alphabetical order, rather than down the screen. -The default is @samp{off}. - -@item show-all-if-ambiguous -@vindex show-all-if-ambiguous -This alters the default behavior of the completion functions. If -set to @samp{on}, -words which have more than one possible completion cause the -matches to be listed immediately instead of ringing the bell. -The default value is @samp{off}. - -@item show-all-if-unmodified -@vindex show-all-if-unmodified -This alters the default behavior of the completion functions in -a fashion similar to @var{show-all-if-ambiguous}. -If set to @samp{on}, -words which have more than one possible completion without any -possible partial completion (the possible completions don't share -a common prefix) cause the matches to be listed immediately instead -of ringing the bell. -The default value is @samp{off}. - -@item visible-stats -@vindex visible-stats -If set to @samp{on}, a character denoting a file's type -is appended to the filename when listing possible -completions. The default is @samp{off}. - -@end table - -@item Key Bindings -The syntax for controlling key bindings in the init file is -simple. First you need to find the name of the command that you -want to change. The following sections contain tables of the command -name, the default keybinding, if any, and a short description of what -the command does. - -Once you know the name of the command, simply place on a line -in the init file the name of the key -you wish to bind the command to, a colon, and then the name of the -command. The name of the key -can be expressed in different ways, depending on what you find most -comfortable. - -In addition to command names, readline allows keys to be bound -to a string that is inserted when the key is pressed (a @var{macro}). - -@ifset BashFeatures -The @w{@code{bind -p}} command displays Readline function names and -bindings in a format that can put directly into an initialization file. -@xref{Bash Builtins}. -@end ifset - -@table @asis -@item @w{@var{keyname}: @var{function-name} or @var{macro}} -@var{keyname} is the name of a key spelled out in English. For example: -@example -Control-u: universal-argument -Meta-Rubout: backward-kill-word -Control-o: "> output" -@end example - -In the above example, @kbd{C-u} is bound to the function -@code{universal-argument}, -@kbd{M-DEL} is bound to the function @code{backward-kill-word}, and -@kbd{C-o} is bound to run the macro -expressed on the right hand side (that is, to insert the text -@samp{> output} into the line). - -A number of symbolic character names are recognized while -processing this key binding syntax: -@var{DEL}, -@var{ESC}, -@var{ESCAPE}, -@var{LFD}, -@var{NEWLINE}, -@var{RET}, -@var{RETURN}, -@var{RUBOUT}, -@var{SPACE}, -@var{SPC}, -and -@var{TAB}. - -@item @w{"@var{keyseq}": @var{function-name} or @var{macro}} -@var{keyseq} differs from @var{keyname} above in that strings -denoting an entire key sequence can be specified, by placing -the key sequence in double quotes. Some @sc{gnu} Emacs style key -escapes can be used, as in the following example, but the -special character names are not recognized. - -@example -"\C-u": universal-argument -"\C-x\C-r": re-read-init-file -"\e[11~": "Function Key 1" -@end example - -In the above example, @kbd{C-u} is again bound to the function -@code{universal-argument} (just as it was in the first example), -@samp{@kbd{C-x} @kbd{C-r}} is bound to the function @code{re-read-init-file}, -and @samp{@key{ESC} @key{[} @key{1} @key{1} @key{~}} is bound to insert -the text @samp{Function Key 1}. - -@end table - -The following @sc{gnu} Emacs style escape sequences are available when -specifying key sequences: - -@table @code -@item @kbd{\C-} -control prefix -@item @kbd{\M-} -meta prefix -@item @kbd{\e} -an escape character -@item @kbd{\\} -backslash -@item @kbd{\"} -@key{"}, a double quotation mark -@item @kbd{\'} -@key{'}, a single quote or apostrophe -@end table - -In addition to the @sc{gnu} Emacs style escape sequences, a second -set of backslash escapes is available: - -@table @code -@item \a -alert (bell) -@item \b -backspace -@item \d -delete -@item \f -form feed -@item \n -newline -@item \r -carriage return -@item \t -horizontal tab -@item \v -vertical tab -@item \@var{nnn} -the eight-bit character whose value is the octal value @var{nnn} -(one to three digits) -@item \x@var{HH} -the eight-bit character whose value is the hexadecimal value @var{HH} -(one or two hex digits) -@end table - -When entering the text of a macro, single or double quotes must -be used to indicate a macro definition. -Unquoted text is assumed to be a function name. -In the macro body, the backslash escapes described above are expanded. -Backslash will quote any other character in the macro text, -including @samp{"} and @samp{'}. -For example, the following binding will make @samp{@kbd{C-x} \} -insert a single @samp{\} into the line: -@example -"\C-x\\": "\\" -@end example - -@end table - -@node Conditional Init Constructs -@subsection Conditional Init Constructs - -Readline implements a facility similar in spirit to the conditional -compilation features of the C preprocessor which allows key -bindings and variable settings to be performed as the result -of tests. There are four parser directives used. - -@table @code -@item $if -The @code{$if} construct allows bindings to be made based on the -editing mode, the terminal being used, or the application using -Readline. The text of the test extends to the end of the line; -no characters are required to isolate it. - -@table @code -@item mode -The @code{mode=} form of the @code{$if} directive is used to test -whether Readline is in @code{emacs} or @code{vi} mode. -This may be used in conjunction -with the @samp{set keymap} command, for instance, to set bindings in -the @code{emacs-standard} and @code{emacs-ctlx} keymaps only if -Readline is starting out in @code{emacs} mode. - -@item term -The @code{term=} form may be used to include terminal-specific -key bindings, perhaps to bind the key sequences output by the -terminal's function keys. The word on the right side of the -@samp{=} is tested against both the full name of the terminal and -the portion of the terminal name before the first @samp{-}. This -allows @code{sun} to match both @code{sun} and @code{sun-cmd}, -for instance. - -@item application -The @var{application} construct is used to include -application-specific settings. Each program using the Readline -library sets the @var{application name}, and you can test for -a particular value. -This could be used to bind key sequences to functions useful for -a specific program. For instance, the following command adds a -key sequence that quotes the current or previous word in Bash: -@example -$if Bash -# Quote the current or previous word -"\C-xq": "\eb\"\ef\"" -$endif -@end example -@end table - -@item $endif -This command, as seen in the previous example, terminates an -@code{$if} command. - -@item $else -Commands in this branch of the @code{$if} directive are executed if -the test fails. - -@item $include -This directive takes a single filename as an argument and reads commands -and bindings from that file. -For example, the following directive reads from @file{/etc/inputrc}: -@example -$include /etc/inputrc -@end example -@end table - -@node Sample Init File -@subsection Sample Init File - -Here is an example of an @var{inputrc} file. This illustrates key -binding, variable assignment, and conditional syntax. - -@example -@page -# This file controls the behaviour of line input editing for -# programs that use the GNU Readline library. Existing -# programs include FTP, Bash, and GDB. -# -# You can re-read the inputrc file with C-x C-r. -# Lines beginning with '#' are comments. -# -# First, include any systemwide bindings and variable -# assignments from /etc/Inputrc -$include /etc/Inputrc - -# -# Set various bindings for emacs mode. - -set editing-mode emacs - -$if mode=emacs - -Meta-Control-h: backward-kill-word Text after the function name is ignored - -# -# Arrow keys in keypad mode -# -#"\M-OD": backward-char -#"\M-OC": forward-char -#"\M-OA": previous-history -#"\M-OB": next-history -# -# Arrow keys in ANSI mode -# -"\M-[D": backward-char -"\M-[C": forward-char -"\M-[A": previous-history -"\M-[B": next-history -# -# Arrow keys in 8 bit keypad mode -# -#"\M-\C-OD": backward-char -#"\M-\C-OC": forward-char -#"\M-\C-OA": previous-history -#"\M-\C-OB": next-history -# -# Arrow keys in 8 bit ANSI mode -# -#"\M-\C-[D": backward-char -#"\M-\C-[C": forward-char -#"\M-\C-[A": previous-history -#"\M-\C-[B": next-history - -C-q: quoted-insert - -$endif - -# An old-style binding. This happens to be the default. -TAB: complete - -# Macros that are convenient for shell interaction -$if Bash -# edit the path -"\C-xp": "PATH=$@{PATH@}\e\C-e\C-a\ef\C-f" -# prepare to type a quoted word -- -# insert open and close double quotes -# and move to just after the open quote -"\C-x\"": "\"\"\C-b" -# insert a backslash (testing backslash escapes -# in sequences and macros) -"\C-x\\": "\\" -# Quote the current or previous word -"\C-xq": "\eb\"\ef\"" -# Add a binding to refresh the line, which is unbound -"\C-xr": redraw-current-line -# Edit variable on current line. -"\M-\C-v": "\C-a\C-k$\C-y\M-\C-e\C-a\C-y=" -$endif - -# use a visible bell if one is available -set bell-style visible - -# don't strip characters to 7 bits when reading -set input-meta on - -# allow iso-latin1 characters to be inserted rather -# than converted to prefix-meta sequences -set convert-meta off - -# display characters with the eighth bit set directly -# rather than as meta-prefixed characters -set output-meta on - -# if there are more than 150 possible completions for -# a word, ask the user if he wants to see all of them -set completion-query-items 150 - -# For FTP -$if Ftp -"\C-xg": "get \M-?" -"\C-xt": "put \M-?" -"\M-.": yank-last-arg -$endif -@end example - -@node Bindable Readline Commands -@section Bindable Readline Commands - -@menu -* Commands For Moving:: Moving about the line. -* Commands For History:: Getting at previous lines. -* Commands For Text:: Commands for changing text. -* Commands For Killing:: Commands for killing and yanking. -* Numeric Arguments:: Specifying numeric arguments, repeat counts. -* Commands For Completion:: Getting Readline to do the typing for you. -* Keyboard Macros:: Saving and re-executing typed characters -* Miscellaneous Commands:: Other miscellaneous commands. -@end menu - -This section describes Readline commands that may be bound to key -sequences. -@ifset BashFeatures -You can list your key bindings by executing -@w{@code{bind -P}} or, for a more terse format, suitable for an -@var{inputrc} file, @w{@code{bind -p}}. (@xref{Bash Builtins}.) -@end ifset -Command names without an accompanying key sequence are unbound by default. - -In the following descriptions, @dfn{point} refers to the current cursor -position, and @dfn{mark} refers to a cursor position saved by the -@code{set-mark} command. -The text between the point and mark is referred to as the @dfn{region}. - -@node Commands For Moving -@subsection Commands For Moving -@ftable @code -@item beginning-of-line (C-a) -Move to the start of the current line. - -@item end-of-line (C-e) -Move to the end of the line. - -@item forward-char (C-f) -Move forward a character. - -@item backward-char (C-b) -Move back a character. - -@item forward-word (M-f) -Move forward to the end of the next word. Words are composed of -letters and digits. - -@item backward-word (M-b) -Move back to the start of the current or previous word. Words are -composed of letters and digits. - -@item clear-screen (C-l) -Clear the screen and redraw the current line, -leaving the current line at the top of the screen. - -@item redraw-current-line () -Refresh the current line. By default, this is unbound. - -@end ftable - -@node Commands For History -@subsection Commands For Manipulating The History - -@ftable @code -@item accept-line (Newline or Return) -@ifset BashFeatures -Accept the line regardless of where the cursor is. -If this line is -non-empty, add it to the history list according to the setting of -the @env{HISTCONTROL} and @env{HISTIGNORE} variables. -If this line is a modified history line, then restore the history line -to its original state. -@end ifset -@ifclear BashFeatures -Accept the line regardless of where the cursor is. -If this line is -non-empty, it may be added to the history list for future recall with -@code{add_history()}. -If this line is a modified history line, the history line is restored -to its original state. -@end ifclear - -@item previous-history (C-p) -Move `back' through the history list, fetching the previous command. - -@item next-history (C-n) -Move `forward' through the history list, fetching the next command. - -@item beginning-of-history (M-<) -Move to the first line in the history. - -@item end-of-history (M->) -Move to the end of the input history, i.e., the line currently -being entered. - -@item reverse-search-history (C-r) -Search backward starting at the current line and moving `up' through -the history as necessary. This is an incremental search. - -@item forward-search-history (C-s) -Search forward starting at the current line and moving `down' through -the the history as necessary. This is an incremental search. - -@item non-incremental-reverse-search-history (M-p) -Search backward starting at the current line and moving `up' -through the history as necessary using a non-incremental search -for a string supplied by the user. - -@item non-incremental-forward-search-history (M-n) -Search forward starting at the current line and moving `down' -through the the history as necessary using a non-incremental search -for a string supplied by the user. - -@item history-search-forward () -Search forward through the history for the string of characters -between the start of the current line and the point. -This is a non-incremental search. -By default, this command is unbound. - -@item history-search-backward () -Search backward through the history for the string of characters -between the start of the current line and the point. This -is a non-incremental search. By default, this command is unbound. - -@item yank-nth-arg (M-C-y) -Insert the first argument to the previous command (usually -the second word on the previous line) at point. -With an argument @var{n}, -insert the @var{n}th word from the previous command (the words -in the previous command begin with word 0). A negative argument -inserts the @var{n}th word from the end of the previous command. -Once the argument @var{n} is computed, the argument is extracted -as if the @samp{!@var{n}} history expansion had been specified. - -@item yank-last-arg (M-. or M-_) -Insert last argument to the previous command (the last word of the -previous history entry). With an -argument, behave exactly like @code{yank-nth-arg}. -Successive calls to @code{yank-last-arg} move back through the history -list, inserting the last argument of each line in turn. -The history expansion facilities are used to extract the last argument, -as if the @samp{!$} history expansion had been specified. - -@end ftable - -@node Commands For Text -@subsection Commands For Changing Text - -@ftable @code -@item delete-char (C-d) -Delete the character at point. If point is at the -beginning of the line, there are no characters in the line, and -the last character typed was not bound to @code{delete-char}, then -return @sc{eof}. - -@item backward-delete-char (Rubout) -Delete the character behind the cursor. A numeric argument means -to kill the characters instead of deleting them. - -@item forward-backward-delete-char () -Delete the character under the cursor, unless the cursor is at the -end of the line, in which case the character behind the cursor is -deleted. By default, this is not bound to a key. - -@item quoted-insert (C-q or C-v) -Add the next character typed to the line verbatim. This is -how to insert key sequences like @kbd{C-q}, for example. - -@ifclear BashFeatures -@item tab-insert (M-@key{TAB}) -Insert a tab character. -@end ifclear - -@item self-insert (a, b, A, 1, !, @dots{}) -Insert yourself. - -@item transpose-chars (C-t) -Drag the character before the cursor forward over -the character at the cursor, moving the -cursor forward as well. If the insertion point -is at the end of the line, then this -transposes the last two characters of the line. -Negative arguments have no effect. - -@item transpose-words (M-t) -Drag the word before point past the word after point, -moving point past that word as well. -If the insertion point is at the end of the line, this transposes -the last two words on the line. - -@item upcase-word (M-u) -Uppercase the current (or following) word. With a negative argument, -uppercase the previous word, but do not move the cursor. - -@item downcase-word (M-l) -Lowercase the current (or following) word. With a negative argument, -lowercase the previous word, but do not move the cursor. - -@item capitalize-word (M-c) -Capitalize the current (or following) word. With a negative argument, -capitalize the previous word, but do not move the cursor. - -@item overwrite-mode () -Toggle overwrite mode. With an explicit positive numeric argument, -switches to overwrite mode. With an explicit non-positive numeric -argument, switches to insert mode. This command affects only -@code{emacs} mode; @code{vi} mode does overwrite differently. -Each call to @code{readline()} starts in insert mode. - -In overwrite mode, characters bound to @code{self-insert} replace -the text at point rather than pushing the text to the right. -Characters bound to @code{backward-delete-char} replace the character -before point with a space. - -By default, this command is unbound. - -@end ftable - -@node Commands For Killing -@subsection Killing And Yanking - -@ftable @code - -@item kill-line (C-k) -Kill the text from point to the end of the line. - -@item backward-kill-line (C-x Rubout) -Kill backward to the beginning of the line. - -@item unix-line-discard (C-u) -Kill backward from the cursor to the beginning of the current line. - -@item kill-whole-line () -Kill all characters on the current line, no matter where point is. -By default, this is unbound. - -@item kill-word (M-d) -Kill from point to the end of the current word, or if between -words, to the end of the next word. -Word boundaries are the same as @code{forward-word}. - -@item backward-kill-word (M-@key{DEL}) -Kill the word behind point. -Word boundaries are the same as @code{backward-word}. - -@item unix-word-rubout (C-w) -Kill the word behind point, using white space as a word boundary. -The killed text is saved on the kill-ring. - -@item unix-filename-rubout () -Kill the word behind point, using white space and the slash character -as the word boundaries. -The killed text is saved on the kill-ring. - -@item delete-horizontal-space () -Delete all spaces and tabs around point. By default, this is unbound. - -@item kill-region () -Kill the text in the current region. -By default, this command is unbound. - -@item copy-region-as-kill () -Copy the text in the region to the kill buffer, so it can be yanked -right away. By default, this command is unbound. - -@item copy-backward-word () -Copy the word before point to the kill buffer. -The word boundaries are the same as @code{backward-word}. -By default, this command is unbound. - -@item copy-forward-word () -Copy the word following point to the kill buffer. -The word boundaries are the same as @code{forward-word}. -By default, this command is unbound. - -@item yank (C-y) -Yank the top of the kill ring into the buffer at point. - -@item yank-pop (M-y) -Rotate the kill-ring, and yank the new top. You can only do this if -the prior command is @code{yank} or @code{yank-pop}. -@end ftable - -@node Numeric Arguments -@subsection Specifying Numeric Arguments -@ftable @code - -@item digit-argument (@kbd{M-0}, @kbd{M-1}, @dots{} @kbd{M--}) -Add this digit to the argument already accumulating, or start a new -argument. @kbd{M--} starts a negative argument. - -@item universal-argument () -This is another way to specify an argument. -If this command is followed by one or more digits, optionally with a -leading minus sign, those digits define the argument. -If the command is followed by digits, executing @code{universal-argument} -again ends the numeric argument, but is otherwise ignored. -As a special case, if this command is immediately followed by a -character that is neither a digit or minus sign, the argument count -for the next command is multiplied by four. -The argument count is initially one, so executing this function the -first time makes the argument count four, a second time makes the -argument count sixteen, and so on. -By default, this is not bound to a key. -@end ftable - -@node Commands For Completion -@subsection Letting Readline Type For You - -@ftable @code -@item complete (@key{TAB}) -Attempt to perform completion on the text before point. -The actual completion performed is application-specific. -@ifset BashFeatures -Bash attempts completion treating the text as a variable (if the -text begins with @samp{$}), username (if the text begins with -@samp{~}), hostname (if the text begins with @samp{@@}), or -command (including aliases and functions) in turn. If none -of these produces a match, filename completion is attempted. -@end ifset -@ifclear BashFeatures -The default is filename completion. -@end ifclear - -@item possible-completions (M-?) -List the possible completions of the text before point. - -@item insert-completions (M-*) -Insert all completions of the text before point that would have -been generated by @code{possible-completions}. - -@item menu-complete () -Similar to @code{complete}, but replaces the word to be completed -with a single match from the list of possible completions. -Repeated execution of @code{menu-complete} steps through the list -of possible completions, inserting each match in turn. -At the end of the list of completions, the bell is rung -(subject to the setting of @code{bell-style}) -and the original text is restored. -An argument of @var{n} moves @var{n} positions forward in the list -of matches; a negative argument may be used to move backward -through the list. -This command is intended to be bound to @key{TAB}, but is unbound -by default. - -@item delete-char-or-list () -Deletes the character under the cursor if not at the beginning or -end of the line (like @code{delete-char}). -If at the end of the line, behaves identically to -@code{possible-completions}. -This command is unbound by default. - -@ifset BashFeatures -@item complete-filename (M-/) -Attempt filename completion on the text before point. - -@item possible-filename-completions (C-x /) -List the possible completions of the text before point, -treating it as a filename. - -@item complete-username (M-~) -Attempt completion on the text before point, treating -it as a username. - -@item possible-username-completions (C-x ~) -List the possible completions of the text before point, -treating it as a username. - -@item complete-variable (M-$) -Attempt completion on the text before point, treating -it as a shell variable. - -@item possible-variable-completions (C-x $) -List the possible completions of the text before point, -treating it as a shell variable. - -@item complete-hostname (M-@@) -Attempt completion on the text before point, treating -it as a hostname. - -@item possible-hostname-completions (C-x @@) -List the possible completions of the text before point, -treating it as a hostname. - -@item complete-command (M-!) -Attempt completion on the text before point, treating -it as a command name. Command completion attempts to -match the text against aliases, reserved words, shell -functions, shell builtins, and finally executable filenames, -in that order. - -@item possible-command-completions (C-x !) -List the possible completions of the text before point, -treating it as a command name. - -@item dynamic-complete-history (M-@key{TAB}) -Attempt completion on the text before point, comparing -the text against lines from the history list for possible -completion matches. - -@item complete-into-braces (M-@{) -Perform filename completion and insert the list of possible completions -enclosed within braces so the list is available to the shell -(@pxref{Brace Expansion}). - -@end ifset -@end ftable - -@node Keyboard Macros -@subsection Keyboard Macros -@ftable @code - -@item start-kbd-macro (C-x () -Begin saving the characters typed into the current keyboard macro. - -@item end-kbd-macro (C-x )) -Stop saving the characters typed into the current keyboard macro -and save the definition. - -@item call-last-kbd-macro (C-x e) -Re-execute the last keyboard macro defined, by making the characters -in the macro appear as if typed at the keyboard. - -@end ftable - -@node Miscellaneous Commands -@subsection Some Miscellaneous Commands -@ftable @code - -@item re-read-init-file (C-x C-r) -Read in the contents of the @var{inputrc} file, and incorporate -any bindings or variable assignments found there. - -@item abort (C-g) -Abort the current editing command and -ring the terminal's bell (subject to the setting of -@code{bell-style}). - -@item do-uppercase-version (M-a, M-b, M-@var{x}, @dots{}) -If the metafied character @var{x} is lowercase, run the command -that is bound to the corresponding uppercase character. - -@item prefix-meta (@key{ESC}) -Metafy the next character typed. This is for keyboards -without a meta key. Typing @samp{@key{ESC} f} is equivalent to typing -@kbd{M-f}. - -@item undo (C-_ or C-x C-u) -Incremental undo, separately remembered for each line. - -@item revert-line (M-r) -Undo all changes made to this line. This is like executing the @code{undo} -command enough times to get back to the beginning. - -@ifset BashFeatures -@item tilde-expand (M-&) -@end ifset -@ifclear BashFeatures -@item tilde-expand (M-~) -@end ifclear -Perform tilde expansion on the current word. - -@item set-mark (C-@@) -Set the mark to the point. If a -numeric argument is supplied, the mark is set to that position. - -@item exchange-point-and-mark (C-x C-x) -Swap the point with the mark. The current cursor position is set to -the saved position, and the old cursor position is saved as the mark. - -@item character-search (C-]) -A character is read and point is moved to the next occurrence of that -character. A negative count searches for previous occurrences. - -@item character-search-backward (M-C-]) -A character is read and point is moved to the previous occurrence -of that character. A negative count searches for subsequent -occurrences. - -@item insert-comment (M-#) -Without a numeric argument, the value of the @code{comment-begin} -variable is inserted at the beginning of the current line. -If a numeric argument is supplied, this command acts as a toggle: if -the characters at the beginning of the line do not match the value -of @code{comment-begin}, the value is inserted, otherwise -the characters in @code{comment-begin} are deleted from the beginning of -the line. -In either case, the line is accepted as if a newline had been typed. -@ifset BashFeatures -The default value of @code{comment-begin} causes this command -to make the current line a shell comment. -If a numeric argument causes the comment character to be removed, the line -will be executed by the shell. -@end ifset - -@item dump-functions () -Print all of the functions and their key bindings to the -Readline output stream. If a numeric argument is supplied, -the output is formatted in such a way that it can be made part -of an @var{inputrc} file. This command is unbound by default. - -@item dump-variables () -Print all of the settable variables and their values to the -Readline output stream. If a numeric argument is supplied, -the output is formatted in such a way that it can be made part -of an @var{inputrc} file. This command is unbound by default. - -@item dump-macros () -Print all of the Readline key sequences bound to macros and the -strings they output. If a numeric argument is supplied, -the output is formatted in such a way that it can be made part -of an @var{inputrc} file. This command is unbound by default. - -@ifset BashFeatures -@item glob-complete-word (M-g) -The word before point is treated as a pattern for pathname expansion, -with an asterisk implicitly appended. This pattern is used to -generate a list of matching file names for possible completions. - -@item glob-expand-word (C-x *) -The word before point is treated as a pattern for pathname expansion, -and the list of matching file names is inserted, replacing the word. -If a numeric argument is supplied, a @samp{*} is appended before -pathname expansion. - -@item glob-list-expansions (C-x g) -The list of expansions that would have been generated by -@code{glob-expand-word} is displayed, and the line is redrawn. -If a numeric argument is supplied, a @samp{*} is appended before -pathname expansion. - -@item display-shell-version (C-x C-v) -Display version information about the current instance of Bash. - -@item shell-expand-line (M-C-e) -Expand the line as the shell does. -This performs alias and history expansion as well as all of the shell -word expansions (@pxref{Shell Expansions}). - -@item history-expand-line (M-^) -Perform history expansion on the current line. - -@item magic-space () -Perform history expansion on the current line and insert a space -(@pxref{History Interaction}). - -@item alias-expand-line () -Perform alias expansion on the current line (@pxref{Aliases}). - -@item history-and-alias-expand-line () -Perform history and alias expansion on the current line. - -@item insert-last-argument (M-. or M-_) -A synonym for @code{yank-last-arg}. - -@item operate-and-get-next (C-o) -Accept the current line for execution and fetch the next line -relative to the current line from the history for editing. Any -argument is ignored. - -@item edit-and-execute-command (C-xC-e) -Invoke an editor on the current command line, and execute the result as shell -commands. -Bash attempts to invoke -@code{$VISUAL}, @code{$EDITOR}, and @code{emacs} -as the editor, in that order. - -@end ifset - -@ifclear BashFeatures -@item emacs-editing-mode (C-e) -When in @code{vi} command mode, this causes a switch to @code{emacs} -editing mode. - -@item vi-editing-mode (M-C-j) -When in @code{emacs} editing mode, this causes a switch to @code{vi} -editing mode. - -@end ifclear - -@end ftable - -@node Readline vi Mode -@section Readline vi Mode - -While the Readline library does not have a full set of @code{vi} -editing functions, it does contain enough to allow simple editing -of the line. The Readline @code{vi} mode behaves as specified in -the @sc{posix} 1003.2 standard. - -@ifset BashFeatures -In order to switch interactively between @code{emacs} and @code{vi} -editing modes, use the @samp{set -o emacs} and @samp{set -o vi} -commands (@pxref{The Set Builtin}). -@end ifset -@ifclear BashFeatures -In order to switch interactively between @code{emacs} and @code{vi} -editing modes, use the command @kbd{M-C-j} (bound to emacs-editing-mode -when in @code{vi} mode and to vi-editing-mode in @code{emacs} mode). -@end ifclear -The Readline default is @code{emacs} mode. - -When you enter a line in @code{vi} mode, you are already placed in -`insertion' mode, as if you had typed an @samp{i}. Pressing @key{ESC} -switches you into `command' mode, where you can edit the text of the -line with the standard @code{vi} movement keys, move to previous -history lines with @samp{k} and subsequent lines with @samp{j}, and -so forth. - -@ifset BashFeatures -@node Programmable Completion -@section Programmable Completion -@cindex programmable completion - -When word completion is attempted for an argument to a command for -which a completion specification (a @var{compspec}) has been defined -using the @code{complete} builtin (@pxref{Programmable Completion Builtins}), -the programmable completion facilities are invoked. - -First, the command name is identified. -If a compspec has been defined for that command, the -compspec is used to generate the list of possible completions for the word. -If the command word is a full pathname, a compspec for the full -pathname is searched for first. -If no compspec is found for the full pathname, an attempt is made to -find a compspec for the portion following the final slash. - -Once a compspec has been found, it is used to generate the list of -matching words. -If a compspec is not found, the default Bash completion -described above (@pxref{Commands For Completion}) is performed. - -First, the actions specified by the compspec are used. -Only matches which are prefixed by the word being completed are -returned. -When the @option{-f} or @option{-d} option is used for filename or -directory name completion, the shell variable @env{FIGNORE} is -used to filter the matches. -@xref{Bash Variables}, for a description of @env{FIGNORE}. - -Any completions specified by a filename expansion pattern to the -@option{-G} option are generated next. -The words generated by the pattern need not match the word being completed. -The @env{GLOBIGNORE} shell variable is not used to filter the matches, -but the @env{FIGNORE} shell variable is used. - -Next, the string specified as the argument to the @option{-W} option -is considered. -The string is first split using the characters in the @env{IFS} -special variable as delimiters. -Shell quoting is honored. -Each word is then expanded using -brace expansion, tilde expansion, parameter and variable expansion, -command substitution, and arithmetic expansion, -as described above (@pxref{Shell Expansions}). -The results are split using the rules described above -(@pxref{Word Splitting}). -The results of the expansion are prefix-matched against the word being -completed, and the matching words become the possible completions. - -After these matches have been generated, any shell function or command -specified with the @option{-F} and @option{-C} options is invoked. -When the command or function is invoked, the @env{COMP_LINE} and -@env{COMP_POINT} variables are assigned values as described above -(@pxref{Bash Variables}). -If a shell function is being invoked, the @env{COMP_WORDS} and -@env{COMP_CWORD} variables are also set. -When the function or command is invoked, the first argument is the -name of the command whose arguments are being completed, the -second argument is the word being completed, and the third argument -is the word preceding the word being completed on the current command line. -No filtering of the generated completions against the word being completed -is performed; the function or command has complete freedom in generating -the matches. - -Any function specified with @option{-F} is invoked first. -The function may use any of the shell facilities, including the -@code{compgen} builtin described below -(@pxref{Programmable Completion Builtins}), to generate the matches. -It must put the possible completions in the @env{COMPREPLY} array -variable. - -Next, any command specified with the @option{-C} option is invoked -in an environment equivalent to command substitution. -It should print a list of completions, one per line, to -the standard output. -Backslash may be used to escape a newline, if necessary. - -After all of the possible completions are generated, any filter -specified with the @option{-X} option is applied to the list. -The filter is a pattern as used for pathname expansion; a @samp{&} -in the pattern is replaced with the text of the word being completed. -A literal @samp{&} may be escaped with a backslash; the backslash -is removed before attempting a match. -Any completion that matches the pattern will be removed from the list. -A leading @samp{!} negates the pattern; in this case any completion -not matching the pattern will be removed. - -Finally, any prefix and suffix specified with the @option{-P} and @option{-S} -options are added to each member of the completion list, and the result is -returned to the Readline completion code as the list of possible -completions. - -If the previously-applied actions do not generate any matches, and the -@option{-o dirnames} option was supplied to @code{complete} when the -compspec was defined, directory name completion is attempted. - -If the @option{-o plusdirs} option was supplied to @code{complete} when -the compspec was defined, directory name completion is attempted and any -matches are added to the results of the other actions. - -By default, if a compspec is found, whatever it generates is returned to -the completion code as the full set of possible completions. -The default Bash completions are not attempted, and the Readline default -of filename completion is disabled. -If the @option{-o bashdefault} option was supplied to @code{complete} when -the compspec was defined, the default Bash completions are attempted -if the compspec generates no matches. -If the @option{-o default} option was supplied to @code{complete} when the -compspec was defined, Readline's default completion will be performed -if the compspec (and, if attempted, the default Bash completions) -generate no matches. - -When a compspec indicates that directory name completion is desired, -the programmable completion functions force Readline to append a slash -to completed names which are symbolic links to directories, subject to -the value of the @var{mark-directories} Readline variable, regardless -of the setting of the @var{mark-symlinked-directories} Readline variable. - -@node Programmable Completion Builtins -@section Programmable Completion Builtins -@cindex completion builtins - -Two builtin commands are available to manipulate the programmable completion -facilities. - -@table @code -@item compgen -@btindex compgen -@example -@code{compgen [@var{option}] [@var{word}]} -@end example - -Generate possible completion matches for @var{word} according to -the @var{option}s, which may be any option accepted by the -@code{complete} -builtin with the exception of @option{-p} and @option{-r}, and write -the matches to the standard output. -When using the @option{-F} or @option{-C} options, the various shell variables -set by the programmable completion facilities, while available, will not -have useful values. - -The matches will be generated in the same way as if the programmable -completion code had generated them directly from a completion specification -with the same flags. -If @var{word} is specified, only those completions matching @var{word} -will be displayed. - -The return value is true unless an invalid option is supplied, or no -matches were generated. - -@item complete -@btindex complete -@example -@code{complete [-abcdefgjksuv] [-o @var{comp-option}] [-A @var{action}] [-G @var{globpat}] [-W @var{wordlist}] -[-P @var{prefix}] [-S @var{suffix}] [-X @var{filterpat}] [-F @var{function}] -[-C @var{command}] @var{name} [@var{name} @dots{}]} -@code{complete -pr [@var{name} @dots{}]} -@end example - -Specify how arguments to each @var{name} should be completed. -If the @option{-p} option is supplied, or if no options are supplied, existing -completion specifications are printed in a way that allows them to be -reused as input. -The @option{-r} option removes a completion specification for -each @var{name}, or, if no @var{name}s are supplied, all -completion specifications. - -The process of applying these completion specifications when word completion -is attempted is described above (@pxref{Programmable Completion}). - -Other options, if specified, have the following meanings. -The arguments to the @option{-G}, @option{-W}, and @option{-X} options -(and, if necessary, the @option{-P} and @option{-S} options) -should be quoted to protect them from expansion before the -@code{complete} builtin is invoked. - - -@table @code -@item -o @var{comp-option} -The @var{comp-option} controls several aspects of the compspec's behavior -beyond the simple generation of completions. -@var{comp-option} may be one of: - -@table @code - -@item bashdefault -Perform the rest of the default Bash completions if the compspec -generates no matches. - -@item default -Use Readline's default filename completion if the compspec generates -no matches. - -@item dirnames -Perform directory name completion if the compspec generates no matches. - -@item filenames -Tell Readline that the compspec generates filenames, so it can perform any -filename-specific processing (like adding a slash to directory names or -suppressing trailing spaces). This option is intended to be used with -shell functions specified with @option{-F}. - -@item nospace -Tell Readline not to append a space (the default) to words completed at -the end of the line. - -@item plusdirs -After any matches defined by the compspec are generated, -directory name completion is attempted and any -matches are added to the results of the other actions. - -@end table - -@item -A @var{action} -The @var{action} may be one of the following to generate a list of possible -completions: - -@table @code -@item alias -Alias names. May also be specified as @option{-a}. - -@item arrayvar -Array variable names. - -@item binding -Readline key binding names (@pxref{Bindable Readline Commands}). - -@item builtin -Names of shell builtin commands. May also be specified as @option{-b}. - -@item command -Command names. May also be specified as @option{-c}. - -@item directory -Directory names. May also be specified as @option{-d}. - -@item disabled -Names of disabled shell builtins. - -@item enabled -Names of enabled shell builtins. - -@item export -Names of exported shell variables. May also be specified as @option{-e}. - -@item file -File names. May also be specified as @option{-f}. - -@item function -Names of shell functions. - -@item group -Group names. May also be specified as @option{-g}. - -@item helptopic -Help topics as accepted by the @code{help} builtin (@pxref{Bash Builtins}). - -@item hostname -Hostnames, as taken from the file specified by the -@env{HOSTFILE} shell variable (@pxref{Bash Variables}). - -@item job -Job names, if job control is active. May also be specified as @option{-j}. - -@item keyword -Shell reserved words. May also be specified as @option{-k}. - -@item running -Names of running jobs, if job control is active. - -@item service -Service names. May also be specified as @option{-s}. - -@item setopt -Valid arguments for the @option{-o} option to the @code{set} builtin -(@pxref{The Set Builtin}). - -@item shopt -Shell option names as accepted by the @code{shopt} builtin -(@pxref{Bash Builtins}). - -@item signal -Signal names. - -@item stopped -Names of stopped jobs, if job control is active. - -@item user -User names. May also be specified as @option{-u}. - -@item variable -Names of all shell variables. May also be specified as @option{-v}. -@end table - -@item -G @var{globpat} -The filename expansion pattern @var{globpat} is expanded to generate -the possible completions. - -@item -W @var{wordlist} -The @var{wordlist} is split using the characters in the -@env{IFS} special variable as delimiters, and each resultant word -is expanded. -The possible completions are the members of the resultant list which -match the word being completed. - -@item -C @var{command} -@var{command} is executed in a subshell environment, and its output is -used as the possible completions. - -@item -F @var{function} -The shell function @var{function} is executed in the current shell -environment. -When it finishes, the possible completions are retrieved from the value -of the @env{COMPREPLY} array variable. - -@item -X @var{filterpat} -@var{filterpat} is a pattern as used for filename expansion. -It is applied to the list of possible completions generated by the -preceding options and arguments, and each completion matching -@var{filterpat} is removed from the list. -A leading @samp{!} in @var{filterpat} negates the pattern; in this -case, any completion not matching @var{filterpat} is removed. - -@item -P @var{prefix} -@var{prefix} is added at the beginning of each possible completion -after all other options have been applied. - -@item -S @var{suffix} -@var{suffix} is appended to each possible completion -after all other options have been applied. -@end table - -The return value is true unless an invalid option is supplied, an option -other than @option{-p} or @option{-r} is supplied without a @var{name} -argument, an attempt is made to remove a completion specification for -a @var{name} for which no specification exists, or -an error occurs adding a completion specification. - -@end table -@end ifset |