| @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.) |
| |
| @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--2020 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. |
| Command line editing is enabled by default when using an interactive shell, |
| unless the @option{--noediting} option is supplied at shell invocation. |
| Line editing is also used when using the @option{-e} option to the |
| @code{read} builtin command (@pxref{Bash Builtins}). |
| By default, the line editing commands are similar to those of Emacs. |
| A vi-style line editing interface is also available. |
| Line editing can be enabled at any time using the @option{-o emacs} or |
| @option{-o vi} options to the @code{set} builtin command |
| (@pxref{The Set Builtin}), or disabled using the @option{+o emacs} or |
| @option{+o vi} options to @code{set}. |
| @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. |
| * A Programmable Completion Example:: An example shell function for |
| generating possible completions. |
| @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}. If that |
| file does not exist or cannot be read, the ultimate default is |
| @file{/etc/inputrc}. |
| @ifset BashFeatures |
| The @w{@code{bind}} builtin command can also be used to set Readline |
| keybindings and variables. |
| @xref{Bash Builtins}. |
| @end ifset |
| |
| 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} (the default), Readline attempts to bind the control |
| characters treated specially by the kernel's terminal driver to their |
| Readline equivalents. |
| |
| @item blink-matching-paren |
| @vindex blink-matching-paren |
| If set to @samp{on}, Readline attempts to briefly move the cursor to an |
| opening parenthesis when a closing parenthesis is inserted. The default |
| is @samp{off}. |
| |
| @item colored-completion-prefix |
| @vindex colored-completion-prefix |
| If set to @samp{on}, when listing completions, Readline displays the |
| common prefix of the set of possible completions using a different color. |
| The color definitions are taken from the value of the @env{LS_COLORS} |
| environment variable. |
| The default is @samp{off}. |
| |
| @item colored-stats |
| @vindex colored-stats |
| If set to @samp{on}, Readline displays possible completions using different |
| colors to indicate their file type. |
| The color definitions are taken from the value of the @env{LS_COLORS} |
| environment variable. |
| The default is @samp{off}. |
| |
| @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-display-width |
| @vindex completion-display-width |
| The number of screen columns used to display possible matches |
| when performing completion. |
| The value is ignored if it is less than 0 or greater than the terminal |
| screen width. |
| A value of 0 will cause matches to be displayed one per line. |
| The default value is -1. |
| |
| @item completion-ignore-case |
| @vindex 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-map-case |
| @vindex completion-map-case |
| If set to @samp{on}, and @var{completion-ignore-case} is enabled, Readline |
| treats hyphens (@samp{-}) and underscores (@samp{_}) as equivalent when |
| performing case-insensitive filename matching and completion. |
| The default value is @samp{off}. |
| |
| @item completion-prefix-display-length |
| @vindex completion-prefix-display-length |
| The length in characters of the common prefix of a list of possible |
| completions that is displayed without modification. When set to a |
| value greater than zero, common prefixes longer than this value are |
| replaced with an ellipsis when displaying possible completions. |
| |
| @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 or equal to this value, |
| Readline will ask whether or not the user 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}, but |
| will be set to @samp{off} if the locale is one that contains |
| eight-bit characters. |
| |
| @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 echo-control-characters |
| @vindex echo-control-characters |
| When set to @samp{on}, on operating systems that indicate they support it, |
| readline echoes a character corresponding to a signal generated from the |
| keyboard. The default is @samp{on}. |
| |
| @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 emacs-mode-string |
| @vindex emacs-mode-string |
| If the @var{show-mode-in-prompt} variable is enabled, |
| this string is displayed immediately before the last line of the primary |
| prompt when emacs editing mode is active. The value is expanded like a |
| key binding, so the standard set of meta- and control prefixes and |
| backslash escape sequences is available. |
| Use the @samp{\1} and @samp{\2} escapes to begin and end sequences of |
| non-printing characters, which can be used to embed a terminal control |
| sequence into the mode string. |
| The default is @samp{@@}. |
| |
| @item enable-bracketed-paste |
| @vindex enable-bracketed-paste |
| When set to @samp{On}, Readline will configure the terminal in a way |
| that will enable it to insert each paste into the editing buffer as a |
| single string of characters, instead of treating each character as if |
| it had been read from the keyboard. This can prevent pasted characters |
| from being interpreted as editing commands. The default is @samp{On}. |
| |
| @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 enable-meta-key |
| When set to @samp{on}, Readline will try to enable any meta modifier |
| key the terminal claims to support when it is called. On many terminals, |
| the meta key is used to send eight-bit characters. |
| The default is @samp{on}. |
| |
| @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 the point (the |
| current cursor position) at the |
| same location on each history line retrieved with @code{previous-history} |
| or @code{next-history}. The default is @samp{off}. |
| |
| @item history-size |
| @vindex history-size |
| Set the maximum number of history entries saved in the history list. |
| If set to zero, any existing history entries are deleted and no new entries |
| are saved. |
| If set to a value less than zero, the number of history entries is not |
| limited. |
| By default, the number of history entries is not limited. |
| If an attempt is made to set @var{history-size} to a non-numeric value, |
| the maximum number of history entries will be set to 500. |
| |
| @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. |
| This variable is automatically set to @samp{on} for terminals of height 1. |
| 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}, but Readline will set it to @samp{on} if the |
| locale contains eight-bit characters. |
| 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. |
| Built-in @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{vi-move} is also a |
| synonym); @code{emacs} is equivalent to @code{emacs-standard}. |
| Applications may add additional names. |
| The default value is @code{emacs}. |
| The value of the @code{editing-mode} variable also affects the |
| default keymap. |
| |
| @item keyseq-timeout |
| Specifies the duration Readline will wait for a character when reading an |
| ambiguous key sequence (one that can form a complete key sequence using |
| the input read so far, or can take additional input to complete a longer |
| key sequence). |
| If no input is received within the timeout, Readline will use the shorter |
| but complete key sequence. |
| Readline uses this value to determine whether or not input is |
| available on the current input source (@code{rl_instream} by default). |
| The value is specified in milliseconds, so a value of 1000 means that |
| Readline will wait one second for additional input. |
| If this variable is set to a value less than or equal to zero, or to a |
| non-numeric value, Readline will wait until another key is pressed to |
| decide which key sequence to complete. |
| The default value is @code{500}. |
| |
| @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. |
| If set to @samp{off}, the leading @samp{.} must be |
| supplied by the user in the filename to be completed. |
| This variable is @samp{on} by default. |
| |
| @item menu-complete-display-prefix |
| @vindex menu-complete-display-prefix |
| If set to @samp{on}, menu completion displays the common prefix of the |
| list of possible completions (which may be empty) before cycling through |
| the list. The default is @samp{off}. |
| |
| @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}, but Readline will set it to @samp{on} if the |
| locale contains eight-bit characters. |
| |
| @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 revert-all-at-newline |
| @vindex revert-all-at-newline |
| If set to @samp{on}, Readline will undo all changes to history lines |
| before returning when @code{accept-line} is executed. By default, |
| history lines may be modified and retain individual undo lists across |
| calls to @code{readline}. 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 show-mode-in-prompt |
| @vindex show-mode-in-prompt |
| If set to @samp{on}, add a string to the beginning of the prompt |
| indicating the editing mode: emacs, vi command, or vi insertion. |
| The mode strings are user-settable (e.g., @var{emacs-mode-string}). |
| The default value is @samp{off}. |
| |
| @item skip-completed-text |
| @vindex skip-completed-text |
| If set to @samp{on}, this alters the default completion behavior when |
| inserting a single match into the line. It's only active when |
| performing completion in the middle of a word. If enabled, readline |
| does not insert characters from the completion that match characters |
| after point in the word being completed, so portions of the word |
| following the cursor are not duplicated. |
| For instance, if this is enabled, attempting completion when the cursor |
| is after the @samp{e} in @samp{Makefile} will result in @samp{Makefile} |
| rather than @samp{Makefilefile}, assuming there is a single possible |
| completion. |
| The default value is @samp{off}. |
| |
| @item vi-cmd-mode-string |
| @vindex vi-cmd-mode-string |
| If the @var{show-mode-in-prompt} variable is enabled, |
| this string is displayed immediately before the last line of the primary |
| prompt when vi editing mode is active and in command mode. |
| The value is expanded like a |
| key binding, so the standard set of meta- and control prefixes and |
| backslash escape sequences is available. |
| Use the @samp{\1} and @samp{\2} escapes to begin and end sequences of |
| non-printing characters, which can be used to embed a terminal control |
| sequence into the mode string. |
| The default is @samp{(cmd)}. |
| |
| @item vi-ins-mode-string |
| @vindex vi-ins-mode-string |
| If the @var{show-mode-in-prompt} variable is enabled, |
| this string is displayed immediately before the last line of the primary |
| prompt when vi editing mode is active and in insertion mode. |
| The value is expanded like a |
| key binding, so the standard set of meta- and control prefixes and |
| backslash escape sequences is available. |
| Use the @samp{\1} and @samp{\2} escapes to begin and end sequences of |
| non-printing characters, which can be used to embed a terminal control |
| sequence into the mode string. |
| The default is @samp{(ins)}. |
| |
| @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. |
| There can be no space between the key name and the colon -- that will be |
| interpreted as part of the key name. |
| 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 example above, @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, after any comparison operator, |
| extends to the end of the line; |
| unless otherwise noted, 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 version |
| The @code{version} test may be used to perform comparisons against |
| specific Readline versions. |
| The @code{version} expands to the current Readline version. |
| The set of comparison operators includes |
| @samp{=} (and @samp{==}), @samp{!=}, @samp{<=}, @samp{>=}, @samp{<}, |
| and @samp{>}. |
| The version number supplied on the right side of the operator consists |
| of a major version number, an optional decimal point, and an optional |
| minor version (e.g., @samp{7.1}). If the minor version is omitted, it |
| is assumed to be @samp{0}. |
| The operator may be separated from the string @code{version} and |
| from the version number argument by whitespace. |
| The following example sets a variable if the Readline version being used |
| is 7.0 or newer: |
| @example |
| $if version >= 7.0 |
| set show-mode-in-prompt on |
| $endif |
| @end example |
| |
| @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 |
| |
| @item variable |
| The @var{variable} construct provides simple equality tests for Readline |
| variables and values. |
| The permitted comparison operators are @samp{=}, @samp{==}, and @samp{!=}. |
| The variable name must be separated from the comparison operator by |
| whitespace; the operator may be separated from the value on the right hand |
| side by whitespace. |
| Both string and boolean variables may be tested. Boolean variables must be |
| tested against the values @var{on} and @var{off}. |
| The following example is equivalent to the @code{mode=emacs} test described |
| above: |
| @example |
| $if editing-mode == emacs |
| set show-mode-in-prompt on |
| $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 system-wide 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 150 or more possible completions for a word, |
| # ask whether or not the user 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. |
| |
| @ifset BashFeatures |
| @item shell-forward-word (M-C-f) |
| Move forward to the end of the next word. |
| Words are delimited by non-quoted shell metacharacters. |
| |
| @item shell-backward-word (M-C-b) |
| Move back to the start of the current or previous word. |
| Words are delimited by non-quoted shell metacharacters. |
| @end ifset |
| |
| @item previous-screen-line () |
| Attempt to move point to the same physical screen column on the previous |
| physical screen line. This will not have the desired effect if the current |
| Readline line does not take up more than one physical line or if point is not |
| greater than the length of the prompt plus the screen width. |
| |
| @item next-screen-line () |
| Attempt to move point to the same physical screen column on the next |
| physical screen line. This will not have the desired effect if the current |
| Readline line does not take up more than one physical line or if the length |
| of the current Readline line is not greater than the length of the prompt |
| plus the screen width. |
| |
| @item clear-display (M-C-l) |
| Clear the screen and, if possible, the terminal's scrollback buffer, |
| then redraw the current line, |
| leaving the current line at the top of the screen. |
| |
| @item clear-screen (C-l) |
| Clear the screen, |
| then 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. |
| This command sets the region to the matched text and activates the mark. |
| |
| @item forward-search-history (C-s) |
| Search forward starting at the current line and moving `down' through |
| the history as necessary. This is an incremental search. |
| This command sets the region to the matched text and activates the mark. |
| |
| @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. |
| The search string may match anywhere in a history line. |
| |
| @item non-incremental-forward-search-history (M-n) |
| Search forward starting at the current line and moving `down' |
| through the history as necessary using a non-incremental search |
| for a string supplied by the user. |
| The search string may match anywhere in a history line. |
| |
| @item history-search-forward () |
| Search forward through the history for the string of characters |
| between the start of the current line and the point. |
| The search string must match at the beginning of a history line. |
| 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. |
| The search string must match at the beginning of a history line. |
| This is a non-incremental search. |
| By default, this command is unbound. |
| |
| @item history-substring-search-forward () |
| Search forward through the history for the string of characters |
| between the start of the current line and the point. |
| The search string may match anywhere in a history line. |
| This is a non-incremental search. |
| By default, this command is unbound. |
| |
| @item history-substring-search-backward () |
| Search backward through the history for the string of characters |
| between the start of the current line and the point. |
| The search string may match anywhere in a history line. |
| 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 a numeric argument, behave exactly like @code{yank-nth-arg}. |
| Successive calls to @code{yank-last-arg} move back through the history |
| list, inserting the last word (or the word specified by the argument to |
| the first call) of each line in turn. |
| Any numeric argument supplied to these successive calls determines |
| the direction to move through the history. A negative argument switches |
| the direction through the history (back or forward). |
| The history expansion facilities are used to extract the last argument, |
| as if the @samp{!$} history expansion had been specified. |
| |
| @item operate-and-get-next (C-o) |
| Accept the current line for return to the calling application as if a |
| newline had been entered, |
| and fetch the next line relative to the current line from the history |
| for editing. |
| A numeric argument, if supplied, specifies the history entry to use instead |
| of the current line. |
| |
| @end ftable |
| |
| @node Commands For Text |
| @subsection Commands For Changing Text |
| |
| @ftable @code |
| |
| @item @i{end-of-file} (usually C-d) |
| The character indicating end-of-file as set, for example, by |
| @code{stty}. If this character is read when there are no characters |
| on the line, and point is at the beginning of the line, Readline |
| interprets it as the end of input and returns @sc{eof}. |
| |
| @item delete-char (C-d) |
| Delete the character at point. If this function is bound to the |
| same character as the tty @sc{eof} character, as @kbd{C-d} |
| commonly is, see above for the effects. |
| |
| @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 bracketed-paste-begin () |
| This function is intended to be bound to the "bracketed paste" escape |
| sequence sent by some terminals, and such a binding is assigned by default. |
| It allows Readline to insert the pasted text as a single unit without treating |
| each character as if it had been read from the keyboard. The characters |
| are inserted as if each one was bound to @code{self-insert} instead of |
| executing any editing commands. |
| |
| Bracketed paste sets the region (the characters between point and the mark) |
| to the inserted text. It uses the concept of an @emph{active mark}: when the |
| mark is active, Readline redisplay uses the terminal's standout mode to |
| denote the region. |
| |
| @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. |
| With a negative numeric argument, kill backward from the cursor to the |
| beginning of the current line. |
| |
| @item backward-kill-line (C-x Rubout) |
| Kill backward from the cursor to the beginning of the current line. |
| With a negative numeric argument, kill forward from the cursor to the |
| end of the current 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}. |
| |
| @ifset BashFeatures |
| @item shell-kill-word (M-C-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{shell-forward-word}. |
| |
| @item shell-backward-kill-word () |
| Kill the word behind point. |
| Word boundaries are the same as @code{shell-backward-word}. |
| @end ifset |
| |
| @item shell-transpose-words (M-C-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. |
| Word boundaries are the same as @code{shell-forward-word} and |
| @code{shell-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 nor 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. |
| When displaying completions, Readline sets the number of columns used |
| for display to the value of @code{completion-display-width}, the value of |
| the environment variable @env{COLUMNS}, or the screen width, in that order. |
| |
| @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 menu-complete-backward () |
| Identical to @code{menu-complete}, but moves backward through the list |
| of possible completions, as if @code{menu-complete} had been given a |
| negative argument. |
| |
| @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 dabbrev-expand () |
| Attempt menu 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. |
| |
| @item print-last-kbd-macro () |
| Print the last keboard macro defined in a format suitable for the |
| @var{inputrc} file. |
| |
| @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-lowercase-version (M-A, M-B, M-@var{x}, @dots{}) |
| If the metafied character @var{x} is upper case, run the command |
| that is bound to the corresponding metafied lower case character. |
| The behavior is undefined if @var{x} is already lower case. |
| |
| @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 skip-csi-sequence () |
| Read enough characters to consume a multi-key sequence such as those |
| defined for keys like Home and End. Such sequences begin with a |
| Control Sequence Indicator (CSI), usually ESC-[. If this sequence is |
| bound to "\e[", keys producing such sequences will have no effect |
| unless explicitly bound to a readline command, instead of inserting |
| stray characters into the editing buffer. This is unbound by default, |
| but usually bound to ESC-[. |
| |
| @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 edit-and-execute-command (C-x C-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} 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 the empty string (completion attempted at the |
| beginning of an empty line), any compspec defined with |
| the @option{-E} option to @code{complete} is used. |
| 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. |
| If those searches do not result in a compspec, any compspec defined with |
| the @option{-D} option to @code{complete} is used as the default. |
| If there is no default compspec, Bash attempts alias expansion |
| on the command word as a final resort, and attempts to find a compspec |
| for the command word from any successful expansion |
| |
| 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 within the string, in order to provide a |
| mechanism for the words to contain shell metacharacters or characters |
| in the value of @env{IFS}. |
| 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}, |
| @env{COMP_POINT}, @env{COMP_KEY}, and @env{COMP_TYPE} 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 ($1) is the |
| name of the command whose arguments are being completed, the |
| second argument ($2) is the word being completed, and the third argument |
| ($3) 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} and @code{compopt} builtins described below |
| (@pxref{Programmable Completion Builtins}), to generate the matches. |
| It must put the possible completions in the @env{COMPREPLY} array |
| variable, one per array element. |
| |
| 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. |
| If the @code{nocasematch} shell option |
| (see the description of @code{shopt} in @ref{The Shopt Builtin}) |
| is enabled, the match is performed without regard to the case |
| of alphabetic characters. |
| |
| 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. |
| |
| There is some support for dynamically modifying completions. This is |
| most useful when used in combination with a default completion specified |
| with @option{-D}. It's possible for shell functions executed as completion |
| handlers to indicate that completion should be retried by returning an |
| exit status of 124. If a shell function returns 124, and changes |
| the compspec associated with the command on which completion is being |
| attempted (supplied as the first argument when the function is executed), |
| programmable completion restarts from the beginning, with an |
| attempt to find a new compspec for that command. This allows a set of |
| completions to be built dynamically as completion is attempted, rather than |
| being loaded all at once. |
| |
| For instance, assuming that there is a library of compspecs, each kept in a |
| file corresponding to the name of the command, the following default |
| completion function would load completions dynamically: |
| |
| @example |
| _completion_loader() |
| @{ |
| . "/etc/bash_completion.d/$1.sh" >/dev/null 2>&1 && return 124 |
| @} |
| complete -D -F _completion_loader -o bashdefault -o default |
| @end example |
| |
| @node Programmable Completion Builtins |
| @section Programmable Completion Builtins |
| @cindex completion builtins |
| |
| Three builtin commands are available to manipulate the programmable completion |
| facilities: one to specify how the arguments to a particular command are to |
| be completed, and two to modify the completion as it is happening. |
| |
| @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}] [-DEI] [-A @var{action}] [-G @var{globpat}] |
| [-W @var{wordlist}] [-F @var{function}] [-C @var{command}] [-X @var{filterpat}] |
| [-P @var{prefix}] [-S @var{suffix}] @var{name} [@var{name} @dots{}]} |
| @code{complete -pr [-DEI] [@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 @option{-D} option indicates that other supplied options and actions should |
| apply to the ``default'' command completion; that is, completion attempted |
| on a command for which no completion has previously been defined. |
| The @option{-E} option indicates that other supplied options and actions should |
| apply to ``empty'' command completion; that is, completion attempted on a |
| blank line. |
| The @option{-I} option indicates that other supplied options and actions should |
| apply to completion on the initial non-assignment word on the line, or after a |
| command delimiter such as @samp{;} or @samp{|}, which is usually command |
| name completion. |
| If multiple options are supplied, the @option{-D} option takes precedence |
| over @option{-E}, and both take precedence over @option{-I}. |
| If any of @option{-D}, @option{-E}, or @option{-I} are supplied, any other |
| @var{name} arguments are ignored; these completions only apply to the case |
| specified by the option. |
| |
| 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, |
| quoting special characters, or suppressing trailing spaces). |
| This option is intended to be used with shell functions specified |
| with @option{-F}. |
| |
| @item noquote |
| Tell Readline not to quote the completed words if they are filenames |
| (quoting filenames is the default). |
| |
| @item nosort |
| Tell Readline not to sort the list of possible completions alphabetically. |
| |
| @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 -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 is executed, $1 is the name of the command whose arguments are |
| being completed, $2 is the word being completed, and $3 is the word |
| preceding the word being completed, as described above |
| (@pxref{Programmable Completion}). |
| When it finishes, the possible completions are retrieved from the value |
| of the @env{COMPREPLY} array variable. |
| |
| @item -G @var{globpat} |
| The filename expansion pattern @var{globpat} is expanded to generate |
| the possible completions. |
| |
| @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. |
| |
| @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 -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. |
| @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. |
| |
| @item compopt |
| @btindex compopt |
| @example |
| @code{compopt} [-o @var{option}] [-DEI] [+o @var{option}] [@var{name}] |
| @end example |
| Modify completion options for each @var{name} according to the |
| @var{option}s, or for the currently-executing completion if no @var{name}s |
| are supplied. |
| If no @var{option}s are given, display the completion options for each |
| @var{name} or the current completion. |
| The possible values of @var{option} are those valid for the @code{complete} |
| builtin described above. |
| The @option{-D} option indicates that other supplied options should |
| apply to the ``default'' command completion; that is, completion attempted |
| on a command for which no completion has previously been defined. |
| The @option{-E} option indicates that other supplied options should |
| apply to ``empty'' command completion; that is, completion attempted on a |
| blank line. |
| The @option{-I} option indicates that other supplied options should |
| apply to completion on the initial non-assignment word on the line, or after a |
| command delimiter such as @samp{;} or @samp{|}, which is usually command |
| name completion. |
| |
| If multiple options are supplied, the @option{-D} option takes precedence |
| over @option{-E}, and both take precedence over @option{-I} |
| |
| The return value is true unless an invalid option is supplied, an attempt |
| is made to modify the options for a @var{name} for which no completion |
| specification exists, or an output error occurs. |
| |
| @end table |
| |
| @node A Programmable Completion Example |
| @section A Programmable Completion Example |
| |
| The most common way to obtain additional completion functionality beyond |
| the default actions @code{complete} and @code{compgen} provide is to use |
| a shell function and bind it to a particular command using @code{complete -F}. |
| |
| The following function provides completions for the @code{cd} builtin. |
| It is a reasonably good example of what shell functions must do when |
| used for completion. This function uses the word passed as @code{$2} |
| to determine the directory name to complete. You can also use the |
| @code{COMP_WORDS} array variable; the current word is indexed by the |
| @code{COMP_CWORD} variable. |
| |
| The function relies on the @code{complete} and @code{compgen} builtins |
| to do much of the work, adding only the things that the Bash @code{cd} |
| does beyond accepting basic directory names: |
| tilde expansion (@pxref{Tilde Expansion}), |
| searching directories in @var{$CDPATH}, which is described above |
| (@pxref{Bourne Shell Builtins}), |
| and basic support for the @code{cdable_vars} shell option |
| (@pxref{The Shopt Builtin}). |
| @code{_comp_cd} modifies the value of @var{IFS} so that it contains only |
| a newline to accommodate file names containing spaces and tabs -- |
| @code{compgen} prints the possible completions it generates one per line. |
| |
| Possible completions go into the @var{COMPREPLY} array variable, one |
| completion per array element. The programmable completion system retrieves |
| the completions from there when the function returns. |
| |
| @example |
| # A completion function for the cd builtin |
| # based on the cd completion function from the bash_completion package |
| _comp_cd() |
| @{ |
| local IFS=$' \t\n' # normalize IFS |
| local cur _skipdot _cdpath |
| local i j k |
| |
| # Tilde expansion, which also expands tilde to full pathname |
| case "$2" in |
| \~*) eval cur="$2" ;; |
| *) cur=$2 ;; |
| esac |
| |
| # no cdpath or absolute pathname -- straight directory completion |
| if [[ -z "$@{CDPATH:-@}" ]] || [[ "$cur" == @@(./*|../*|/*) ]]; then |
| # compgen prints paths one per line; could also use while loop |
| IFS=$'\n' |
| COMPREPLY=( $(compgen -d -- "$cur") ) |
| IFS=$' \t\n' |
| # CDPATH+directories in the current directory if not in CDPATH |
| else |
| IFS=$'\n' |
| _skipdot=false |
| # preprocess CDPATH to convert null directory names to . |
| _cdpath=$@{CDPATH/#:/.:@} |
| _cdpath=$@{_cdpath//::/:.:@} |
| _cdpath=$@{_cdpath/%:/:.@} |
| for i in $@{_cdpath//:/$'\n'@}; do |
| if [[ $i -ef . ]]; then _skipdot=true; fi |
| k="$@{#COMPREPLY[@@]@}" |
| for j in $( compgen -d -- "$i/$cur" ); do |
| COMPREPLY[k++]=$@{j#$i/@} # cut off directory |
| done |
| done |
| $_skipdot || COMPREPLY+=( $(compgen -d -- "$cur") ) |
| IFS=$' \t\n' |
| fi |
| |
| # variable names if appropriate shell option set and no completions |
| if shopt -q cdable_vars && [[ $@{#COMPREPLY[@@]@} -eq 0 ]]; then |
| COMPREPLY=( $(compgen -v -- "$cur") ) |
| fi |
| |
| return 0 |
| @} |
| @end example |
| |
| We install the completion function using the @option{-F} option to |
| @code{complete}: |
| |
| @example |
| # Tell readline to quote appropriate and append slashes to directories; |
| # use the bash default completion for other arguments |
| complete -o filenames -o nospace -o bashdefault -F _comp_cd cd |
| @end example |
| |
| @noindent |
| Since we'd like Bash and Readline to take care of some |
| of the other details for us, we use several other options to tell Bash |
| and Readline what to do. The @option{-o filenames} option tells Readline |
| that the possible completions should be treated as filenames, and quoted |
| appropriately. That option will also cause Readline to append a slash to |
| filenames it can determine are directories (which is why we might want to |
| extend @code{_comp_cd} to append a slash if we're using directories found |
| via @var{CDPATH}: Readline can't tell those completions are directories). |
| The @option{-o nospace} option tells Readline to not append a space |
| character to the directory name, in case we want to append to it. |
| The @option{-o bashdefault} option brings in the rest of the "Bash default" |
| completions -- possible completion that Bash adds to the default Readline |
| set. These include things like command name completion, variable completion |
| for words beginning with @samp{$} or @samp{$@{}, completions containing pathname |
| expansion patterns (@pxref{Filename Expansion}), and so on. |
| |
| Once installed using @code{complete}, @code{_comp_cd} will be called every |
| time we attempt word completion for a @code{cd} command. |
| |
| Many more examples -- an extensive collection of completions for most of |
| the common GNU, Unix, and Linux commands -- are available as part of the |
| bash_completion project. This is installed by default on many GNU/Linux |
| distributions. Originally written by Ian Macdonald, the project now lives |
| at @url{https://github.com/scop/bash-completion/}. There are ports for |
| other systems such as Solaris and Mac OS X. |
| |
| An older version of the bash_completion package is distributed with bash |
| in the @file{examples/complete} subdirectory. |
| |
| @end ifset |