15796c8dcSSimon Schubert@comment %**start of header (This is for running Texinfo on a region.)
25796c8dcSSimon Schubert@setfilename rluser.info
35796c8dcSSimon Schubert@comment %**end of header (This is for running Texinfo on a region.)
45796c8dcSSimon Schubert
55796c8dcSSimon Schubert@ignore
65796c8dcSSimon SchubertThis file documents the end user interface to the GNU command line
75796c8dcSSimon Schubertediting features.  It is to be an appendix to manuals for programs which
85796c8dcSSimon Schubertuse these features.  There is a document entitled "readline.texinfo"
95796c8dcSSimon Schubertwhich contains both end-user and programmer documentation for the
105796c8dcSSimon SchubertGNU Readline Library.
115796c8dcSSimon Schubert
12*a45ae5f8SJohn MarinoCopyright (C) 1988--2011 Free Software Foundation, Inc.
135796c8dcSSimon Schubert
145796c8dcSSimon SchubertAuthored by Brian Fox and Chet Ramey.
155796c8dcSSimon Schubert
165796c8dcSSimon SchubertPermission is granted to process this file through Tex and print the
175796c8dcSSimon Schubertresults, provided the printed document carries copying permission notice
185796c8dcSSimon Schubertidentical to this one except for the removal of this paragraph (this
195796c8dcSSimon Schubertparagraph not being relevant to the printed manual).
205796c8dcSSimon Schubert
215796c8dcSSimon SchubertPermission is granted to make and distribute verbatim copies of this manual
225796c8dcSSimon Schubertprovided the copyright notice and this permission notice are preserved on
235796c8dcSSimon Schubertall copies.
245796c8dcSSimon Schubert
255796c8dcSSimon SchubertPermission is granted to copy and distribute modified versions of this
265796c8dcSSimon Schubertmanual under the conditions for verbatim copying, provided also that the
275796c8dcSSimon SchubertGNU Copyright statement is available to the distributee, and provided that
285796c8dcSSimon Schubertthe entire resulting derived work is distributed under the terms of a
295796c8dcSSimon Schubertpermission notice identical to this one.
305796c8dcSSimon Schubert
315796c8dcSSimon SchubertPermission is granted to copy and distribute translations of this manual
325796c8dcSSimon Schubertinto another language, under the above conditions for modified versions.
335796c8dcSSimon Schubert@end ignore
345796c8dcSSimon Schubert
355796c8dcSSimon Schubert@comment If you are including this manual as an appendix, then set the
365796c8dcSSimon Schubert@comment variable readline-appendix.
375796c8dcSSimon Schubert
385796c8dcSSimon Schubert@ifclear BashFeatures
395796c8dcSSimon Schubert@defcodeindex bt
405796c8dcSSimon Schubert@end ifclear
415796c8dcSSimon Schubert
425796c8dcSSimon Schubert@node Command Line Editing
435796c8dcSSimon Schubert@chapter Command Line Editing
445796c8dcSSimon Schubert
455796c8dcSSimon SchubertThis chapter describes the basic features of the @sc{gnu}
465796c8dcSSimon Schubertcommand line editing interface.
475796c8dcSSimon Schubert@ifset BashFeatures
485796c8dcSSimon SchubertCommand line editing is provided by the Readline library, which is
495796c8dcSSimon Schubertused by several different programs, including Bash.
50*a45ae5f8SJohn MarinoCommand line editing is enabled by default when using an interactive shell,
51*a45ae5f8SJohn Marinounless the @option{--noediting} option is supplied at shell invocation.
52*a45ae5f8SJohn MarinoLine editing is also used when using the @option{-e} option to the
53*a45ae5f8SJohn Marino@code{read} builtin command (@pxref{Bash Builtins}).
54*a45ae5f8SJohn MarinoBy default, the line editing commands are similar to those of Emacs.
55*a45ae5f8SJohn MarinoA vi-style line editing interface is also available.
56*a45ae5f8SJohn MarinoLine editing can be enabled at any time using the @option{-o emacs} or
57*a45ae5f8SJohn Marino@option{-o vi} options to the @code{set} builtin command
58*a45ae5f8SJohn Marino(@pxref{The Set Builtin}), or disabled using the @option{+o emacs} or
59*a45ae5f8SJohn Marino@option{+o vi} options to @code{set}.
605796c8dcSSimon Schubert@end ifset
615796c8dcSSimon Schubert
625796c8dcSSimon Schubert@menu
635796c8dcSSimon Schubert* Introduction and Notation::	Notation used in this text.
645796c8dcSSimon Schubert* Readline Interaction::	The minimum set of commands for editing a line.
655796c8dcSSimon Schubert* Readline Init File::		Customizing Readline from a user's view.
665796c8dcSSimon Schubert* Bindable Readline Commands::	A description of most of the Readline commands
675796c8dcSSimon Schubert				available for binding
685796c8dcSSimon Schubert* Readline vi Mode::		A short description of how to make Readline
695796c8dcSSimon Schubert				behave like the vi editor.
705796c8dcSSimon Schubert@ifset BashFeatures
715796c8dcSSimon Schubert* Programmable Completion::	How to specify the possible completions for
725796c8dcSSimon Schubert				a specific command.
735796c8dcSSimon Schubert* Programmable Completion Builtins::	Builtin commands to specify how to
745796c8dcSSimon Schubert				complete arguments for a particular command.
755796c8dcSSimon Schubert@end ifset
765796c8dcSSimon Schubert@end menu
775796c8dcSSimon Schubert
785796c8dcSSimon Schubert@node Introduction and Notation
795796c8dcSSimon Schubert@section Introduction to Line Editing
805796c8dcSSimon Schubert
815796c8dcSSimon SchubertThe following paragraphs describe the notation used to represent
825796c8dcSSimon Schubertkeystrokes.
835796c8dcSSimon Schubert
845796c8dcSSimon SchubertThe text @kbd{C-k} is read as `Control-K' and describes the character
855796c8dcSSimon Schubertproduced when the @key{k} key is pressed while the Control key
865796c8dcSSimon Schubertis depressed.
875796c8dcSSimon Schubert
885796c8dcSSimon SchubertThe text @kbd{M-k} is read as `Meta-K' and describes the character
895796c8dcSSimon Schubertproduced when the Meta key (if you have one) is depressed, and the @key{k}
905796c8dcSSimon Schubertkey is pressed.
915796c8dcSSimon SchubertThe Meta key is labeled @key{ALT} on many keyboards.
925796c8dcSSimon SchubertOn keyboards with two keys labeled @key{ALT} (usually to either side of
935796c8dcSSimon Schubertthe space bar), the @key{ALT} on the left side is generally set to
945796c8dcSSimon Schubertwork as a Meta key.
955796c8dcSSimon SchubertThe @key{ALT} key on the right may also be configured to work as a
965796c8dcSSimon SchubertMeta key or may be configured as some other modifier, such as a
975796c8dcSSimon SchubertCompose key for typing accented characters.
985796c8dcSSimon Schubert
995796c8dcSSimon SchubertIf you do not have a Meta or @key{ALT} key, or another key working as
1005796c8dcSSimon Schuberta Meta key, the identical keystroke can be generated by typing @key{ESC}
1015796c8dcSSimon Schubert@emph{first}, and then typing @key{k}.
1025796c8dcSSimon SchubertEither process is known as @dfn{metafying} the @key{k} key.
1035796c8dcSSimon Schubert
1045796c8dcSSimon SchubertThe text @kbd{M-C-k} is read as `Meta-Control-k' and describes the
1055796c8dcSSimon Schubertcharacter produced by @dfn{metafying} @kbd{C-k}.
1065796c8dcSSimon Schubert
1075796c8dcSSimon SchubertIn addition, several keys have their own names.  Specifically,
1085796c8dcSSimon Schubert@key{DEL}, @key{ESC}, @key{LFD}, @key{SPC}, @key{RET}, and @key{TAB} all
1095796c8dcSSimon Schubertstand for themselves when seen in this text, or in an init file
1105796c8dcSSimon Schubert(@pxref{Readline Init File}).
1115796c8dcSSimon SchubertIf your keyboard lacks a @key{LFD} key, typing @key{C-j} will
1125796c8dcSSimon Schubertproduce the desired character.
1135796c8dcSSimon SchubertThe @key{RET} key may be labeled @key{Return} or @key{Enter} on
1145796c8dcSSimon Schubertsome keyboards.
1155796c8dcSSimon Schubert
1165796c8dcSSimon Schubert@node Readline Interaction
1175796c8dcSSimon Schubert@section Readline Interaction
1185796c8dcSSimon Schubert@cindex interaction, readline
1195796c8dcSSimon Schubert
1205796c8dcSSimon SchubertOften during an interactive session you type in a long line of text,
1215796c8dcSSimon Schubertonly to notice that the first word on the line is misspelled.  The
1225796c8dcSSimon SchubertReadline library gives you a set of commands for manipulating the text
1235796c8dcSSimon Schubertas you type it in, allowing you to just fix your typo, and not forcing
1245796c8dcSSimon Schubertyou to retype the majority of the line.  Using these editing commands,
1255796c8dcSSimon Schubertyou move the cursor to the place that needs correction, and delete or
1265796c8dcSSimon Schubertinsert the text of the corrections.  Then, when you are satisfied with
1275796c8dcSSimon Schubertthe line, you simply press @key{RET}.  You do not have to be at the
1285796c8dcSSimon Schubertend of the line to press @key{RET}; the entire line is accepted
1295796c8dcSSimon Schubertregardless of the location of the cursor within the line.
1305796c8dcSSimon Schubert
1315796c8dcSSimon Schubert@menu
1325796c8dcSSimon Schubert* Readline Bare Essentials::	The least you need to know about Readline.
1335796c8dcSSimon Schubert* Readline Movement Commands::	Moving about the input line.
1345796c8dcSSimon Schubert* Readline Killing Commands::	How to delete text, and how to get it back!
1355796c8dcSSimon Schubert* Readline Arguments::		Giving numeric arguments to commands.
1365796c8dcSSimon Schubert* Searching::			Searching through previous lines.
1375796c8dcSSimon Schubert@end menu
1385796c8dcSSimon Schubert
1395796c8dcSSimon Schubert@node Readline Bare Essentials
1405796c8dcSSimon Schubert@subsection Readline Bare Essentials
1415796c8dcSSimon Schubert@cindex notation, readline
1425796c8dcSSimon Schubert@cindex command editing
1435796c8dcSSimon Schubert@cindex editing command lines
1445796c8dcSSimon Schubert
1455796c8dcSSimon SchubertIn order to enter characters into the line, simply type them.  The typed
1465796c8dcSSimon Schubertcharacter appears where the cursor was, and then the cursor moves one
1475796c8dcSSimon Schubertspace to the right.  If you mistype a character, you can use your
1485796c8dcSSimon Schuberterase character to back up and delete the mistyped character.
1495796c8dcSSimon Schubert
1505796c8dcSSimon SchubertSometimes you may mistype a character, and
1515796c8dcSSimon Schubertnot notice the error until you have typed several other characters.  In
1525796c8dcSSimon Schubertthat case, you can type @kbd{C-b} to move the cursor to the left, and then
1535796c8dcSSimon Schubertcorrect your mistake.  Afterwards, you can move the cursor to the right
1545796c8dcSSimon Schubertwith @kbd{C-f}.
1555796c8dcSSimon Schubert
1565796c8dcSSimon SchubertWhen you add text in the middle of a line, you will notice that characters
1575796c8dcSSimon Schubertto the right of the cursor are `pushed over' to make room for the text
1585796c8dcSSimon Schubertthat you have inserted.  Likewise, when you delete text behind the cursor,
1595796c8dcSSimon Schubertcharacters to the right of the cursor are `pulled back' to fill in the
1605796c8dcSSimon Schubertblank space created by the removal of the text.  A list of the bare
1615796c8dcSSimon Schubertessentials for editing the text of an input line follows.
1625796c8dcSSimon Schubert
1635796c8dcSSimon Schubert@table @asis
1645796c8dcSSimon Schubert@item @kbd{C-b}
1655796c8dcSSimon SchubertMove back one character.
1665796c8dcSSimon Schubert@item @kbd{C-f}
1675796c8dcSSimon SchubertMove forward one character.
1685796c8dcSSimon Schubert@item @key{DEL} or @key{Backspace}
1695796c8dcSSimon SchubertDelete the character to the left of the cursor.
1705796c8dcSSimon Schubert@item @kbd{C-d}
1715796c8dcSSimon SchubertDelete the character underneath the cursor.
1725796c8dcSSimon Schubert@item @w{Printing characters}
1735796c8dcSSimon SchubertInsert the character into the line at the cursor.
1745796c8dcSSimon Schubert@item @kbd{C-_} or @kbd{C-x C-u}
1755796c8dcSSimon SchubertUndo the last editing command.  You can undo all the way back to an
1765796c8dcSSimon Schubertempty line.
1775796c8dcSSimon Schubert@end table
1785796c8dcSSimon Schubert
1795796c8dcSSimon Schubert@noindent
1805796c8dcSSimon Schubert(Depending on your configuration, the @key{Backspace} key be set to
1815796c8dcSSimon Schubertdelete the character to the left of the cursor and the @key{DEL} key set
1825796c8dcSSimon Schubertto delete the character underneath the cursor, like @kbd{C-d}, rather
1835796c8dcSSimon Schubertthan the character to the left of the cursor.)
1845796c8dcSSimon Schubert
1855796c8dcSSimon Schubert@node Readline Movement Commands
1865796c8dcSSimon Schubert@subsection Readline Movement Commands
1875796c8dcSSimon Schubert
1885796c8dcSSimon Schubert
1895796c8dcSSimon SchubertThe above table describes the most basic keystrokes that you need
1905796c8dcSSimon Schubertin order to do editing of the input line.  For your convenience, many
1915796c8dcSSimon Schubertother commands have been added in addition to @kbd{C-b}, @kbd{C-f},
1925796c8dcSSimon Schubert@kbd{C-d}, and @key{DEL}.  Here are some commands for moving more rapidly
1935796c8dcSSimon Schubertabout the line.
1945796c8dcSSimon Schubert
1955796c8dcSSimon Schubert@table @kbd
1965796c8dcSSimon Schubert@item C-a
1975796c8dcSSimon SchubertMove to the start of the line.
1985796c8dcSSimon Schubert@item C-e
1995796c8dcSSimon SchubertMove to the end of the line.
2005796c8dcSSimon Schubert@item M-f
2015796c8dcSSimon SchubertMove forward a word, where a word is composed of letters and digits.
2025796c8dcSSimon Schubert@item M-b
2035796c8dcSSimon SchubertMove backward a word.
2045796c8dcSSimon Schubert@item C-l
2055796c8dcSSimon SchubertClear the screen, reprinting the current line at the top.
2065796c8dcSSimon Schubert@end table
2075796c8dcSSimon Schubert
2085796c8dcSSimon SchubertNotice how @kbd{C-f} moves forward a character, while @kbd{M-f} moves
2095796c8dcSSimon Schubertforward a word.  It is a loose convention that control keystrokes
2105796c8dcSSimon Schubertoperate on characters while meta keystrokes operate on words.
2115796c8dcSSimon Schubert
2125796c8dcSSimon Schubert@node Readline Killing Commands
2135796c8dcSSimon Schubert@subsection Readline Killing Commands
2145796c8dcSSimon Schubert
2155796c8dcSSimon Schubert@cindex killing text
2165796c8dcSSimon Schubert@cindex yanking text
2175796c8dcSSimon Schubert
2185796c8dcSSimon Schubert@dfn{Killing} text means to delete the text from the line, but to save
2195796c8dcSSimon Schubertit away for later use, usually by @dfn{yanking} (re-inserting)
2205796c8dcSSimon Schubertit back into the line.
2215796c8dcSSimon Schubert(`Cut' and `paste' are more recent jargon for `kill' and `yank'.)
2225796c8dcSSimon Schubert
2235796c8dcSSimon SchubertIf the description for a command says that it `kills' text, then you can
2245796c8dcSSimon Schubertbe sure that you can get the text back in a different (or the same)
2255796c8dcSSimon Schubertplace later.
2265796c8dcSSimon Schubert
2275796c8dcSSimon SchubertWhen you use a kill command, the text is saved in a @dfn{kill-ring}.
2285796c8dcSSimon SchubertAny number of consecutive kills save all of the killed text together, so
2295796c8dcSSimon Schubertthat when you yank it back, you get it all.  The kill
2305796c8dcSSimon Schubertring is not line specific; the text that you killed on a previously
2315796c8dcSSimon Schuberttyped line is available to be yanked back later, when you are typing
2325796c8dcSSimon Schubertanother line.
2335796c8dcSSimon Schubert@cindex kill ring
2345796c8dcSSimon Schubert
2355796c8dcSSimon SchubertHere is the list of commands for killing text.
2365796c8dcSSimon Schubert
2375796c8dcSSimon Schubert@table @kbd
2385796c8dcSSimon Schubert@item C-k
2395796c8dcSSimon SchubertKill the text from the current cursor position to the end of the line.
2405796c8dcSSimon Schubert
2415796c8dcSSimon Schubert@item M-d
2425796c8dcSSimon SchubertKill from the cursor to the end of the current word, or, if between
2435796c8dcSSimon Schubertwords, to the end of the next word.
2445796c8dcSSimon SchubertWord boundaries are the same as those used by @kbd{M-f}.
2455796c8dcSSimon Schubert
2465796c8dcSSimon Schubert@item M-@key{DEL}
2475796c8dcSSimon SchubertKill from the cursor the start of the current word, or, if between
2485796c8dcSSimon Schubertwords, to the start of the previous word.
2495796c8dcSSimon SchubertWord boundaries are the same as those used by @kbd{M-b}.
2505796c8dcSSimon Schubert
2515796c8dcSSimon Schubert@item C-w
2525796c8dcSSimon SchubertKill from the cursor to the previous whitespace.  This is different than
2535796c8dcSSimon Schubert@kbd{M-@key{DEL}} because the word boundaries differ.
2545796c8dcSSimon Schubert
2555796c8dcSSimon Schubert@end table
2565796c8dcSSimon Schubert
2575796c8dcSSimon SchubertHere is how to @dfn{yank} the text back into the line.  Yanking
2585796c8dcSSimon Schubertmeans to copy the most-recently-killed text from the kill buffer.
2595796c8dcSSimon Schubert
2605796c8dcSSimon Schubert@table @kbd
2615796c8dcSSimon Schubert@item C-y
2625796c8dcSSimon SchubertYank the most recently killed text back into the buffer at the cursor.
2635796c8dcSSimon Schubert
2645796c8dcSSimon Schubert@item M-y
2655796c8dcSSimon SchubertRotate the kill-ring, and yank the new top.  You can only do this if
2665796c8dcSSimon Schubertthe prior command is @kbd{C-y} or @kbd{M-y}.
2675796c8dcSSimon Schubert@end table
2685796c8dcSSimon Schubert
2695796c8dcSSimon Schubert@node Readline Arguments
2705796c8dcSSimon Schubert@subsection Readline Arguments
2715796c8dcSSimon Schubert
2725796c8dcSSimon SchubertYou can pass numeric arguments to Readline commands.  Sometimes the
2735796c8dcSSimon Schubertargument acts as a repeat count, other times it is the @i{sign} of the
2745796c8dcSSimon Schubertargument that is significant.  If you pass a negative argument to a
2755796c8dcSSimon Schubertcommand which normally acts in a forward direction, that command will
2765796c8dcSSimon Schubertact in a backward direction.  For example, to kill text back to the
2775796c8dcSSimon Schubertstart of the line, you might type @samp{M-- C-k}.
2785796c8dcSSimon Schubert
2795796c8dcSSimon SchubertThe general way to pass numeric arguments to a command is to type meta
2805796c8dcSSimon Schubertdigits before the command.  If the first `digit' typed is a minus
2815796c8dcSSimon Schubertsign (@samp{-}), then the sign of the argument will be negative.  Once
2825796c8dcSSimon Schubertyou have typed one meta digit to get the argument started, you can type
2835796c8dcSSimon Schubertthe remainder of the digits, and then the command.  For example, to give
2845796c8dcSSimon Schubertthe @kbd{C-d} command an argument of 10, you could type @samp{M-1 0 C-d},
2855796c8dcSSimon Schubertwhich will delete the next ten characters on the input line.
2865796c8dcSSimon Schubert
2875796c8dcSSimon Schubert@node Searching
2885796c8dcSSimon Schubert@subsection Searching for Commands in the History
2895796c8dcSSimon Schubert
2905796c8dcSSimon SchubertReadline provides commands for searching through the command history
2915796c8dcSSimon Schubert@ifset BashFeatures
2925796c8dcSSimon Schubert(@pxref{Bash History Facilities})
2935796c8dcSSimon Schubert@end ifset
2945796c8dcSSimon Schubertfor lines containing a specified string.
2955796c8dcSSimon SchubertThere are two search modes:  @dfn{incremental} and @dfn{non-incremental}.
2965796c8dcSSimon Schubert
2975796c8dcSSimon SchubertIncremental searches begin before the user has finished typing the
2985796c8dcSSimon Schubertsearch string.
2995796c8dcSSimon SchubertAs each character of the search string is typed, Readline displays
3005796c8dcSSimon Schubertthe next entry from the history matching the string typed so far.
3015796c8dcSSimon SchubertAn incremental search requires only as many characters as needed to
3025796c8dcSSimon Schubertfind the desired history entry.
3035796c8dcSSimon SchubertTo search backward in the history for a particular string, type
3045796c8dcSSimon Schubert@kbd{C-r}.  Typing @kbd{C-s} searches forward through the history.
3055796c8dcSSimon SchubertThe characters present in the value of the @code{isearch-terminators} variable
3065796c8dcSSimon Schubertare used to terminate an incremental search.
3075796c8dcSSimon SchubertIf that variable has not been assigned a value, the @key{ESC} and
3085796c8dcSSimon Schubert@kbd{C-J} characters will terminate an incremental search.
3095796c8dcSSimon Schubert@kbd{C-g} will abort an incremental search and restore the original line.
3105796c8dcSSimon SchubertWhen the search is terminated, the history entry containing the
3115796c8dcSSimon Schubertsearch string becomes the current line.
3125796c8dcSSimon Schubert
3135796c8dcSSimon SchubertTo find other matching entries in the history list, type @kbd{C-r} or
3145796c8dcSSimon Schubert@kbd{C-s} as appropriate.
3155796c8dcSSimon SchubertThis will search backward or forward in the history for the next
3165796c8dcSSimon Schubertentry matching the search string typed so far.
3175796c8dcSSimon SchubertAny other key sequence bound to a Readline command will terminate
3185796c8dcSSimon Schubertthe search and execute that command.
3195796c8dcSSimon SchubertFor instance, a @key{RET} will terminate the search and accept
3205796c8dcSSimon Schubertthe line, thereby executing the command from the history list.
3215796c8dcSSimon SchubertA movement command will terminate the search, make the last line found
3225796c8dcSSimon Schubertthe current line, and begin editing.
3235796c8dcSSimon Schubert
3245796c8dcSSimon SchubertReadline remembers the last incremental search string.  If two
3255796c8dcSSimon Schubert@kbd{C-r}s are typed without any intervening characters defining a new
3265796c8dcSSimon Schubertsearch string, any remembered search string is used.
3275796c8dcSSimon Schubert
3285796c8dcSSimon SchubertNon-incremental searches read the entire search string before starting
3295796c8dcSSimon Schubertto search for matching history lines.  The search string may be
3305796c8dcSSimon Schuberttyped by the user or be part of the contents of the current line.
3315796c8dcSSimon Schubert
3325796c8dcSSimon Schubert@node Readline Init File
3335796c8dcSSimon Schubert@section Readline Init File
3345796c8dcSSimon Schubert@cindex initialization file, readline
3355796c8dcSSimon Schubert
3365796c8dcSSimon SchubertAlthough the Readline library comes with a set of Emacs-like
3375796c8dcSSimon Schubertkeybindings installed by default, it is possible to use a different set
3385796c8dcSSimon Schubertof keybindings.
3395796c8dcSSimon SchubertAny user can customize programs that use Readline by putting
3405796c8dcSSimon Schubertcommands in an @dfn{inputrc} file, conventionally in his home directory.
3415796c8dcSSimon SchubertThe name of this
3425796c8dcSSimon Schubert@ifset BashFeatures
3435796c8dcSSimon Schubertfile is taken from the value of the shell variable @env{INPUTRC}.  If
3445796c8dcSSimon Schubert@end ifset
3455796c8dcSSimon Schubert@ifclear BashFeatures
3465796c8dcSSimon Schubertfile is taken from the value of the environment variable @env{INPUTRC}.  If
3475796c8dcSSimon Schubert@end ifclear
348*a45ae5f8SJohn Marinothat variable is unset, the default is @file{~/.inputrc}.  If that
349*a45ae5f8SJohn Marinofile does not exist or cannot be read, the ultimate default is
350*a45ae5f8SJohn Marino@file{/etc/inputrc}.
3515796c8dcSSimon Schubert
3525796c8dcSSimon SchubertWhen a program which uses the Readline library starts up, the
3535796c8dcSSimon Schubertinit file is read, and the key bindings are set.
3545796c8dcSSimon Schubert
3555796c8dcSSimon SchubertIn addition, the @code{C-x C-r} command re-reads this init file, thus
3565796c8dcSSimon Schubertincorporating any changes that you might have made to it.
3575796c8dcSSimon Schubert
3585796c8dcSSimon Schubert@menu
3595796c8dcSSimon Schubert* Readline Init File Syntax::	Syntax for the commands in the inputrc file.
3605796c8dcSSimon Schubert
3615796c8dcSSimon Schubert* Conditional Init Constructs::	Conditional key bindings in the inputrc file.
3625796c8dcSSimon Schubert
3635796c8dcSSimon Schubert* Sample Init File::		An example inputrc file.
3645796c8dcSSimon Schubert@end menu
3655796c8dcSSimon Schubert
3665796c8dcSSimon Schubert@node Readline Init File Syntax
3675796c8dcSSimon Schubert@subsection Readline Init File Syntax
3685796c8dcSSimon Schubert
3695796c8dcSSimon SchubertThere are only a few basic constructs allowed in the
3705796c8dcSSimon SchubertReadline init file.  Blank lines are ignored.
3715796c8dcSSimon SchubertLines beginning with a @samp{#} are comments.
3725796c8dcSSimon SchubertLines beginning with a @samp{$} indicate conditional
3735796c8dcSSimon Schubertconstructs (@pxref{Conditional Init Constructs}).  Other lines
3745796c8dcSSimon Schubertdenote variable settings and key bindings.
3755796c8dcSSimon Schubert
3765796c8dcSSimon Schubert@table @asis
3775796c8dcSSimon Schubert@item Variable Settings
3785796c8dcSSimon SchubertYou can modify the run-time behavior of Readline by
3795796c8dcSSimon Schubertaltering the values of variables in Readline
3805796c8dcSSimon Schubertusing the @code{set} command within the init file.
3815796c8dcSSimon SchubertThe syntax is simple:
3825796c8dcSSimon Schubert
3835796c8dcSSimon Schubert@example
3845796c8dcSSimon Schubertset @var{variable} @var{value}
3855796c8dcSSimon Schubert@end example
3865796c8dcSSimon Schubert
3875796c8dcSSimon Schubert@noindent
3885796c8dcSSimon SchubertHere, for example, is how to
3895796c8dcSSimon Schubertchange from the default Emacs-like key binding to use
3905796c8dcSSimon Schubert@code{vi} line editing commands:
3915796c8dcSSimon Schubert
3925796c8dcSSimon Schubert@example
3935796c8dcSSimon Schubertset editing-mode vi
3945796c8dcSSimon Schubert@end example
3955796c8dcSSimon Schubert
3965796c8dcSSimon SchubertVariable names and values, where appropriate, are recognized without regard
3975796c8dcSSimon Schubertto case.  Unrecognized variable names are ignored.
3985796c8dcSSimon Schubert
3995796c8dcSSimon SchubertBoolean variables (those that can be set to on or off) are set to on if
4005796c8dcSSimon Schubertthe value is null or empty, @var{on} (case-insensitive), or 1.  Any other
4015796c8dcSSimon Schubertvalue results in the variable being set to off.
4025796c8dcSSimon Schubert
4035796c8dcSSimon Schubert@ifset BashFeatures
4045796c8dcSSimon SchubertThe @w{@code{bind -V}} command lists the current Readline variable names
4055796c8dcSSimon Schubertand values.  @xref{Bash Builtins}.
4065796c8dcSSimon Schubert@end ifset
4075796c8dcSSimon Schubert
4085796c8dcSSimon SchubertA great deal of run-time behavior is changeable with the following
4095796c8dcSSimon Schubertvariables.
4105796c8dcSSimon Schubert
4115796c8dcSSimon Schubert@cindex variables, readline
4125796c8dcSSimon Schubert@table @code
4135796c8dcSSimon Schubert
4145796c8dcSSimon Schubert@item bell-style
4155796c8dcSSimon Schubert@vindex bell-style
4165796c8dcSSimon SchubertControls what happens when Readline wants to ring the terminal bell.
4175796c8dcSSimon SchubertIf set to @samp{none}, Readline never rings the bell.  If set to
4185796c8dcSSimon Schubert@samp{visible}, Readline uses a visible bell if one is available.
4195796c8dcSSimon SchubertIf set to @samp{audible} (the default), Readline attempts to ring
4205796c8dcSSimon Schubertthe terminal's bell.
4215796c8dcSSimon Schubert
4225796c8dcSSimon Schubert@item bind-tty-special-chars
4235796c8dcSSimon Schubert@vindex bind-tty-special-chars
4245796c8dcSSimon SchubertIf set to @samp{on}, Readline attempts to bind the control characters
4255796c8dcSSimon Schuberttreated specially by the kernel's terminal driver to their Readline
4265796c8dcSSimon Schubertequivalents.
4275796c8dcSSimon Schubert
4285796c8dcSSimon Schubert@item comment-begin
4295796c8dcSSimon Schubert@vindex comment-begin
4305796c8dcSSimon SchubertThe string to insert at the beginning of the line when the
4315796c8dcSSimon Schubert@code{insert-comment} command is executed.  The default value
4325796c8dcSSimon Schubertis @code{"#"}.
4335796c8dcSSimon Schubert
434*a45ae5f8SJohn Marino@item completion-display-width
435*a45ae5f8SJohn Marino@vindex completion-display-width
436*a45ae5f8SJohn MarinoThe number of screen columns used to display possible matches
437*a45ae5f8SJohn Marinowhen performing completion.
438*a45ae5f8SJohn MarinoThe value is ignored if it is less than 0 or greater than the terminal
439*a45ae5f8SJohn Marinoscreen width.
440*a45ae5f8SJohn MarinoA value of 0 will cause matches to be displayed one per line.
441*a45ae5f8SJohn MarinoThe default value is -1.
442*a45ae5f8SJohn Marino
4435796c8dcSSimon Schubert@item completion-ignore-case
444*a45ae5f8SJohn Marino@vindex completion-ignore-case
4455796c8dcSSimon SchubertIf set to @samp{on}, Readline performs filename matching and completion
4465796c8dcSSimon Schubertin a case-insensitive fashion.
4475796c8dcSSimon SchubertThe default value is @samp{off}.
4485796c8dcSSimon Schubert
449*a45ae5f8SJohn Marino@item completion-map-case
450*a45ae5f8SJohn Marino@vindex completion-map-case
451*a45ae5f8SJohn MarinoIf set to @samp{on}, and @var{completion-ignore-case} is enabled, Readline
452*a45ae5f8SJohn Marinotreats hyphens (@samp{-}) and underscores (@samp{_}) as equivalent when
453*a45ae5f8SJohn Marinoperforming case-insensitive filename matching and completion.
454*a45ae5f8SJohn Marino
455*a45ae5f8SJohn Marino@item completion-prefix-display-length
456*a45ae5f8SJohn Marino@vindex completion-prefix-display-length
457*a45ae5f8SJohn MarinoThe length in characters of the common prefix of a list of possible
458*a45ae5f8SJohn Marinocompletions that is displayed without modification.  When set to a
459*a45ae5f8SJohn Marinovalue greater than zero, common prefixes longer than this value are
460*a45ae5f8SJohn Marinoreplaced with an ellipsis when displaying possible completions.
461*a45ae5f8SJohn Marino
4625796c8dcSSimon Schubert@item completion-query-items
4635796c8dcSSimon Schubert@vindex completion-query-items
4645796c8dcSSimon SchubertThe number of possible completions that determines when the user is
4655796c8dcSSimon Schubertasked whether the list of possibilities should be displayed.
4665796c8dcSSimon SchubertIf the number of possible completions is greater than this value,
4675796c8dcSSimon SchubertReadline will ask the user whether or not he wishes to view
4685796c8dcSSimon Schubertthem; otherwise, they are simply listed.
4695796c8dcSSimon SchubertThis variable must be set to an integer value greater than or equal to 0.
4705796c8dcSSimon SchubertA negative value means Readline should never ask.
4715796c8dcSSimon SchubertThe default limit is @code{100}.
4725796c8dcSSimon Schubert
4735796c8dcSSimon Schubert@item convert-meta
4745796c8dcSSimon Schubert@vindex convert-meta
4755796c8dcSSimon SchubertIf set to @samp{on}, Readline will convert characters with the
4765796c8dcSSimon Schuberteighth bit set to an @sc{ascii} key sequence by stripping the eighth
4775796c8dcSSimon Schubertbit and prefixing an @key{ESC} character, converting them to a
4785796c8dcSSimon Schubertmeta-prefixed key sequence.  The default value is @samp{on}.
4795796c8dcSSimon Schubert
4805796c8dcSSimon Schubert@item disable-completion
4815796c8dcSSimon Schubert@vindex disable-completion
4825796c8dcSSimon SchubertIf set to @samp{On}, Readline will inhibit word completion.
4835796c8dcSSimon SchubertCompletion  characters will be inserted into the line as if they had
4845796c8dcSSimon Schubertbeen mapped to @code{self-insert}.  The default is @samp{off}.
4855796c8dcSSimon Schubert
4865796c8dcSSimon Schubert@item editing-mode
4875796c8dcSSimon Schubert@vindex editing-mode
4885796c8dcSSimon SchubertThe @code{editing-mode} variable controls which default set of
4895796c8dcSSimon Schubertkey bindings is used.  By default, Readline starts up in Emacs editing
4905796c8dcSSimon Schubertmode, where the keystrokes are most similar to Emacs.  This variable can be
4915796c8dcSSimon Schubertset to either @samp{emacs} or @samp{vi}.
4925796c8dcSSimon Schubert
493*a45ae5f8SJohn Marino@item echo-control-characters
494*a45ae5f8SJohn MarinoWhen set to @samp{on}, on operating systems that indicate they support it,
495*a45ae5f8SJohn Marinoreadline echoes a character corresponding to a signal generated from the
496*a45ae5f8SJohn Marinokeyboard.  The default is @samp{on}.
497*a45ae5f8SJohn Marino
4985796c8dcSSimon Schubert@item enable-keypad
4995796c8dcSSimon Schubert@vindex enable-keypad
5005796c8dcSSimon SchubertWhen set to @samp{on}, Readline will try to enable the application
5015796c8dcSSimon Schubertkeypad when it is called.  Some systems need this to enable the
5025796c8dcSSimon Schubertarrow keys.  The default is @samp{off}.
5035796c8dcSSimon Schubert
504*a45ae5f8SJohn Marino@item enable-meta-key
505*a45ae5f8SJohn MarinoWhen set to @samp{on}, Readline will try to enable any meta modifier
506*a45ae5f8SJohn Marinokey the terminal claims to support when it is called.  On many terminals,
507*a45ae5f8SJohn Marinothe meta key is used to send eight-bit characters.
508*a45ae5f8SJohn MarinoThe default is @samp{on}.
509*a45ae5f8SJohn Marino
5105796c8dcSSimon Schubert@item expand-tilde
5115796c8dcSSimon Schubert@vindex expand-tilde
5125796c8dcSSimon SchubertIf set to @samp{on}, tilde expansion is performed when Readline
5135796c8dcSSimon Schubertattempts word completion.  The default is @samp{off}.
5145796c8dcSSimon Schubert
5155796c8dcSSimon Schubert@item history-preserve-point
5165796c8dcSSimon Schubert@vindex history-preserve-point
517*a45ae5f8SJohn MarinoIf set to @samp{on}, the history code attempts to place the point (the
518*a45ae5f8SJohn Marinocurrent cursor position) at the
5195796c8dcSSimon Schubertsame location on each history line retrieved with @code{previous-history}
5205796c8dcSSimon Schubertor @code{next-history}.  The default is @samp{off}.
5215796c8dcSSimon Schubert
522*a45ae5f8SJohn Marino@item history-size
523*a45ae5f8SJohn Marino@vindex history-size
524*a45ae5f8SJohn MarinoSet the maximum number of history entries saved in the history list.  If
525*a45ae5f8SJohn Marinoset to zero, the number of entries in the history list is not limited.
526*a45ae5f8SJohn Marino
5275796c8dcSSimon Schubert@item horizontal-scroll-mode
5285796c8dcSSimon Schubert@vindex horizontal-scroll-mode
5295796c8dcSSimon SchubertThis variable can be set to either @samp{on} or @samp{off}.  Setting it
5305796c8dcSSimon Schubertto @samp{on} means that the text of the lines being edited will scroll
5315796c8dcSSimon Schuberthorizontally on a single screen line when they are longer than the width
5325796c8dcSSimon Schubertof the screen, instead of wrapping onto a new screen line.  By default,
5335796c8dcSSimon Schubertthis variable is set to @samp{off}.
5345796c8dcSSimon Schubert
5355796c8dcSSimon Schubert@item input-meta
5365796c8dcSSimon Schubert@vindex input-meta
5375796c8dcSSimon Schubert@vindex meta-flag
5385796c8dcSSimon SchubertIf set to @samp{on}, Readline will enable eight-bit input (it
5395796c8dcSSimon Schubertwill not clear the eighth bit in the characters it reads),
5405796c8dcSSimon Schubertregardless of what the terminal claims it can support.  The
5415796c8dcSSimon Schubertdefault value is @samp{off}.  The name @code{meta-flag} is a
5425796c8dcSSimon Schubertsynonym for this variable.
5435796c8dcSSimon Schubert
5445796c8dcSSimon Schubert@item isearch-terminators
5455796c8dcSSimon Schubert@vindex isearch-terminators
5465796c8dcSSimon SchubertThe string of characters that should terminate an incremental search without
5475796c8dcSSimon Schubertsubsequently executing the character as a command (@pxref{Searching}).
5485796c8dcSSimon SchubertIf this variable has not been given a value, the characters @key{ESC} and
5495796c8dcSSimon Schubert@kbd{C-J} will terminate an incremental search.
5505796c8dcSSimon Schubert
5515796c8dcSSimon Schubert@item keymap
5525796c8dcSSimon Schubert@vindex keymap
5535796c8dcSSimon SchubertSets Readline's idea of the current keymap for key binding commands.
5545796c8dcSSimon SchubertAcceptable @code{keymap} names are
5555796c8dcSSimon Schubert@code{emacs},
5565796c8dcSSimon Schubert@code{emacs-standard},
5575796c8dcSSimon Schubert@code{emacs-meta},
5585796c8dcSSimon Schubert@code{emacs-ctlx},
5595796c8dcSSimon Schubert@code{vi},
5605796c8dcSSimon Schubert@code{vi-move},
5615796c8dcSSimon Schubert@code{vi-command}, and
5625796c8dcSSimon Schubert@code{vi-insert}.
5635796c8dcSSimon Schubert@code{vi} is equivalent to @code{vi-command}; @code{emacs} is
5645796c8dcSSimon Schubertequivalent to @code{emacs-standard}.  The default value is @code{emacs}.
5655796c8dcSSimon SchubertThe value of the @code{editing-mode} variable also affects the
5665796c8dcSSimon Schubertdefault keymap.
5675796c8dcSSimon Schubert
5685796c8dcSSimon Schubert@item mark-directories
5695796c8dcSSimon SchubertIf set to @samp{on}, completed directory names have a slash
5705796c8dcSSimon Schubertappended.  The default is @samp{on}.
5715796c8dcSSimon Schubert
5725796c8dcSSimon Schubert@item mark-modified-lines
5735796c8dcSSimon Schubert@vindex mark-modified-lines
5745796c8dcSSimon SchubertThis variable, when set to @samp{on}, causes Readline to display an
5755796c8dcSSimon Schubertasterisk (@samp{*}) at the start of history lines which have been modified.
5765796c8dcSSimon SchubertThis variable is @samp{off} by default.
5775796c8dcSSimon Schubert
5785796c8dcSSimon Schubert@item mark-symlinked-directories
5795796c8dcSSimon Schubert@vindex mark-symlinked-directories
5805796c8dcSSimon SchubertIf set to @samp{on}, completed names which are symbolic links
5815796c8dcSSimon Schubertto directories have a slash appended (subject to the value of
5825796c8dcSSimon Schubert@code{mark-directories}).
5835796c8dcSSimon SchubertThe default is @samp{off}.
5845796c8dcSSimon Schubert
5855796c8dcSSimon Schubert@item match-hidden-files
5865796c8dcSSimon Schubert@vindex match-hidden-files
5875796c8dcSSimon SchubertThis variable, when set to @samp{on}, causes Readline to match files whose
5885796c8dcSSimon Schubertnames begin with a @samp{.} (hidden files) when performing filename
589*a45ae5f8SJohn Marinocompletion.
590*a45ae5f8SJohn MarinoIf set to @samp{off}, the leading @samp{.} must be
5915796c8dcSSimon Schubertsupplied by the user in the filename to be completed.
5925796c8dcSSimon SchubertThis variable is @samp{on} by default.
5935796c8dcSSimon Schubert
594*a45ae5f8SJohn Marino@item menu-complete-display-prefix
595*a45ae5f8SJohn Marino@vindex menu-complete-display-prefix
596*a45ae5f8SJohn MarinoIf set to @samp{on}, menu completion displays the common prefix of the
597*a45ae5f8SJohn Marinolist of possible completions (which may be empty) before cycling through
598*a45ae5f8SJohn Marinothe list.  The default is @samp{off}.
599*a45ae5f8SJohn Marino
6005796c8dcSSimon Schubert@item output-meta
6015796c8dcSSimon Schubert@vindex output-meta
6025796c8dcSSimon SchubertIf set to @samp{on}, Readline will display characters with the
6035796c8dcSSimon Schuberteighth bit set directly rather than as a meta-prefixed escape
6045796c8dcSSimon Schubertsequence.  The default is @samp{off}.
6055796c8dcSSimon Schubert
6065796c8dcSSimon Schubert@item page-completions
6075796c8dcSSimon Schubert@vindex page-completions
6085796c8dcSSimon SchubertIf set to @samp{on}, Readline uses an internal @code{more}-like pager
6095796c8dcSSimon Schubertto display a screenful of possible completions at a time.
6105796c8dcSSimon SchubertThis variable is @samp{on} by default.
6115796c8dcSSimon Schubert
6125796c8dcSSimon Schubert@item print-completions-horizontally
6135796c8dcSSimon SchubertIf set to @samp{on}, Readline will display completions with matches
6145796c8dcSSimon Schubertsorted horizontally in alphabetical order, rather than down the screen.
6155796c8dcSSimon SchubertThe default is @samp{off}.
6165796c8dcSSimon Schubert
617*a45ae5f8SJohn Marino@item revert-all-at-newline
618*a45ae5f8SJohn Marino@vindex revert-all-at-newline
619*a45ae5f8SJohn MarinoIf set to @samp{on}, Readline will undo all changes to history lines
620*a45ae5f8SJohn Marinobefore returning when @code{accept-line} is executed.  By default,
621*a45ae5f8SJohn Marinohistory lines may be modified and retain individual undo lists across
622*a45ae5f8SJohn Marinocalls to @code{readline}.  The default is @samp{off}.
623*a45ae5f8SJohn Marino
6245796c8dcSSimon Schubert@item show-all-if-ambiguous
6255796c8dcSSimon Schubert@vindex show-all-if-ambiguous
6265796c8dcSSimon SchubertThis alters the default behavior of the completion functions.  If
6275796c8dcSSimon Schubertset to @samp{on},
6285796c8dcSSimon Schubertwords which have more than one possible completion cause the
6295796c8dcSSimon Schubertmatches to be listed immediately instead of ringing the bell.
6305796c8dcSSimon SchubertThe default value is @samp{off}.
6315796c8dcSSimon Schubert
6325796c8dcSSimon Schubert@item show-all-if-unmodified
6335796c8dcSSimon Schubert@vindex show-all-if-unmodified
6345796c8dcSSimon SchubertThis alters the default behavior of the completion functions in
6355796c8dcSSimon Schuberta fashion similar to @var{show-all-if-ambiguous}.
6365796c8dcSSimon SchubertIf set to @samp{on},
6375796c8dcSSimon Schubertwords which have more than one possible completion without any
6385796c8dcSSimon Schubertpossible partial completion (the possible completions don't share
6395796c8dcSSimon Schuberta common prefix) cause the matches to be listed immediately instead
6405796c8dcSSimon Schubertof ringing the bell.
6415796c8dcSSimon SchubertThe default value is @samp{off}.
6425796c8dcSSimon Schubert
643*a45ae5f8SJohn Marino@item skip-completed-text
644*a45ae5f8SJohn Marino@vindex skip-completed-text
645*a45ae5f8SJohn MarinoIf set to @samp{on}, this alters the default completion behavior when
646*a45ae5f8SJohn Marinoinserting a single match into the line.  It's only active when
647*a45ae5f8SJohn Marinoperforming completion in the middle of a word.  If enabled, readline
648*a45ae5f8SJohn Marinodoes not insert characters from the completion that match characters
649*a45ae5f8SJohn Marinoafter point in the word being completed, so portions of the word
650*a45ae5f8SJohn Marinofollowing the cursor are not duplicated.
651*a45ae5f8SJohn MarinoFor instance, if this is enabled, attempting completion when the cursor
652*a45ae5f8SJohn Marinois after the @samp{e} in @samp{Makefile} will result in @samp{Makefile}
653*a45ae5f8SJohn Marinorather than @samp{Makefilefile}, assuming there is a single possible
654*a45ae5f8SJohn Marinocompletion.
655*a45ae5f8SJohn MarinoThe default value is @samp{off}.
656*a45ae5f8SJohn Marino
6575796c8dcSSimon Schubert@item visible-stats
6585796c8dcSSimon Schubert@vindex visible-stats
6595796c8dcSSimon SchubertIf set to @samp{on}, a character denoting a file's type
6605796c8dcSSimon Schubertis appended to the filename when listing possible
6615796c8dcSSimon Schubertcompletions.  The default is @samp{off}.
6625796c8dcSSimon Schubert
6635796c8dcSSimon Schubert@end table
6645796c8dcSSimon Schubert
6655796c8dcSSimon Schubert@item Key Bindings
6665796c8dcSSimon SchubertThe syntax for controlling key bindings in the init file is
6675796c8dcSSimon Schubertsimple.  First you need to find the name of the command that you
6685796c8dcSSimon Schubertwant to change.  The following sections contain tables of the command
6695796c8dcSSimon Schubertname, the default keybinding, if any, and a short description of what
6705796c8dcSSimon Schubertthe command does.
6715796c8dcSSimon Schubert
6725796c8dcSSimon SchubertOnce you know the name of the command, simply place on a line
6735796c8dcSSimon Schubertin the init file the name of the key
6745796c8dcSSimon Schubertyou wish to bind the command to, a colon, and then the name of the
675*a45ae5f8SJohn Marinocommand.
676*a45ae5f8SJohn MarinoThere can be no space between the key name and the colon -- that will be
677*a45ae5f8SJohn Marinointerpreted as part of the key name.
678*a45ae5f8SJohn MarinoThe name of the key can be expressed in different ways, depending on
679*a45ae5f8SJohn Marinowhat you find most comfortable.
6805796c8dcSSimon Schubert
6815796c8dcSSimon SchubertIn addition to command names, readline allows keys to be bound
6825796c8dcSSimon Schubertto a string that is inserted when the key is pressed (a @var{macro}).
6835796c8dcSSimon Schubert
6845796c8dcSSimon Schubert@ifset BashFeatures
6855796c8dcSSimon SchubertThe @w{@code{bind -p}} command displays Readline function names and
6865796c8dcSSimon Schubertbindings in a format that can put directly into an initialization file.
6875796c8dcSSimon Schubert@xref{Bash Builtins}.
6885796c8dcSSimon Schubert@end ifset
6895796c8dcSSimon Schubert
6905796c8dcSSimon Schubert@table @asis
6915796c8dcSSimon Schubert@item @w{@var{keyname}: @var{function-name} or @var{macro}}
6925796c8dcSSimon Schubert@var{keyname} is the name of a key spelled out in English.  For example:
6935796c8dcSSimon Schubert@example
6945796c8dcSSimon SchubertControl-u: universal-argument
6955796c8dcSSimon SchubertMeta-Rubout: backward-kill-word
6965796c8dcSSimon SchubertControl-o: "> output"
6975796c8dcSSimon Schubert@end example
6985796c8dcSSimon Schubert
6995796c8dcSSimon SchubertIn the above example, @kbd{C-u} is bound to the function
7005796c8dcSSimon Schubert@code{universal-argument},
7015796c8dcSSimon Schubert@kbd{M-DEL} is bound to the function @code{backward-kill-word}, and
7025796c8dcSSimon Schubert@kbd{C-o} is bound to run the macro
7035796c8dcSSimon Schubertexpressed on the right hand side (that is, to insert the text
7045796c8dcSSimon Schubert@samp{> output} into the line).
7055796c8dcSSimon Schubert
7065796c8dcSSimon SchubertA number of symbolic character names are recognized while
7075796c8dcSSimon Schubertprocessing this key binding syntax:
7085796c8dcSSimon Schubert@var{DEL},
7095796c8dcSSimon Schubert@var{ESC},
7105796c8dcSSimon Schubert@var{ESCAPE},
7115796c8dcSSimon Schubert@var{LFD},
7125796c8dcSSimon Schubert@var{NEWLINE},
7135796c8dcSSimon Schubert@var{RET},
7145796c8dcSSimon Schubert@var{RETURN},
7155796c8dcSSimon Schubert@var{RUBOUT},
7165796c8dcSSimon Schubert@var{SPACE},
7175796c8dcSSimon Schubert@var{SPC},
7185796c8dcSSimon Schubertand
7195796c8dcSSimon Schubert@var{TAB}.
7205796c8dcSSimon Schubert
7215796c8dcSSimon Schubert@item @w{"@var{keyseq}": @var{function-name} or @var{macro}}
7225796c8dcSSimon Schubert@var{keyseq} differs from @var{keyname} above in that strings
7235796c8dcSSimon Schubertdenoting an entire key sequence can be specified, by placing
7245796c8dcSSimon Schubertthe key sequence in double quotes.  Some @sc{gnu} Emacs style key
7255796c8dcSSimon Schubertescapes can be used, as in the following example, but the
7265796c8dcSSimon Schubertspecial character names are not recognized.
7275796c8dcSSimon Schubert
7285796c8dcSSimon Schubert@example
7295796c8dcSSimon Schubert"\C-u": universal-argument
7305796c8dcSSimon Schubert"\C-x\C-r": re-read-init-file
7315796c8dcSSimon Schubert"\e[11~": "Function Key 1"
7325796c8dcSSimon Schubert@end example
7335796c8dcSSimon Schubert
7345796c8dcSSimon SchubertIn the above example, @kbd{C-u} is again bound to the function
7355796c8dcSSimon Schubert@code{universal-argument} (just as it was in the first example),
7365796c8dcSSimon Schubert@samp{@kbd{C-x} @kbd{C-r}} is bound to the function @code{re-read-init-file},
7375796c8dcSSimon Schubertand @samp{@key{ESC} @key{[} @key{1} @key{1} @key{~}} is bound to insert
7385796c8dcSSimon Schubertthe text @samp{Function Key 1}.
7395796c8dcSSimon Schubert
7405796c8dcSSimon Schubert@end table
7415796c8dcSSimon Schubert
7425796c8dcSSimon SchubertThe following @sc{gnu} Emacs style escape sequences are available when
7435796c8dcSSimon Schubertspecifying key sequences:
7445796c8dcSSimon Schubert
7455796c8dcSSimon Schubert@table @code
7465796c8dcSSimon Schubert@item @kbd{\C-}
7475796c8dcSSimon Schubertcontrol prefix
7485796c8dcSSimon Schubert@item @kbd{\M-}
7495796c8dcSSimon Schubertmeta prefix
7505796c8dcSSimon Schubert@item @kbd{\e}
7515796c8dcSSimon Schubertan escape character
7525796c8dcSSimon Schubert@item @kbd{\\}
7535796c8dcSSimon Schubertbackslash
7545796c8dcSSimon Schubert@item @kbd{\"}
7555796c8dcSSimon Schubert@key{"}, a double quotation mark
7565796c8dcSSimon Schubert@item @kbd{\'}
7575796c8dcSSimon Schubert@key{'}, a single quote or apostrophe
7585796c8dcSSimon Schubert@end table
7595796c8dcSSimon Schubert
7605796c8dcSSimon SchubertIn addition to the @sc{gnu} Emacs style escape sequences, a second
7615796c8dcSSimon Schubertset of backslash escapes is available:
7625796c8dcSSimon Schubert
7635796c8dcSSimon Schubert@table @code
7645796c8dcSSimon Schubert@item \a
7655796c8dcSSimon Schubertalert (bell)
7665796c8dcSSimon Schubert@item \b
7675796c8dcSSimon Schubertbackspace
7685796c8dcSSimon Schubert@item \d
7695796c8dcSSimon Schubertdelete
7705796c8dcSSimon Schubert@item \f
7715796c8dcSSimon Schubertform feed
7725796c8dcSSimon Schubert@item \n
7735796c8dcSSimon Schubertnewline
7745796c8dcSSimon Schubert@item \r
7755796c8dcSSimon Schubertcarriage return
7765796c8dcSSimon Schubert@item \t
7775796c8dcSSimon Schuberthorizontal tab
7785796c8dcSSimon Schubert@item \v
7795796c8dcSSimon Schubertvertical tab
7805796c8dcSSimon Schubert@item \@var{nnn}
7815796c8dcSSimon Schubertthe eight-bit character whose value is the octal value @var{nnn}
7825796c8dcSSimon Schubert(one to three digits)
7835796c8dcSSimon Schubert@item \x@var{HH}
7845796c8dcSSimon Schubertthe eight-bit character whose value is the hexadecimal value @var{HH}
7855796c8dcSSimon Schubert(one or two hex digits)
7865796c8dcSSimon Schubert@end table
7875796c8dcSSimon Schubert
7885796c8dcSSimon SchubertWhen entering the text of a macro, single or double quotes must
7895796c8dcSSimon Schubertbe used to indicate a macro definition.
7905796c8dcSSimon SchubertUnquoted text is assumed to be a function name.
7915796c8dcSSimon SchubertIn the macro body, the backslash escapes described above are expanded.
7925796c8dcSSimon SchubertBackslash will quote any other character in the macro text,
7935796c8dcSSimon Schubertincluding @samp{"} and @samp{'}.
7945796c8dcSSimon SchubertFor example, the following binding will make @samp{@kbd{C-x} \}
7955796c8dcSSimon Schubertinsert a single @samp{\} into the line:
7965796c8dcSSimon Schubert@example
7975796c8dcSSimon Schubert"\C-x\\": "\\"
7985796c8dcSSimon Schubert@end example
7995796c8dcSSimon Schubert
8005796c8dcSSimon Schubert@end table
8015796c8dcSSimon Schubert
8025796c8dcSSimon Schubert@node Conditional Init Constructs
8035796c8dcSSimon Schubert@subsection Conditional Init Constructs
8045796c8dcSSimon Schubert
8055796c8dcSSimon SchubertReadline implements a facility similar in spirit to the conditional
8065796c8dcSSimon Schubertcompilation features of the C preprocessor which allows key
8075796c8dcSSimon Schubertbindings and variable settings to be performed as the result
8085796c8dcSSimon Schubertof tests.  There are four parser directives used.
8095796c8dcSSimon Schubert
8105796c8dcSSimon Schubert@table @code
8115796c8dcSSimon Schubert@item $if
8125796c8dcSSimon SchubertThe @code{$if} construct allows bindings to be made based on the
8135796c8dcSSimon Schubertediting mode, the terminal being used, or the application using
8145796c8dcSSimon SchubertReadline.  The text of the test extends to the end of the line;
8155796c8dcSSimon Schubertno characters are required to isolate it.
8165796c8dcSSimon Schubert
8175796c8dcSSimon Schubert@table @code
8185796c8dcSSimon Schubert@item mode
8195796c8dcSSimon SchubertThe @code{mode=} form of the @code{$if} directive is used to test
8205796c8dcSSimon Schubertwhether Readline is in @code{emacs} or @code{vi} mode.
8215796c8dcSSimon SchubertThis may be used in conjunction
8225796c8dcSSimon Schubertwith the @samp{set keymap} command, for instance, to set bindings in
8235796c8dcSSimon Schubertthe @code{emacs-standard} and @code{emacs-ctlx} keymaps only if
8245796c8dcSSimon SchubertReadline is starting out in @code{emacs} mode.
8255796c8dcSSimon Schubert
8265796c8dcSSimon Schubert@item term
8275796c8dcSSimon SchubertThe @code{term=} form may be used to include terminal-specific
8285796c8dcSSimon Schubertkey bindings, perhaps to bind the key sequences output by the
8295796c8dcSSimon Schubertterminal's function keys.  The word on the right side of the
8305796c8dcSSimon Schubert@samp{=} is tested against both the full name of the terminal and
8315796c8dcSSimon Schubertthe portion of the terminal name before the first @samp{-}.  This
8325796c8dcSSimon Schubertallows @code{sun} to match both @code{sun} and @code{sun-cmd},
8335796c8dcSSimon Schubertfor instance.
8345796c8dcSSimon Schubert
8355796c8dcSSimon Schubert@item application
8365796c8dcSSimon SchubertThe @var{application} construct is used to include
8375796c8dcSSimon Schubertapplication-specific settings.  Each program using the Readline
8385796c8dcSSimon Schubertlibrary sets the @var{application name}, and you can test for
8395796c8dcSSimon Schuberta particular value.
8405796c8dcSSimon SchubertThis could be used to bind key sequences to functions useful for
8415796c8dcSSimon Schuberta specific program.  For instance, the following command adds a
8425796c8dcSSimon Schubertkey sequence that quotes the current or previous word in Bash:
8435796c8dcSSimon Schubert@example
8445796c8dcSSimon Schubert$if Bash
8455796c8dcSSimon Schubert# Quote the current or previous word
8465796c8dcSSimon Schubert"\C-xq": "\eb\"\ef\""
8475796c8dcSSimon Schubert$endif
8485796c8dcSSimon Schubert@end example
8495796c8dcSSimon Schubert@end table
8505796c8dcSSimon Schubert
8515796c8dcSSimon Schubert@item $endif
8525796c8dcSSimon SchubertThis command, as seen in the previous example, terminates an
8535796c8dcSSimon Schubert@code{$if} command.
8545796c8dcSSimon Schubert
8555796c8dcSSimon Schubert@item $else
8565796c8dcSSimon SchubertCommands in this branch of the @code{$if} directive are executed if
8575796c8dcSSimon Schubertthe test fails.
8585796c8dcSSimon Schubert
8595796c8dcSSimon Schubert@item $include
8605796c8dcSSimon SchubertThis directive takes a single filename as an argument and reads commands
8615796c8dcSSimon Schubertand bindings from that file.
8625796c8dcSSimon SchubertFor example, the following directive reads from @file{/etc/inputrc}:
8635796c8dcSSimon Schubert@example
8645796c8dcSSimon Schubert$include /etc/inputrc
8655796c8dcSSimon Schubert@end example
8665796c8dcSSimon Schubert@end table
8675796c8dcSSimon Schubert
8685796c8dcSSimon Schubert@node Sample Init File
8695796c8dcSSimon Schubert@subsection Sample Init File
8705796c8dcSSimon Schubert
8715796c8dcSSimon SchubertHere is an example of an @var{inputrc} file.  This illustrates key
8725796c8dcSSimon Schubertbinding, variable assignment, and conditional syntax.
8735796c8dcSSimon Schubert
8745796c8dcSSimon Schubert@example
8755796c8dcSSimon Schubert@page
8765796c8dcSSimon Schubert# This file controls the behaviour of line input editing for
8775796c8dcSSimon Schubert# programs that use the GNU Readline library.  Existing
8785796c8dcSSimon Schubert# programs include FTP, Bash, and GDB.
8795796c8dcSSimon Schubert#
8805796c8dcSSimon Schubert# You can re-read the inputrc file with C-x C-r.
8815796c8dcSSimon Schubert# Lines beginning with '#' are comments.
8825796c8dcSSimon Schubert#
8835796c8dcSSimon Schubert# First, include any systemwide bindings and variable
8845796c8dcSSimon Schubert# assignments from /etc/Inputrc
8855796c8dcSSimon Schubert$include /etc/Inputrc
8865796c8dcSSimon Schubert
8875796c8dcSSimon Schubert#
8885796c8dcSSimon Schubert# Set various bindings for emacs mode.
8895796c8dcSSimon Schubert
8905796c8dcSSimon Schubertset editing-mode emacs
8915796c8dcSSimon Schubert
8925796c8dcSSimon Schubert$if mode=emacs
8935796c8dcSSimon Schubert
8945796c8dcSSimon SchubertMeta-Control-h:	backward-kill-word	Text after the function name is ignored
8955796c8dcSSimon Schubert
8965796c8dcSSimon Schubert#
8975796c8dcSSimon Schubert# Arrow keys in keypad mode
8985796c8dcSSimon Schubert#
8995796c8dcSSimon Schubert#"\M-OD":        backward-char
9005796c8dcSSimon Schubert#"\M-OC":        forward-char
9015796c8dcSSimon Schubert#"\M-OA":        previous-history
9025796c8dcSSimon Schubert#"\M-OB":        next-history
9035796c8dcSSimon Schubert#
9045796c8dcSSimon Schubert# Arrow keys in ANSI mode
9055796c8dcSSimon Schubert#
9065796c8dcSSimon Schubert"\M-[D":        backward-char
9075796c8dcSSimon Schubert"\M-[C":        forward-char
9085796c8dcSSimon Schubert"\M-[A":        previous-history
9095796c8dcSSimon Schubert"\M-[B":        next-history
9105796c8dcSSimon Schubert#
9115796c8dcSSimon Schubert# Arrow keys in 8 bit keypad mode
9125796c8dcSSimon Schubert#
9135796c8dcSSimon Schubert#"\M-\C-OD":       backward-char
9145796c8dcSSimon Schubert#"\M-\C-OC":       forward-char
9155796c8dcSSimon Schubert#"\M-\C-OA":       previous-history
9165796c8dcSSimon Schubert#"\M-\C-OB":       next-history
9175796c8dcSSimon Schubert#
9185796c8dcSSimon Schubert# Arrow keys in 8 bit ANSI mode
9195796c8dcSSimon Schubert#
9205796c8dcSSimon Schubert#"\M-\C-[D":       backward-char
9215796c8dcSSimon Schubert#"\M-\C-[C":       forward-char
9225796c8dcSSimon Schubert#"\M-\C-[A":       previous-history
9235796c8dcSSimon Schubert#"\M-\C-[B":       next-history
9245796c8dcSSimon Schubert
9255796c8dcSSimon SchubertC-q: quoted-insert
9265796c8dcSSimon Schubert
9275796c8dcSSimon Schubert$endif
9285796c8dcSSimon Schubert
9295796c8dcSSimon Schubert# An old-style binding.  This happens to be the default.
9305796c8dcSSimon SchubertTAB: complete
9315796c8dcSSimon Schubert
9325796c8dcSSimon Schubert# Macros that are convenient for shell interaction
9335796c8dcSSimon Schubert$if Bash
9345796c8dcSSimon Schubert# edit the path
9355796c8dcSSimon Schubert"\C-xp": "PATH=$@{PATH@}\e\C-e\C-a\ef\C-f"
9365796c8dcSSimon Schubert# prepare to type a quoted word --
9375796c8dcSSimon Schubert# insert open and close double quotes
9385796c8dcSSimon Schubert# and move to just after the open quote
9395796c8dcSSimon Schubert"\C-x\"": "\"\"\C-b"
9405796c8dcSSimon Schubert# insert a backslash (testing backslash escapes
9415796c8dcSSimon Schubert# in sequences and macros)
9425796c8dcSSimon Schubert"\C-x\\": "\\"
9435796c8dcSSimon Schubert# Quote the current or previous word
9445796c8dcSSimon Schubert"\C-xq": "\eb\"\ef\""
9455796c8dcSSimon Schubert# Add a binding to refresh the line, which is unbound
9465796c8dcSSimon Schubert"\C-xr": redraw-current-line
9475796c8dcSSimon Schubert# Edit variable on current line.
9485796c8dcSSimon Schubert"\M-\C-v": "\C-a\C-k$\C-y\M-\C-e\C-a\C-y="
9495796c8dcSSimon Schubert$endif
9505796c8dcSSimon Schubert
9515796c8dcSSimon Schubert# use a visible bell if one is available
9525796c8dcSSimon Schubertset bell-style visible
9535796c8dcSSimon Schubert
9545796c8dcSSimon Schubert# don't strip characters to 7 bits when reading
9555796c8dcSSimon Schubertset input-meta on
9565796c8dcSSimon Schubert
9575796c8dcSSimon Schubert# allow iso-latin1 characters to be inserted rather
9585796c8dcSSimon Schubert# than converted to prefix-meta sequences
9595796c8dcSSimon Schubertset convert-meta off
9605796c8dcSSimon Schubert
9615796c8dcSSimon Schubert# display characters with the eighth bit set directly
9625796c8dcSSimon Schubert# rather than as meta-prefixed characters
9635796c8dcSSimon Schubertset output-meta on
9645796c8dcSSimon Schubert
9655796c8dcSSimon Schubert# if there are more than 150 possible completions for
9665796c8dcSSimon Schubert# a word, ask the user if he wants to see all of them
9675796c8dcSSimon Schubertset completion-query-items 150
9685796c8dcSSimon Schubert
9695796c8dcSSimon Schubert# For FTP
9705796c8dcSSimon Schubert$if Ftp
9715796c8dcSSimon Schubert"\C-xg": "get \M-?"
9725796c8dcSSimon Schubert"\C-xt": "put \M-?"
9735796c8dcSSimon Schubert"\M-.": yank-last-arg
9745796c8dcSSimon Schubert$endif
9755796c8dcSSimon Schubert@end example
9765796c8dcSSimon Schubert
9775796c8dcSSimon Schubert@node Bindable Readline Commands
9785796c8dcSSimon Schubert@section Bindable Readline Commands
9795796c8dcSSimon Schubert
9805796c8dcSSimon Schubert@menu
9815796c8dcSSimon Schubert* Commands For Moving::		Moving about the line.
9825796c8dcSSimon Schubert* Commands For History::	Getting at previous lines.
9835796c8dcSSimon Schubert* Commands For Text::		Commands for changing text.
9845796c8dcSSimon Schubert* Commands For Killing::	Commands for killing and yanking.
9855796c8dcSSimon Schubert* Numeric Arguments::		Specifying numeric arguments, repeat counts.
9865796c8dcSSimon Schubert* Commands For Completion::	Getting Readline to do the typing for you.
9875796c8dcSSimon Schubert* Keyboard Macros::		Saving and re-executing typed characters
9885796c8dcSSimon Schubert* Miscellaneous Commands::	Other miscellaneous commands.
9895796c8dcSSimon Schubert@end menu
9905796c8dcSSimon Schubert
9915796c8dcSSimon SchubertThis section describes Readline commands that may be bound to key
9925796c8dcSSimon Schubertsequences.
9935796c8dcSSimon Schubert@ifset BashFeatures
9945796c8dcSSimon SchubertYou can list your key bindings by executing
9955796c8dcSSimon Schubert@w{@code{bind -P}} or, for a more terse format, suitable for an
9965796c8dcSSimon Schubert@var{inputrc} file, @w{@code{bind -p}}.  (@xref{Bash Builtins}.)
9975796c8dcSSimon Schubert@end ifset
9985796c8dcSSimon SchubertCommand names without an accompanying key sequence are unbound by default.
9995796c8dcSSimon Schubert
10005796c8dcSSimon SchubertIn the following descriptions, @dfn{point} refers to the current cursor
10015796c8dcSSimon Schubertposition, and @dfn{mark} refers to a cursor position saved by the
10025796c8dcSSimon Schubert@code{set-mark} command.
10035796c8dcSSimon SchubertThe text between the point and mark is referred to as the @dfn{region}.
10045796c8dcSSimon Schubert
10055796c8dcSSimon Schubert@node Commands For Moving
10065796c8dcSSimon Schubert@subsection Commands For Moving
10075796c8dcSSimon Schubert@ftable @code
10085796c8dcSSimon Schubert@item beginning-of-line (C-a)
10095796c8dcSSimon SchubertMove to the start of the current line.
10105796c8dcSSimon Schubert
10115796c8dcSSimon Schubert@item end-of-line (C-e)
10125796c8dcSSimon SchubertMove to the end of the line.
10135796c8dcSSimon Schubert
10145796c8dcSSimon Schubert@item forward-char (C-f)
10155796c8dcSSimon SchubertMove forward a character.
10165796c8dcSSimon Schubert
10175796c8dcSSimon Schubert@item backward-char (C-b)
10185796c8dcSSimon SchubertMove back a character.
10195796c8dcSSimon Schubert
10205796c8dcSSimon Schubert@item forward-word (M-f)
1021*a45ae5f8SJohn MarinoMove forward to the end of the next word.
1022*a45ae5f8SJohn MarinoWords are composed of letters and digits.
10235796c8dcSSimon Schubert
10245796c8dcSSimon Schubert@item backward-word (M-b)
1025*a45ae5f8SJohn MarinoMove back to the start of the current or previous word.
1026*a45ae5f8SJohn MarinoWords are composed of letters and digits.
1027*a45ae5f8SJohn Marino
1028*a45ae5f8SJohn Marino@ifset BashFeatures
1029*a45ae5f8SJohn Marino@item shell-forward-word ()
1030*a45ae5f8SJohn MarinoMove forward to the end of the next word.
1031*a45ae5f8SJohn MarinoWords are delimited by non-quoted shell metacharacters.
1032*a45ae5f8SJohn Marino
1033*a45ae5f8SJohn Marino@item shell-backward-word ()
1034*a45ae5f8SJohn MarinoMove back to the start of the current or previous word.
1035*a45ae5f8SJohn MarinoWords are delimited by non-quoted shell metacharacters.
1036*a45ae5f8SJohn Marino@end ifset
10375796c8dcSSimon Schubert
10385796c8dcSSimon Schubert@item clear-screen (C-l)
10395796c8dcSSimon SchubertClear the screen and redraw the current line,
10405796c8dcSSimon Schubertleaving the current line at the top of the screen.
10415796c8dcSSimon Schubert
10425796c8dcSSimon Schubert@item redraw-current-line ()
10435796c8dcSSimon SchubertRefresh the current line.  By default, this is unbound.
10445796c8dcSSimon Schubert
10455796c8dcSSimon Schubert@end ftable
10465796c8dcSSimon Schubert
10475796c8dcSSimon Schubert@node Commands For History
10485796c8dcSSimon Schubert@subsection Commands For Manipulating The History
10495796c8dcSSimon Schubert
10505796c8dcSSimon Schubert@ftable @code
10515796c8dcSSimon Schubert@item accept-line (Newline or Return)
10525796c8dcSSimon Schubert@ifset BashFeatures
10535796c8dcSSimon SchubertAccept the line regardless of where the cursor is.
10545796c8dcSSimon SchubertIf this line is
10555796c8dcSSimon Schubertnon-empty, add it to the history list according to the setting of
10565796c8dcSSimon Schubertthe @env{HISTCONTROL} and @env{HISTIGNORE} variables.
10575796c8dcSSimon SchubertIf this line is a modified history line, then restore the history line
10585796c8dcSSimon Schubertto its original state.
10595796c8dcSSimon Schubert@end ifset
10605796c8dcSSimon Schubert@ifclear BashFeatures
10615796c8dcSSimon SchubertAccept the line regardless of where the cursor is.
10625796c8dcSSimon SchubertIf this line is
10635796c8dcSSimon Schubertnon-empty, it may be added to the history list for future recall with
10645796c8dcSSimon Schubert@code{add_history()}.
10655796c8dcSSimon SchubertIf this line is a modified history line, the history line is restored
10665796c8dcSSimon Schubertto its original state.
10675796c8dcSSimon Schubert@end ifclear
10685796c8dcSSimon Schubert
10695796c8dcSSimon Schubert@item previous-history (C-p)
10705796c8dcSSimon SchubertMove `back' through the history list, fetching the previous command.
10715796c8dcSSimon Schubert
10725796c8dcSSimon Schubert@item next-history (C-n)
10735796c8dcSSimon SchubertMove `forward' through the history list, fetching the next command.
10745796c8dcSSimon Schubert
10755796c8dcSSimon Schubert@item beginning-of-history (M-<)
10765796c8dcSSimon SchubertMove to the first line in the history.
10775796c8dcSSimon Schubert
10785796c8dcSSimon Schubert@item end-of-history (M->)
10795796c8dcSSimon SchubertMove to the end of the input history, i.e., the line currently
10805796c8dcSSimon Schubertbeing entered.
10815796c8dcSSimon Schubert
10825796c8dcSSimon Schubert@item reverse-search-history (C-r)
10835796c8dcSSimon SchubertSearch backward starting at the current line and moving `up' through
10845796c8dcSSimon Schubertthe history as necessary.  This is an incremental search.
10855796c8dcSSimon Schubert
10865796c8dcSSimon Schubert@item forward-search-history (C-s)
10875796c8dcSSimon SchubertSearch forward starting at the current line and moving `down' through
10885796c8dcSSimon Schubertthe the history as necessary.  This is an incremental search.
10895796c8dcSSimon Schubert
10905796c8dcSSimon Schubert@item non-incremental-reverse-search-history (M-p)
10915796c8dcSSimon SchubertSearch backward starting at the current line and moving `up'
10925796c8dcSSimon Schubertthrough the history as necessary using a non-incremental search
10935796c8dcSSimon Schubertfor a string supplied by the user.
10945796c8dcSSimon Schubert
10955796c8dcSSimon Schubert@item non-incremental-forward-search-history (M-n)
10965796c8dcSSimon SchubertSearch forward starting at the current line and moving `down'
10975796c8dcSSimon Schubertthrough the the history as necessary using a non-incremental search
10985796c8dcSSimon Schubertfor a string supplied by the user.
10995796c8dcSSimon Schubert
11005796c8dcSSimon Schubert@item history-search-forward ()
11015796c8dcSSimon SchubertSearch forward through the history for the string of characters
11025796c8dcSSimon Schubertbetween the start of the current line and the point.
11035796c8dcSSimon SchubertThis is a non-incremental search.
11045796c8dcSSimon SchubertBy default, this command is unbound.
11055796c8dcSSimon Schubert
11065796c8dcSSimon Schubert@item history-search-backward ()
11075796c8dcSSimon SchubertSearch backward through the history for the string of characters
11085796c8dcSSimon Schubertbetween the start of the current line and the point.  This
11095796c8dcSSimon Schubertis a non-incremental search.  By default, this command is unbound.
11105796c8dcSSimon Schubert
11115796c8dcSSimon Schubert@item yank-nth-arg (M-C-y)
11125796c8dcSSimon SchubertInsert the first argument to the previous command (usually
11135796c8dcSSimon Schubertthe second word on the previous line) at point.
11145796c8dcSSimon SchubertWith an argument @var{n},
11155796c8dcSSimon Schubertinsert the @var{n}th word from the previous command (the words
11165796c8dcSSimon Schubertin the previous command begin with word 0).  A negative argument
11175796c8dcSSimon Schubertinserts the @var{n}th word from the end of the previous command.
11185796c8dcSSimon SchubertOnce the argument @var{n} is computed, the argument is extracted
11195796c8dcSSimon Schubertas if the @samp{!@var{n}} history expansion had been specified.
11205796c8dcSSimon Schubert
11215796c8dcSSimon Schubert@item yank-last-arg (M-. or M-_)
11225796c8dcSSimon SchubertInsert last argument to the previous command (the last word of the
1123*a45ae5f8SJohn Marinoprevious history entry).
1124*a45ae5f8SJohn MarinoWith a numeric argument, behave exactly like @code{yank-nth-arg}.
11255796c8dcSSimon SchubertSuccessive calls to @code{yank-last-arg} move back through the history
1126*a45ae5f8SJohn Marinolist, inserting the last word (or the word specified by the argument to
1127*a45ae5f8SJohn Marinothe first call) of each line in turn.
1128*a45ae5f8SJohn MarinoAny numeric argument supplied to these successive calls determines
1129*a45ae5f8SJohn Marinothe direction to move through the history.  A negative argument switches
1130*a45ae5f8SJohn Marinothe direction through the history (back or forward).
11315796c8dcSSimon SchubertThe history expansion facilities are used to extract the last argument,
11325796c8dcSSimon Schubertas if the @samp{!$} history expansion had been specified.
11335796c8dcSSimon Schubert
11345796c8dcSSimon Schubert@end ftable
11355796c8dcSSimon Schubert
11365796c8dcSSimon Schubert@node Commands For Text
11375796c8dcSSimon Schubert@subsection Commands For Changing Text
11385796c8dcSSimon Schubert
11395796c8dcSSimon Schubert@ftable @code
11405796c8dcSSimon Schubert@item delete-char (C-d)
11415796c8dcSSimon SchubertDelete the character at point.  If point is at the
11425796c8dcSSimon Schubertbeginning of the line, there are no characters in the line, and
11435796c8dcSSimon Schubertthe last character typed was not bound to @code{delete-char}, then
11445796c8dcSSimon Schubertreturn @sc{eof}.
11455796c8dcSSimon Schubert
11465796c8dcSSimon Schubert@item backward-delete-char (Rubout)
11475796c8dcSSimon SchubertDelete the character behind the cursor.  A numeric argument means
11485796c8dcSSimon Schubertto kill the characters instead of deleting them.
11495796c8dcSSimon Schubert
11505796c8dcSSimon Schubert@item forward-backward-delete-char ()
11515796c8dcSSimon SchubertDelete the character under the cursor, unless the cursor is at the
11525796c8dcSSimon Schubertend of the line, in which case the character behind the cursor is
11535796c8dcSSimon Schubertdeleted.  By default, this is not bound to a key.
11545796c8dcSSimon Schubert
11555796c8dcSSimon Schubert@item quoted-insert (C-q or C-v)
11565796c8dcSSimon SchubertAdd the next character typed to the line verbatim.  This is
11575796c8dcSSimon Schuberthow to insert key sequences like @kbd{C-q}, for example.
11585796c8dcSSimon Schubert
11595796c8dcSSimon Schubert@ifclear BashFeatures
11605796c8dcSSimon Schubert@item tab-insert (M-@key{TAB})
11615796c8dcSSimon SchubertInsert a tab character.
11625796c8dcSSimon Schubert@end ifclear
11635796c8dcSSimon Schubert
11645796c8dcSSimon Schubert@item self-insert (a, b, A, 1, !, @dots{})
11655796c8dcSSimon SchubertInsert yourself.
11665796c8dcSSimon Schubert
11675796c8dcSSimon Schubert@item transpose-chars (C-t)
11685796c8dcSSimon SchubertDrag the character before the cursor forward over
11695796c8dcSSimon Schubertthe character at the cursor, moving the
11705796c8dcSSimon Schubertcursor forward as well.  If the insertion point
11715796c8dcSSimon Schubertis at the end of the line, then this
11725796c8dcSSimon Schuberttransposes the last two characters of the line.
11735796c8dcSSimon SchubertNegative arguments have no effect.
11745796c8dcSSimon Schubert
11755796c8dcSSimon Schubert@item transpose-words (M-t)
11765796c8dcSSimon SchubertDrag the word before point past the word after point,
11775796c8dcSSimon Schubertmoving point past that word as well.
11785796c8dcSSimon SchubertIf the insertion point is at the end of the line, this transposes
11795796c8dcSSimon Schubertthe last two words on the line.
11805796c8dcSSimon Schubert
11815796c8dcSSimon Schubert@item upcase-word (M-u)
11825796c8dcSSimon SchubertUppercase the current (or following) word.  With a negative argument,
11835796c8dcSSimon Schubertuppercase the previous word, but do not move the cursor.
11845796c8dcSSimon Schubert
11855796c8dcSSimon Schubert@item downcase-word (M-l)
11865796c8dcSSimon SchubertLowercase the current (or following) word.  With a negative argument,
11875796c8dcSSimon Schubertlowercase the previous word, but do not move the cursor.
11885796c8dcSSimon Schubert
11895796c8dcSSimon Schubert@item capitalize-word (M-c)
11905796c8dcSSimon SchubertCapitalize the current (or following) word.  With a negative argument,
11915796c8dcSSimon Schubertcapitalize the previous word, but do not move the cursor.
11925796c8dcSSimon Schubert
11935796c8dcSSimon Schubert@item overwrite-mode ()
11945796c8dcSSimon SchubertToggle overwrite mode.  With an explicit positive numeric argument,
11955796c8dcSSimon Schubertswitches to overwrite mode.  With an explicit non-positive numeric
11965796c8dcSSimon Schubertargument, switches to insert mode.  This command affects only
11975796c8dcSSimon Schubert@code{emacs} mode; @code{vi} mode does overwrite differently.
11985796c8dcSSimon SchubertEach call to @code{readline()} starts in insert mode.
11995796c8dcSSimon Schubert
12005796c8dcSSimon SchubertIn overwrite mode, characters bound to @code{self-insert} replace
12015796c8dcSSimon Schubertthe text at point rather than pushing the text to the right.
12025796c8dcSSimon SchubertCharacters bound to @code{backward-delete-char} replace the character
12035796c8dcSSimon Schubertbefore point with a space.
12045796c8dcSSimon Schubert
12055796c8dcSSimon SchubertBy default, this command is unbound.
12065796c8dcSSimon Schubert
12075796c8dcSSimon Schubert@end ftable
12085796c8dcSSimon Schubert
12095796c8dcSSimon Schubert@node Commands For Killing
12105796c8dcSSimon Schubert@subsection Killing And Yanking
12115796c8dcSSimon Schubert
12125796c8dcSSimon Schubert@ftable @code
12135796c8dcSSimon Schubert
12145796c8dcSSimon Schubert@item kill-line (C-k)
12155796c8dcSSimon SchubertKill the text from point to the end of the line.
12165796c8dcSSimon Schubert
12175796c8dcSSimon Schubert@item backward-kill-line (C-x Rubout)
12185796c8dcSSimon SchubertKill backward to the beginning of the line.
12195796c8dcSSimon Schubert
12205796c8dcSSimon Schubert@item unix-line-discard (C-u)
12215796c8dcSSimon SchubertKill backward from the cursor to the beginning of the current line.
12225796c8dcSSimon Schubert
12235796c8dcSSimon Schubert@item kill-whole-line ()
12245796c8dcSSimon SchubertKill all characters on the current line, no matter where point is.
12255796c8dcSSimon SchubertBy default, this is unbound.
12265796c8dcSSimon Schubert
12275796c8dcSSimon Schubert@item kill-word (M-d)
12285796c8dcSSimon SchubertKill from point to the end of the current word, or if between
12295796c8dcSSimon Schubertwords, to the end of the next word.
12305796c8dcSSimon SchubertWord boundaries are the same as @code{forward-word}.
12315796c8dcSSimon Schubert
12325796c8dcSSimon Schubert@item backward-kill-word (M-@key{DEL})
12335796c8dcSSimon SchubertKill the word behind point.
12345796c8dcSSimon SchubertWord boundaries are the same as @code{backward-word}.
12355796c8dcSSimon Schubert
1236*a45ae5f8SJohn Marino@ifset BashFeatures
1237*a45ae5f8SJohn Marino@item shell-kill-word ()
1238*a45ae5f8SJohn MarinoKill from point to the end of the current word, or if between
1239*a45ae5f8SJohn Marinowords, to the end of the next word.
1240*a45ae5f8SJohn MarinoWord boundaries are the same as @code{shell-forward-word}.
1241*a45ae5f8SJohn Marino
1242*a45ae5f8SJohn Marino@item shell-backward-kill-word ()
1243*a45ae5f8SJohn MarinoKill the word behind point.
1244*a45ae5f8SJohn MarinoWord boundaries are the same as @code{shell-backward-word}.
1245*a45ae5f8SJohn Marino@end ifset
1246*a45ae5f8SJohn Marino
12475796c8dcSSimon Schubert@item unix-word-rubout (C-w)
12485796c8dcSSimon SchubertKill the word behind point, using white space as a word boundary.
12495796c8dcSSimon SchubertThe killed text is saved on the kill-ring.
12505796c8dcSSimon Schubert
12515796c8dcSSimon Schubert@item unix-filename-rubout ()
12525796c8dcSSimon SchubertKill the word behind point, using white space and the slash character
12535796c8dcSSimon Schubertas the word boundaries.
12545796c8dcSSimon SchubertThe killed text is saved on the kill-ring.
12555796c8dcSSimon Schubert
12565796c8dcSSimon Schubert@item delete-horizontal-space ()
12575796c8dcSSimon SchubertDelete all spaces and tabs around point.  By default, this is unbound.
12585796c8dcSSimon Schubert
12595796c8dcSSimon Schubert@item kill-region ()
12605796c8dcSSimon SchubertKill the text in the current region.
12615796c8dcSSimon SchubertBy default, this command is unbound.
12625796c8dcSSimon Schubert
12635796c8dcSSimon Schubert@item copy-region-as-kill ()
12645796c8dcSSimon SchubertCopy the text in the region to the kill buffer, so it can be yanked
12655796c8dcSSimon Schubertright away.  By default, this command is unbound.
12665796c8dcSSimon Schubert
12675796c8dcSSimon Schubert@item copy-backward-word ()
12685796c8dcSSimon SchubertCopy the word before point to the kill buffer.
12695796c8dcSSimon SchubertThe word boundaries are the same as @code{backward-word}.
12705796c8dcSSimon SchubertBy default, this command is unbound.
12715796c8dcSSimon Schubert
12725796c8dcSSimon Schubert@item copy-forward-word ()
12735796c8dcSSimon SchubertCopy the word following point to the kill buffer.
12745796c8dcSSimon SchubertThe word boundaries are the same as @code{forward-word}.
12755796c8dcSSimon SchubertBy default, this command is unbound.
12765796c8dcSSimon Schubert
12775796c8dcSSimon Schubert@item yank (C-y)
12785796c8dcSSimon SchubertYank the top of the kill ring into the buffer at point.
12795796c8dcSSimon Schubert
12805796c8dcSSimon Schubert@item yank-pop (M-y)
12815796c8dcSSimon SchubertRotate the kill-ring, and yank the new top.  You can only do this if
12825796c8dcSSimon Schubertthe prior command is @code{yank} or @code{yank-pop}.
12835796c8dcSSimon Schubert@end ftable
12845796c8dcSSimon Schubert
12855796c8dcSSimon Schubert@node Numeric Arguments
12865796c8dcSSimon Schubert@subsection Specifying Numeric Arguments
12875796c8dcSSimon Schubert@ftable @code
12885796c8dcSSimon Schubert
12895796c8dcSSimon Schubert@item digit-argument (@kbd{M-0}, @kbd{M-1}, @dots{} @kbd{M--})
12905796c8dcSSimon SchubertAdd this digit to the argument already accumulating, or start a new
12915796c8dcSSimon Schubertargument.  @kbd{M--} starts a negative argument.
12925796c8dcSSimon Schubert
12935796c8dcSSimon Schubert@item universal-argument ()
12945796c8dcSSimon SchubertThis is another way to specify an argument.
12955796c8dcSSimon SchubertIf this command is followed by one or more digits, optionally with a
12965796c8dcSSimon Schubertleading minus sign, those digits define the argument.
12975796c8dcSSimon SchubertIf the command is followed by digits, executing @code{universal-argument}
12985796c8dcSSimon Schubertagain ends the numeric argument, but is otherwise ignored.
12995796c8dcSSimon SchubertAs a special case, if this command is immediately followed by a
13005796c8dcSSimon Schubertcharacter that is neither a digit or minus sign, the argument count
13015796c8dcSSimon Schubertfor the next command is multiplied by four.
13025796c8dcSSimon SchubertThe argument count is initially one, so executing this function the
13035796c8dcSSimon Schubertfirst time makes the argument count four, a second time makes the
13045796c8dcSSimon Schubertargument count sixteen, and so on.
13055796c8dcSSimon SchubertBy default, this is not bound to a key.
13065796c8dcSSimon Schubert@end ftable
13075796c8dcSSimon Schubert
13085796c8dcSSimon Schubert@node Commands For Completion
13095796c8dcSSimon Schubert@subsection Letting Readline Type For You
13105796c8dcSSimon Schubert
13115796c8dcSSimon Schubert@ftable @code
13125796c8dcSSimon Schubert@item complete (@key{TAB})
13135796c8dcSSimon SchubertAttempt to perform completion on the text before point.
13145796c8dcSSimon SchubertThe actual completion performed is application-specific.
13155796c8dcSSimon Schubert@ifset BashFeatures
13165796c8dcSSimon SchubertBash attempts completion treating the text as a variable (if the
13175796c8dcSSimon Schuberttext begins with @samp{$}), username (if the text begins with
13185796c8dcSSimon Schubert@samp{~}), hostname (if the text begins with @samp{@@}), or
13195796c8dcSSimon Schubertcommand (including aliases and functions) in turn.  If none
13205796c8dcSSimon Schubertof these produces a match, filename completion is attempted.
13215796c8dcSSimon Schubert@end ifset
13225796c8dcSSimon Schubert@ifclear BashFeatures
13235796c8dcSSimon SchubertThe default is filename completion.
13245796c8dcSSimon Schubert@end ifclear
13255796c8dcSSimon Schubert
13265796c8dcSSimon Schubert@item possible-completions (M-?)
13275796c8dcSSimon SchubertList the possible completions of the text before point.
1328*a45ae5f8SJohn MarinoWhen displaying completions, Readline sets the number of columns used
1329*a45ae5f8SJohn Marinofor display to the value of @code{completion-display-width}, the value of
1330*a45ae5f8SJohn Marinothe environment variable @env{COLUMNS}, or the screen width, in that order.
13315796c8dcSSimon Schubert
13325796c8dcSSimon Schubert@item insert-completions (M-*)
13335796c8dcSSimon SchubertInsert all completions of the text before point that would have
13345796c8dcSSimon Schubertbeen generated by @code{possible-completions}.
13355796c8dcSSimon Schubert
13365796c8dcSSimon Schubert@item menu-complete ()
13375796c8dcSSimon SchubertSimilar to @code{complete}, but replaces the word to be completed
13385796c8dcSSimon Schubertwith a single match from the list of possible completions.
13395796c8dcSSimon SchubertRepeated execution of @code{menu-complete} steps through the list
13405796c8dcSSimon Schubertof possible completions, inserting each match in turn.
13415796c8dcSSimon SchubertAt the end of the list of completions, the bell is rung
13425796c8dcSSimon Schubert(subject to the setting of @code{bell-style})
13435796c8dcSSimon Schubertand the original text is restored.
13445796c8dcSSimon SchubertAn argument of @var{n} moves @var{n} positions forward in the list
13455796c8dcSSimon Schubertof matches; a negative argument may be used to move backward
13465796c8dcSSimon Schubertthrough the list.
13475796c8dcSSimon SchubertThis command is intended to be bound to @key{TAB}, but is unbound
13485796c8dcSSimon Schubertby default.
13495796c8dcSSimon Schubert
1350*a45ae5f8SJohn Marino@item menu-complete-backward ()
1351*a45ae5f8SJohn MarinoIdentical to @code{menu-complete}, but moves backward through the list
1352*a45ae5f8SJohn Marinoof possible completions, as if @code{menu-complete} had been given a
1353*a45ae5f8SJohn Marinonegative argument.
1354*a45ae5f8SJohn Marino
13555796c8dcSSimon Schubert@item delete-char-or-list ()
13565796c8dcSSimon SchubertDeletes the character under the cursor if not at the beginning or
13575796c8dcSSimon Schubertend of the line (like @code{delete-char}).
13585796c8dcSSimon SchubertIf at the end of the line, behaves identically to
13595796c8dcSSimon Schubert@code{possible-completions}.
13605796c8dcSSimon SchubertThis command is unbound by default.
13615796c8dcSSimon Schubert
13625796c8dcSSimon Schubert@ifset BashFeatures
13635796c8dcSSimon Schubert@item complete-filename (M-/)
13645796c8dcSSimon SchubertAttempt filename completion on the text before point.
13655796c8dcSSimon Schubert
13665796c8dcSSimon Schubert@item possible-filename-completions (C-x /)
13675796c8dcSSimon SchubertList the possible completions of the text before point,
13685796c8dcSSimon Schuberttreating it as a filename.
13695796c8dcSSimon Schubert
13705796c8dcSSimon Schubert@item complete-username (M-~)
13715796c8dcSSimon SchubertAttempt completion on the text before point, treating
13725796c8dcSSimon Schubertit as a username.
13735796c8dcSSimon Schubert
13745796c8dcSSimon Schubert@item possible-username-completions (C-x ~)
13755796c8dcSSimon SchubertList the possible completions of the text before point,
13765796c8dcSSimon Schuberttreating it as a username.
13775796c8dcSSimon Schubert
13785796c8dcSSimon Schubert@item complete-variable (M-$)
13795796c8dcSSimon SchubertAttempt completion on the text before point, treating
13805796c8dcSSimon Schubertit as a shell variable.
13815796c8dcSSimon Schubert
13825796c8dcSSimon Schubert@item possible-variable-completions (C-x $)
13835796c8dcSSimon SchubertList the possible completions of the text before point,
13845796c8dcSSimon Schuberttreating it as a shell variable.
13855796c8dcSSimon Schubert
13865796c8dcSSimon Schubert@item complete-hostname (M-@@)
13875796c8dcSSimon SchubertAttempt completion on the text before point, treating
13885796c8dcSSimon Schubertit as a hostname.
13895796c8dcSSimon Schubert
13905796c8dcSSimon Schubert@item possible-hostname-completions (C-x @@)
13915796c8dcSSimon SchubertList the possible completions of the text before point,
13925796c8dcSSimon Schuberttreating it as a hostname.
13935796c8dcSSimon Schubert
13945796c8dcSSimon Schubert@item complete-command (M-!)
13955796c8dcSSimon SchubertAttempt completion on the text before point, treating
13965796c8dcSSimon Schubertit as a command name.  Command completion attempts to
13975796c8dcSSimon Schubertmatch the text against aliases, reserved words, shell
13985796c8dcSSimon Schubertfunctions, shell builtins, and finally executable filenames,
13995796c8dcSSimon Schubertin that order.
14005796c8dcSSimon Schubert
14015796c8dcSSimon Schubert@item possible-command-completions (C-x !)
14025796c8dcSSimon SchubertList the possible completions of the text before point,
14035796c8dcSSimon Schuberttreating it as a command name.
14045796c8dcSSimon Schubert
14055796c8dcSSimon Schubert@item dynamic-complete-history (M-@key{TAB})
14065796c8dcSSimon SchubertAttempt completion on the text before point, comparing
14075796c8dcSSimon Schubertthe text against lines from the history list for possible
14085796c8dcSSimon Schubertcompletion matches.
14095796c8dcSSimon Schubert
1410*a45ae5f8SJohn Marino@item dabbrev-expand ()
1411*a45ae5f8SJohn MarinoAttempt menu completion on the text before point, comparing
1412*a45ae5f8SJohn Marinothe text against lines from the history list for possible
1413*a45ae5f8SJohn Marinocompletion matches.
1414*a45ae5f8SJohn Marino
14155796c8dcSSimon Schubert@item complete-into-braces (M-@{)
14165796c8dcSSimon SchubertPerform filename completion and insert the list of possible completions
14175796c8dcSSimon Schubertenclosed within braces so the list is available to the shell
14185796c8dcSSimon Schubert(@pxref{Brace Expansion}).
14195796c8dcSSimon Schubert
14205796c8dcSSimon Schubert@end ifset
14215796c8dcSSimon Schubert@end ftable
14225796c8dcSSimon Schubert
14235796c8dcSSimon Schubert@node Keyboard Macros
14245796c8dcSSimon Schubert@subsection Keyboard Macros
14255796c8dcSSimon Schubert@ftable @code
14265796c8dcSSimon Schubert
14275796c8dcSSimon Schubert@item start-kbd-macro (C-x ()
14285796c8dcSSimon SchubertBegin saving the characters typed into the current keyboard macro.
14295796c8dcSSimon Schubert
14305796c8dcSSimon Schubert@item end-kbd-macro (C-x ))
14315796c8dcSSimon SchubertStop saving the characters typed into the current keyboard macro
14325796c8dcSSimon Schubertand save the definition.
14335796c8dcSSimon Schubert
14345796c8dcSSimon Schubert@item call-last-kbd-macro (C-x e)
14355796c8dcSSimon SchubertRe-execute the last keyboard macro defined, by making the characters
14365796c8dcSSimon Schubertin the macro appear as if typed at the keyboard.
14375796c8dcSSimon Schubert
14385796c8dcSSimon Schubert@end ftable
14395796c8dcSSimon Schubert
14405796c8dcSSimon Schubert@node Miscellaneous Commands
14415796c8dcSSimon Schubert@subsection Some Miscellaneous Commands
14425796c8dcSSimon Schubert@ftable @code
14435796c8dcSSimon Schubert
14445796c8dcSSimon Schubert@item re-read-init-file (C-x C-r)
14455796c8dcSSimon SchubertRead in the contents of the @var{inputrc} file, and incorporate
14465796c8dcSSimon Schubertany bindings or variable assignments found there.
14475796c8dcSSimon Schubert
14485796c8dcSSimon Schubert@item abort (C-g)
14495796c8dcSSimon SchubertAbort the current editing command and
14505796c8dcSSimon Schubertring the terminal's bell (subject to the setting of
14515796c8dcSSimon Schubert@code{bell-style}).
14525796c8dcSSimon Schubert
14535796c8dcSSimon Schubert@item do-uppercase-version (M-a, M-b, M-@var{x}, @dots{})
14545796c8dcSSimon SchubertIf the metafied character @var{x} is lowercase, run the command
14555796c8dcSSimon Schubertthat is bound to the corresponding uppercase character.
14565796c8dcSSimon Schubert
14575796c8dcSSimon Schubert@item prefix-meta (@key{ESC})
14585796c8dcSSimon SchubertMetafy the next character typed.  This is for keyboards
14595796c8dcSSimon Schubertwithout a meta key.  Typing @samp{@key{ESC} f} is equivalent to typing
14605796c8dcSSimon Schubert@kbd{M-f}.
14615796c8dcSSimon Schubert
14625796c8dcSSimon Schubert@item undo (C-_ or C-x C-u)
14635796c8dcSSimon SchubertIncremental undo, separately remembered for each line.
14645796c8dcSSimon Schubert
14655796c8dcSSimon Schubert@item revert-line (M-r)
14665796c8dcSSimon SchubertUndo all changes made to this line.  This is like executing the @code{undo}
14675796c8dcSSimon Schubertcommand enough times to get back to the beginning.
14685796c8dcSSimon Schubert
14695796c8dcSSimon Schubert@ifset BashFeatures
14705796c8dcSSimon Schubert@item tilde-expand (M-&)
14715796c8dcSSimon Schubert@end ifset
14725796c8dcSSimon Schubert@ifclear BashFeatures
14735796c8dcSSimon Schubert@item tilde-expand (M-~)
14745796c8dcSSimon Schubert@end ifclear
14755796c8dcSSimon SchubertPerform tilde expansion on the current word.
14765796c8dcSSimon Schubert
14775796c8dcSSimon Schubert@item set-mark (C-@@)
14785796c8dcSSimon SchubertSet the mark to the point.  If a
14795796c8dcSSimon Schubertnumeric argument is supplied, the mark is set to that position.
14805796c8dcSSimon Schubert
14815796c8dcSSimon Schubert@item exchange-point-and-mark (C-x C-x)
14825796c8dcSSimon SchubertSwap the point with the mark.  The current cursor position is set to
14835796c8dcSSimon Schubertthe saved position, and the old cursor position is saved as the mark.
14845796c8dcSSimon Schubert
14855796c8dcSSimon Schubert@item character-search (C-])
14865796c8dcSSimon SchubertA character is read and point is moved to the next occurrence of that
14875796c8dcSSimon Schubertcharacter.  A negative count searches for previous occurrences.
14885796c8dcSSimon Schubert
14895796c8dcSSimon Schubert@item character-search-backward (M-C-])
14905796c8dcSSimon SchubertA character is read and point is moved to the previous occurrence
14915796c8dcSSimon Schubertof that character.  A negative count searches for subsequent
14925796c8dcSSimon Schubertoccurrences.
14935796c8dcSSimon Schubert
1494*a45ae5f8SJohn Marino@item skip-csi-sequence ()
1495*a45ae5f8SJohn MarinoRead enough characters to consume a multi-key sequence such as those
1496*a45ae5f8SJohn Marinodefined for keys like Home and End.  Such sequences begin with a
1497*a45ae5f8SJohn MarinoControl Sequence Indicator (CSI), usually ESC-[.  If this sequence is
1498*a45ae5f8SJohn Marinobound to "\e[", keys producing such sequences will have no effect
1499*a45ae5f8SJohn Marinounless explicitly bound to a readline command, instead of inserting
1500*a45ae5f8SJohn Marinostray characters into the editing buffer.  This is unbound by default,
1501*a45ae5f8SJohn Marinobut usually bound to ESC-[.
1502*a45ae5f8SJohn Marino
15035796c8dcSSimon Schubert@item insert-comment (M-#)
15045796c8dcSSimon SchubertWithout a numeric argument, the value of the @code{comment-begin}
15055796c8dcSSimon Schubertvariable is inserted at the beginning of the current line.
15065796c8dcSSimon SchubertIf a numeric argument is supplied, this command acts as a toggle:  if
15075796c8dcSSimon Schubertthe characters at the beginning of the line do not match the value
15085796c8dcSSimon Schubertof @code{comment-begin}, the value is inserted, otherwise
15095796c8dcSSimon Schubertthe characters in @code{comment-begin} are deleted from the beginning of
15105796c8dcSSimon Schubertthe line.
15115796c8dcSSimon SchubertIn either case, the line is accepted as if a newline had been typed.
15125796c8dcSSimon Schubert@ifset BashFeatures
15135796c8dcSSimon SchubertThe default value of @code{comment-begin} causes this command
15145796c8dcSSimon Schubertto make the current line a shell comment.
15155796c8dcSSimon SchubertIf a numeric argument causes the comment character to be removed, the line
15165796c8dcSSimon Schubertwill be executed by the shell.
15175796c8dcSSimon Schubert@end ifset
15185796c8dcSSimon Schubert
15195796c8dcSSimon Schubert@item dump-functions ()
15205796c8dcSSimon SchubertPrint all of the functions and their key bindings to the
15215796c8dcSSimon SchubertReadline output stream.  If a numeric argument is supplied,
15225796c8dcSSimon Schubertthe output is formatted in such a way that it can be made part
15235796c8dcSSimon Schubertof an @var{inputrc} file.  This command is unbound by default.
15245796c8dcSSimon Schubert
15255796c8dcSSimon Schubert@item dump-variables ()
15265796c8dcSSimon SchubertPrint all of the settable variables and their values to the
15275796c8dcSSimon SchubertReadline output stream.  If a numeric argument is supplied,
15285796c8dcSSimon Schubertthe output is formatted in such a way that it can be made part
15295796c8dcSSimon Schubertof an @var{inputrc} file.  This command is unbound by default.
15305796c8dcSSimon Schubert
15315796c8dcSSimon Schubert@item dump-macros ()
15325796c8dcSSimon SchubertPrint all of the Readline key sequences bound to macros and the
15335796c8dcSSimon Schubertstrings they output.  If a numeric argument is supplied,
15345796c8dcSSimon Schubertthe output is formatted in such a way that it can be made part
15355796c8dcSSimon Schubertof an @var{inputrc} file.  This command is unbound by default.
15365796c8dcSSimon Schubert
15375796c8dcSSimon Schubert@ifset BashFeatures
15385796c8dcSSimon Schubert@item glob-complete-word (M-g)
15395796c8dcSSimon SchubertThe word before point is treated as a pattern for pathname expansion,
15405796c8dcSSimon Schubertwith an asterisk implicitly appended.  This pattern is used to
15415796c8dcSSimon Schubertgenerate a list of matching file names for possible completions.
15425796c8dcSSimon Schubert
15435796c8dcSSimon Schubert@item glob-expand-word (C-x *)
15445796c8dcSSimon SchubertThe word before point is treated as a pattern for pathname expansion,
15455796c8dcSSimon Schubertand the list of matching file names is inserted, replacing the word.
15465796c8dcSSimon SchubertIf a numeric argument is supplied, a @samp{*} is appended before
15475796c8dcSSimon Schubertpathname expansion.
15485796c8dcSSimon Schubert
15495796c8dcSSimon Schubert@item glob-list-expansions (C-x g)
15505796c8dcSSimon SchubertThe list of expansions that would have been generated by
15515796c8dcSSimon Schubert@code{glob-expand-word} is displayed, and the line is redrawn.
15525796c8dcSSimon SchubertIf a numeric argument is supplied, a @samp{*} is appended before
15535796c8dcSSimon Schubertpathname expansion.
15545796c8dcSSimon Schubert
15555796c8dcSSimon Schubert@item display-shell-version (C-x C-v)
15565796c8dcSSimon SchubertDisplay version information about the current instance of Bash.
15575796c8dcSSimon Schubert
15585796c8dcSSimon Schubert@item shell-expand-line (M-C-e)
15595796c8dcSSimon SchubertExpand the line as the shell does.
15605796c8dcSSimon SchubertThis performs alias and history expansion as well as all of the shell
15615796c8dcSSimon Schubertword expansions (@pxref{Shell Expansions}).
15625796c8dcSSimon Schubert
15635796c8dcSSimon Schubert@item history-expand-line (M-^)
15645796c8dcSSimon SchubertPerform history expansion on the current line.
15655796c8dcSSimon Schubert
15665796c8dcSSimon Schubert@item magic-space ()
15675796c8dcSSimon SchubertPerform history expansion on the current line and insert a space
15685796c8dcSSimon Schubert(@pxref{History Interaction}).
15695796c8dcSSimon Schubert
15705796c8dcSSimon Schubert@item alias-expand-line ()
15715796c8dcSSimon SchubertPerform alias expansion on the current line (@pxref{Aliases}).
15725796c8dcSSimon Schubert
15735796c8dcSSimon Schubert@item history-and-alias-expand-line ()
15745796c8dcSSimon SchubertPerform history and alias expansion on the current line.
15755796c8dcSSimon Schubert
15765796c8dcSSimon Schubert@item insert-last-argument (M-. or M-_)
15775796c8dcSSimon SchubertA synonym for @code{yank-last-arg}.
15785796c8dcSSimon Schubert
15795796c8dcSSimon Schubert@item operate-and-get-next (C-o)
15805796c8dcSSimon SchubertAccept the current line for execution and fetch the next line
15815796c8dcSSimon Schubertrelative to the current line from the history for editing.  Any
15825796c8dcSSimon Schubertargument is ignored.
15835796c8dcSSimon Schubert
15845796c8dcSSimon Schubert@item edit-and-execute-command (C-xC-e)
15855796c8dcSSimon SchubertInvoke an editor on the current command line, and execute the result as shell
15865796c8dcSSimon Schubertcommands.
15875796c8dcSSimon SchubertBash attempts to invoke
15885796c8dcSSimon Schubert@code{$VISUAL}, @code{$EDITOR}, and @code{emacs}
15895796c8dcSSimon Schubertas the editor, in that order.
15905796c8dcSSimon Schubert
15915796c8dcSSimon Schubert@end ifset
15925796c8dcSSimon Schubert
15935796c8dcSSimon Schubert@ifclear BashFeatures
15945796c8dcSSimon Schubert@item emacs-editing-mode (C-e)
15955796c8dcSSimon SchubertWhen in @code{vi} command mode, this causes a switch to @code{emacs}
15965796c8dcSSimon Schubertediting mode.
15975796c8dcSSimon Schubert
15985796c8dcSSimon Schubert@item vi-editing-mode (M-C-j)
15995796c8dcSSimon SchubertWhen in @code{emacs} editing mode, this causes a switch to @code{vi}
16005796c8dcSSimon Schubertediting mode.
16015796c8dcSSimon Schubert
16025796c8dcSSimon Schubert@end ifclear
16035796c8dcSSimon Schubert
16045796c8dcSSimon Schubert@end ftable
16055796c8dcSSimon Schubert
16065796c8dcSSimon Schubert@node Readline vi Mode
16075796c8dcSSimon Schubert@section Readline vi Mode
16085796c8dcSSimon Schubert
16095796c8dcSSimon SchubertWhile the Readline library does not have a full set of @code{vi}
16105796c8dcSSimon Schubertediting functions, it does contain enough to allow simple editing
16115796c8dcSSimon Schubertof the line.  The Readline @code{vi} mode behaves as specified in
1612*a45ae5f8SJohn Marinothe @sc{posix} standard.
16135796c8dcSSimon Schubert
16145796c8dcSSimon Schubert@ifset BashFeatures
16155796c8dcSSimon SchubertIn order to switch interactively between @code{emacs} and @code{vi}
16165796c8dcSSimon Schubertediting modes, use the @samp{set -o emacs} and @samp{set -o vi}
16175796c8dcSSimon Schubertcommands (@pxref{The Set Builtin}).
16185796c8dcSSimon Schubert@end ifset
16195796c8dcSSimon Schubert@ifclear BashFeatures
16205796c8dcSSimon SchubertIn order to switch interactively between @code{emacs} and @code{vi}
16215796c8dcSSimon Schubertediting modes, use the command @kbd{M-C-j} (bound to emacs-editing-mode
16225796c8dcSSimon Schubertwhen in @code{vi} mode and to vi-editing-mode in @code{emacs} mode).
16235796c8dcSSimon Schubert@end ifclear
16245796c8dcSSimon SchubertThe Readline default is @code{emacs} mode.
16255796c8dcSSimon Schubert
16265796c8dcSSimon SchubertWhen you enter a line in @code{vi} mode, you are already placed in
16275796c8dcSSimon Schubert`insertion' mode, as if you had typed an @samp{i}.  Pressing @key{ESC}
16285796c8dcSSimon Schubertswitches you into `command' mode, where you can edit the text of the
16295796c8dcSSimon Schubertline with the standard @code{vi} movement keys, move to previous
16305796c8dcSSimon Schuberthistory lines with @samp{k} and subsequent lines with @samp{j}, and
16315796c8dcSSimon Schubertso forth.
16325796c8dcSSimon Schubert
16335796c8dcSSimon Schubert@ifset BashFeatures
16345796c8dcSSimon Schubert@node Programmable Completion
16355796c8dcSSimon Schubert@section Programmable Completion
16365796c8dcSSimon Schubert@cindex programmable completion
16375796c8dcSSimon Schubert
16385796c8dcSSimon SchubertWhen word completion is attempted for an argument to a command for
16395796c8dcSSimon Schubertwhich a completion specification (a @var{compspec}) has been defined
16405796c8dcSSimon Schubertusing the @code{complete} builtin (@pxref{Programmable Completion Builtins}),
16415796c8dcSSimon Schubertthe programmable completion facilities are invoked.
16425796c8dcSSimon Schubert
16435796c8dcSSimon SchubertFirst, the command name is identified.
16445796c8dcSSimon SchubertIf a compspec has been defined for that command, the
16455796c8dcSSimon Schubertcompspec is used to generate the list of possible completions for the word.
1646*a45ae5f8SJohn MarinoIf the command word is the empty string (completion attempted at the
1647*a45ae5f8SJohn Marinobeginning of an empty line), any compspec defined with
1648*a45ae5f8SJohn Marinothe @option{-E} option to @code{complete} is used.
16495796c8dcSSimon SchubertIf the command word is a full pathname, a compspec for the full
16505796c8dcSSimon Schubertpathname is searched for first.
16515796c8dcSSimon SchubertIf no compspec is found for the full pathname, an attempt is made to
16525796c8dcSSimon Schubertfind a compspec for the portion following the final slash.
1653*a45ae5f8SJohn MarinoIf those searches do not result in a compspec, any compspec defined with
1654*a45ae5f8SJohn Marinothe @option{-D} option to @code{complete} is used as the default.
16555796c8dcSSimon Schubert
16565796c8dcSSimon SchubertOnce a compspec has been found, it is used to generate the list of
16575796c8dcSSimon Schubertmatching words.
16585796c8dcSSimon SchubertIf a compspec is not found, the default Bash completion
16595796c8dcSSimon Schubertdescribed above (@pxref{Commands For Completion}) is performed.
16605796c8dcSSimon Schubert
16615796c8dcSSimon SchubertFirst, the actions specified by the compspec are used.
16625796c8dcSSimon SchubertOnly matches which are prefixed by the word being completed are
16635796c8dcSSimon Schubertreturned.
16645796c8dcSSimon SchubertWhen the @option{-f} or @option{-d} option is used for filename or
16655796c8dcSSimon Schubertdirectory name completion, the shell variable @env{FIGNORE} is
16665796c8dcSSimon Schubertused to filter the matches.
16675796c8dcSSimon Schubert@xref{Bash Variables}, for a description of @env{FIGNORE}.
16685796c8dcSSimon Schubert
16695796c8dcSSimon SchubertAny completions specified by a filename expansion pattern to the
16705796c8dcSSimon Schubert@option{-G} option are generated next.
16715796c8dcSSimon SchubertThe words generated by the pattern need not match the word being completed.
16725796c8dcSSimon SchubertThe @env{GLOBIGNORE} shell variable is not used to filter the matches,
16735796c8dcSSimon Schubertbut the @env{FIGNORE} shell variable is used.
16745796c8dcSSimon Schubert
16755796c8dcSSimon SchubertNext, the string specified as the argument to the @option{-W} option
16765796c8dcSSimon Schubertis considered.
16775796c8dcSSimon SchubertThe string is first split using the characters in the @env{IFS}
16785796c8dcSSimon Schubertspecial variable as delimiters.
16795796c8dcSSimon SchubertShell quoting is honored.
16805796c8dcSSimon SchubertEach word is then expanded using
16815796c8dcSSimon Schubertbrace expansion, tilde expansion, parameter and variable expansion,
16825796c8dcSSimon Schubertcommand substitution, and arithmetic expansion,
16835796c8dcSSimon Schubertas described above (@pxref{Shell Expansions}).
16845796c8dcSSimon SchubertThe results are split using the rules described above
16855796c8dcSSimon Schubert(@pxref{Word Splitting}).
16865796c8dcSSimon SchubertThe results of the expansion are prefix-matched against the word being
16875796c8dcSSimon Schubertcompleted, and the matching words become the possible completions.
16885796c8dcSSimon Schubert
16895796c8dcSSimon SchubertAfter these matches have been generated, any shell function or command
16905796c8dcSSimon Schubertspecified with the @option{-F} and @option{-C} options is invoked.
1691*a45ae5f8SJohn MarinoWhen the command or function is invoked, the @env{COMP_LINE},
1692*a45ae5f8SJohn Marino@env{COMP_POINT}, @env{COMP_KEY}, and @env{COMP_TYPE} variables are
1693*a45ae5f8SJohn Marinoassigned values as described above (@pxref{Bash Variables}).
16945796c8dcSSimon SchubertIf a shell function is being invoked, the @env{COMP_WORDS} and
16955796c8dcSSimon Schubert@env{COMP_CWORD} variables are also set.
16965796c8dcSSimon SchubertWhen the function or command is invoked, the first argument is the
16975796c8dcSSimon Schubertname of the command whose arguments are being completed, the
16985796c8dcSSimon Schubertsecond argument is the word being completed, and the third argument
16995796c8dcSSimon Schubertis the word preceding the word being completed on the current command line.
17005796c8dcSSimon SchubertNo filtering of the generated completions against the word being completed
17015796c8dcSSimon Schubertis performed; the function or command has complete freedom in generating
17025796c8dcSSimon Schubertthe matches.
17035796c8dcSSimon Schubert
17045796c8dcSSimon SchubertAny function specified with @option{-F} is invoked first.
17055796c8dcSSimon SchubertThe function may use any of the shell facilities, including the
1706*a45ae5f8SJohn Marino@code{compgen} and @code{compopt} builtins described below
17075796c8dcSSimon Schubert(@pxref{Programmable Completion Builtins}), to generate the matches.
17085796c8dcSSimon SchubertIt must put the possible completions in the @env{COMPREPLY} array
17095796c8dcSSimon Schubertvariable.
17105796c8dcSSimon Schubert
17115796c8dcSSimon SchubertNext, any command specified with the @option{-C} option is invoked
17125796c8dcSSimon Schubertin an environment equivalent to command substitution.
17135796c8dcSSimon SchubertIt should print a list of completions, one per line, to
17145796c8dcSSimon Schubertthe standard output.
17155796c8dcSSimon SchubertBackslash may be used to escape a newline, if necessary.
17165796c8dcSSimon Schubert
17175796c8dcSSimon SchubertAfter all of the possible completions are generated, any filter
17185796c8dcSSimon Schubertspecified with the @option{-X} option is applied to the list.
17195796c8dcSSimon SchubertThe filter is a pattern as used for pathname expansion; a @samp{&}
17205796c8dcSSimon Schubertin the pattern is replaced with the text of the word being completed.
17215796c8dcSSimon SchubertA literal @samp{&} may be escaped with a backslash; the backslash
17225796c8dcSSimon Schubertis removed before attempting a match.
17235796c8dcSSimon SchubertAny completion that matches the pattern will be removed from the list.
17245796c8dcSSimon SchubertA leading @samp{!} negates the pattern; in this case any completion
17255796c8dcSSimon Schubertnot matching the pattern will be removed.
17265796c8dcSSimon Schubert
17275796c8dcSSimon SchubertFinally, any prefix and suffix specified with the @option{-P} and @option{-S}
17285796c8dcSSimon Schubertoptions are added to each member of the completion list, and the result is
17295796c8dcSSimon Schubertreturned to the Readline completion code as the list of possible
17305796c8dcSSimon Schubertcompletions.
17315796c8dcSSimon Schubert
17325796c8dcSSimon SchubertIf the previously-applied actions do not generate any matches, and the
17335796c8dcSSimon Schubert@option{-o dirnames} option was supplied to @code{complete} when the
17345796c8dcSSimon Schubertcompspec was defined, directory name completion is attempted.
17355796c8dcSSimon Schubert
17365796c8dcSSimon SchubertIf the @option{-o plusdirs} option was supplied to @code{complete} when
17375796c8dcSSimon Schubertthe compspec was defined, directory name completion is attempted and any
17385796c8dcSSimon Schubertmatches are added to the results of the other actions.
17395796c8dcSSimon Schubert
17405796c8dcSSimon SchubertBy default, if a compspec is found, whatever it generates is returned to
17415796c8dcSSimon Schubertthe completion code as the full set of possible completions.
17425796c8dcSSimon SchubertThe default Bash completions are not attempted, and the Readline default
17435796c8dcSSimon Schubertof filename completion is disabled.
17445796c8dcSSimon SchubertIf the @option{-o bashdefault} option was supplied to @code{complete} when
17455796c8dcSSimon Schubertthe compspec was defined, the default Bash completions are attempted
17465796c8dcSSimon Schubertif the compspec generates no matches.
17475796c8dcSSimon SchubertIf the @option{-o default} option was supplied to @code{complete} when the
17485796c8dcSSimon Schubertcompspec was defined, Readline's default completion will be performed
17495796c8dcSSimon Schubertif the compspec (and, if attempted, the default Bash completions)
17505796c8dcSSimon Schubertgenerate no matches.
17515796c8dcSSimon Schubert
17525796c8dcSSimon SchubertWhen a compspec indicates that directory name completion is desired,
17535796c8dcSSimon Schubertthe programmable completion functions force Readline to append a slash
17545796c8dcSSimon Schubertto completed names which are symbolic links to directories, subject to
17555796c8dcSSimon Schubertthe value of the @var{mark-directories} Readline variable, regardless
17565796c8dcSSimon Schubertof the setting of the @var{mark-symlinked-directories} Readline variable.
17575796c8dcSSimon Schubert
1758*a45ae5f8SJohn MarinoThere is some support for dynamically modifying completions.  This is
1759*a45ae5f8SJohn Marinomost useful when used in combination with a default completion specified
1760*a45ae5f8SJohn Marinowith @option{-D}.  It's possible for shell functions executed as completion
1761*a45ae5f8SJohn Marinohandlers to indicate that completion should be retried by returning an
1762*a45ae5f8SJohn Marinoexit status of 124.  If a shell function returns 124, and changes
1763*a45ae5f8SJohn Marinothe compspec associated with the command on which completion is being
1764*a45ae5f8SJohn Marinoattempted (supplied as the first argument when the function is executed),
1765*a45ae5f8SJohn Marinoprogrammable completion restarts from the beginning, with an
1766*a45ae5f8SJohn Marinoattempt to find a new compspec for that command.  This allows a set of
1767*a45ae5f8SJohn Marinocompletions to be built dynamically as completion is attempted, rather than
1768*a45ae5f8SJohn Marinobeing loaded all at once.
1769*a45ae5f8SJohn Marino
1770*a45ae5f8SJohn MarinoFor instance, assuming that there is a library of compspecs, each kept in a
1771*a45ae5f8SJohn Marinofile corresponding to the name of the command, the following default
1772*a45ae5f8SJohn Marinocompletion function would load completions dynamically:
1773*a45ae5f8SJohn Marino
1774*a45ae5f8SJohn Marino@example
1775*a45ae5f8SJohn Marino_completion_loader()
1776*a45ae5f8SJohn Marino@{
1777*a45ae5f8SJohn Marino	. "/etc/bash_completion.d/$1.sh" >/dev/null 2>&1 && return 124
1778*a45ae5f8SJohn Marino@}
1779*a45ae5f8SJohn Marinocomplete -D -F _completion_loader
1780*a45ae5f8SJohn Marino@end example
1781*a45ae5f8SJohn Marino
17825796c8dcSSimon Schubert@node Programmable Completion Builtins
17835796c8dcSSimon Schubert@section Programmable Completion Builtins
17845796c8dcSSimon Schubert@cindex completion builtins
17855796c8dcSSimon Schubert
17865796c8dcSSimon SchubertTwo builtin commands are available to manipulate the programmable completion
17875796c8dcSSimon Schubertfacilities.
17885796c8dcSSimon Schubert
17895796c8dcSSimon Schubert@table @code
17905796c8dcSSimon Schubert@item compgen
17915796c8dcSSimon Schubert@btindex compgen
17925796c8dcSSimon Schubert@example
17935796c8dcSSimon Schubert@code{compgen [@var{option}] [@var{word}]}
17945796c8dcSSimon Schubert@end example
17955796c8dcSSimon Schubert
17965796c8dcSSimon SchubertGenerate possible completion matches for @var{word} according to
17975796c8dcSSimon Schubertthe @var{option}s, which may be any option accepted by the
17985796c8dcSSimon Schubert@code{complete}
17995796c8dcSSimon Schubertbuiltin with the exception of @option{-p} and @option{-r}, and write
18005796c8dcSSimon Schubertthe matches to the standard output.
18015796c8dcSSimon SchubertWhen using the @option{-F} or @option{-C} options, the various shell variables
18025796c8dcSSimon Schubertset by the programmable completion facilities, while available, will not
18035796c8dcSSimon Schuberthave useful values.
18045796c8dcSSimon Schubert
18055796c8dcSSimon SchubertThe matches will be generated in the same way as if the programmable
18065796c8dcSSimon Schubertcompletion code had generated them directly from a completion specification
18075796c8dcSSimon Schubertwith the same flags.
18085796c8dcSSimon SchubertIf @var{word} is specified, only those completions matching @var{word}
18095796c8dcSSimon Schubertwill be displayed.
18105796c8dcSSimon Schubert
18115796c8dcSSimon SchubertThe return value is true unless an invalid option is supplied, or no
18125796c8dcSSimon Schubertmatches were generated.
18135796c8dcSSimon Schubert
18145796c8dcSSimon Schubert@item complete
18155796c8dcSSimon Schubert@btindex complete
18165796c8dcSSimon Schubert@example
1817*a45ae5f8SJohn Marino@code{complete [-abcdefgjksuv] [-o @var{comp-option}] [-DE] [-A @var{action}] [-G @var{globpat}] [-W @var{wordlist}]
1818*a45ae5f8SJohn Marino[-F @var{function}] [-C @var{command}] [-X @var{filterpat}]
1819*a45ae5f8SJohn Marino[-P @var{prefix}] [-S @var{suffix}] @var{name} [@var{name} @dots{}]}
1820*a45ae5f8SJohn Marino@code{complete -pr [-DE] [@var{name} @dots{}]}
18215796c8dcSSimon Schubert@end example
18225796c8dcSSimon Schubert
18235796c8dcSSimon SchubertSpecify how arguments to each @var{name} should be completed.
18245796c8dcSSimon SchubertIf the @option{-p} option is supplied, or if no options are supplied, existing
18255796c8dcSSimon Schubertcompletion specifications are printed in a way that allows them to be
18265796c8dcSSimon Schubertreused as input.
18275796c8dcSSimon SchubertThe @option{-r} option removes a completion specification for
18285796c8dcSSimon Schuberteach @var{name}, or, if no @var{name}s are supplied, all
18295796c8dcSSimon Schubertcompletion specifications.
1830*a45ae5f8SJohn MarinoThe @option{-D} option indicates that the remaining options and actions should
1831*a45ae5f8SJohn Marinoapply to the ``default'' command completion; that is, completion attempted
1832*a45ae5f8SJohn Marinoon a command for which no completion has previously been defined.
1833*a45ae5f8SJohn MarinoThe @option{-E} option indicates that the remaining options and actions should
1834*a45ae5f8SJohn Marinoapply to ``empty'' command completion; that is, completion attempted on a
1835*a45ae5f8SJohn Marinoblank line.
18365796c8dcSSimon Schubert
18375796c8dcSSimon SchubertThe process of applying these completion specifications when word completion
1838*a45ae5f8SJohn Marinois attempted is described above (@pxref{Programmable Completion}).  The
1839*a45ae5f8SJohn Marino@option{-D} option takes precedence over @option{-E}.
18405796c8dcSSimon Schubert
18415796c8dcSSimon SchubertOther options, if specified, have the following meanings.
18425796c8dcSSimon SchubertThe arguments to the @option{-G}, @option{-W}, and @option{-X} options
18435796c8dcSSimon Schubert(and, if necessary, the @option{-P} and @option{-S} options)
18445796c8dcSSimon Schubertshould be quoted to protect them from expansion before the
18455796c8dcSSimon Schubert@code{complete} builtin is invoked.
18465796c8dcSSimon Schubert
18475796c8dcSSimon Schubert
18485796c8dcSSimon Schubert@table @code
18495796c8dcSSimon Schubert@item -o @var{comp-option}
18505796c8dcSSimon SchubertThe @var{comp-option} controls several aspects of the compspec's behavior
18515796c8dcSSimon Schubertbeyond the simple generation of completions.
18525796c8dcSSimon Schubert@var{comp-option} may be one of:
18535796c8dcSSimon Schubert
18545796c8dcSSimon Schubert@table @code
18555796c8dcSSimon Schubert
18565796c8dcSSimon Schubert@item bashdefault
18575796c8dcSSimon SchubertPerform the rest of the default Bash completions if the compspec
18585796c8dcSSimon Schubertgenerates no matches.
18595796c8dcSSimon Schubert
18605796c8dcSSimon Schubert@item default
18615796c8dcSSimon SchubertUse Readline's default filename completion if the compspec generates
18625796c8dcSSimon Schubertno matches.
18635796c8dcSSimon Schubert
18645796c8dcSSimon Schubert@item dirnames
18655796c8dcSSimon SchubertPerform directory name completion if the compspec generates no matches.
18665796c8dcSSimon Schubert
18675796c8dcSSimon Schubert@item filenames
18685796c8dcSSimon SchubertTell Readline that the compspec generates filenames, so it can perform any
1869*a45ae5f8SJohn Marinofilename-specific processing (like adding a slash to directory names
1870*a45ae5f8SJohn Marinoquoting special characters, or suppressing trailing spaces).
1871*a45ae5f8SJohn MarinoThis option is intended to be used with shell functions specified
1872*a45ae5f8SJohn Marinowith @option{-F}.
18735796c8dcSSimon Schubert
18745796c8dcSSimon Schubert@item nospace
18755796c8dcSSimon SchubertTell Readline not to append a space (the default) to words completed at
18765796c8dcSSimon Schubertthe end of the line.
18775796c8dcSSimon Schubert
18785796c8dcSSimon Schubert@item plusdirs
18795796c8dcSSimon SchubertAfter any matches defined by the compspec are generated,
18805796c8dcSSimon Schubertdirectory name completion is attempted and any
18815796c8dcSSimon Schubertmatches are added to the results of the other actions.
18825796c8dcSSimon Schubert
18835796c8dcSSimon Schubert@end table
18845796c8dcSSimon Schubert
18855796c8dcSSimon Schubert@item -A @var{action}
18865796c8dcSSimon SchubertThe @var{action} may be one of the following to generate a list of possible
18875796c8dcSSimon Schubertcompletions:
18885796c8dcSSimon Schubert
18895796c8dcSSimon Schubert@table @code
18905796c8dcSSimon Schubert@item alias
18915796c8dcSSimon SchubertAlias names.  May also be specified as @option{-a}.
18925796c8dcSSimon Schubert
18935796c8dcSSimon Schubert@item arrayvar
18945796c8dcSSimon SchubertArray variable names.
18955796c8dcSSimon Schubert
18965796c8dcSSimon Schubert@item binding
18975796c8dcSSimon SchubertReadline key binding names (@pxref{Bindable Readline Commands}).
18985796c8dcSSimon Schubert
18995796c8dcSSimon Schubert@item builtin
19005796c8dcSSimon SchubertNames of shell builtin commands.  May also be specified as @option{-b}.
19015796c8dcSSimon Schubert
19025796c8dcSSimon Schubert@item command
19035796c8dcSSimon SchubertCommand names.  May also be specified as @option{-c}.
19045796c8dcSSimon Schubert
19055796c8dcSSimon Schubert@item directory
19065796c8dcSSimon SchubertDirectory names.  May also be specified as @option{-d}.
19075796c8dcSSimon Schubert
19085796c8dcSSimon Schubert@item disabled
19095796c8dcSSimon SchubertNames of disabled shell builtins.
19105796c8dcSSimon Schubert
19115796c8dcSSimon Schubert@item enabled
19125796c8dcSSimon SchubertNames of enabled shell builtins.
19135796c8dcSSimon Schubert
19145796c8dcSSimon Schubert@item export
19155796c8dcSSimon SchubertNames of exported shell variables.  May also be specified as @option{-e}.
19165796c8dcSSimon Schubert
19175796c8dcSSimon Schubert@item file
19185796c8dcSSimon SchubertFile names.  May also be specified as @option{-f}.
19195796c8dcSSimon Schubert
19205796c8dcSSimon Schubert@item function
19215796c8dcSSimon SchubertNames of shell functions.
19225796c8dcSSimon Schubert
19235796c8dcSSimon Schubert@item group
19245796c8dcSSimon SchubertGroup names.  May also be specified as @option{-g}.
19255796c8dcSSimon Schubert
19265796c8dcSSimon Schubert@item helptopic
19275796c8dcSSimon SchubertHelp topics as accepted by the @code{help} builtin (@pxref{Bash Builtins}).
19285796c8dcSSimon Schubert
19295796c8dcSSimon Schubert@item hostname
19305796c8dcSSimon SchubertHostnames, as taken from the file specified by the
19315796c8dcSSimon Schubert@env{HOSTFILE} shell variable (@pxref{Bash Variables}).
19325796c8dcSSimon Schubert
19335796c8dcSSimon Schubert@item job
19345796c8dcSSimon SchubertJob names, if job control is active.  May also be specified as @option{-j}.
19355796c8dcSSimon Schubert
19365796c8dcSSimon Schubert@item keyword
19375796c8dcSSimon SchubertShell reserved words.  May also be specified as @option{-k}.
19385796c8dcSSimon Schubert
19395796c8dcSSimon Schubert@item running
19405796c8dcSSimon SchubertNames of running jobs, if job control is active.
19415796c8dcSSimon Schubert
19425796c8dcSSimon Schubert@item service
19435796c8dcSSimon SchubertService names.  May also be specified as @option{-s}.
19445796c8dcSSimon Schubert
19455796c8dcSSimon Schubert@item setopt
19465796c8dcSSimon SchubertValid arguments for the @option{-o} option to the @code{set} builtin
19475796c8dcSSimon Schubert(@pxref{The Set Builtin}).
19485796c8dcSSimon Schubert
19495796c8dcSSimon Schubert@item shopt
19505796c8dcSSimon SchubertShell option names as accepted by the @code{shopt} builtin
19515796c8dcSSimon Schubert(@pxref{Bash Builtins}).
19525796c8dcSSimon Schubert
19535796c8dcSSimon Schubert@item signal
19545796c8dcSSimon SchubertSignal names.
19555796c8dcSSimon Schubert
19565796c8dcSSimon Schubert@item stopped
19575796c8dcSSimon SchubertNames of stopped jobs, if job control is active.
19585796c8dcSSimon Schubert
19595796c8dcSSimon Schubert@item user
19605796c8dcSSimon SchubertUser names.  May also be specified as @option{-u}.
19615796c8dcSSimon Schubert
19625796c8dcSSimon Schubert@item variable
19635796c8dcSSimon SchubertNames of all shell variables.  May also be specified as @option{-v}.
19645796c8dcSSimon Schubert@end table
19655796c8dcSSimon Schubert
19665796c8dcSSimon Schubert@item -C @var{command}
19675796c8dcSSimon Schubert@var{command} is executed in a subshell environment, and its output is
19685796c8dcSSimon Schubertused as the possible completions.
19695796c8dcSSimon Schubert
19705796c8dcSSimon Schubert@item -F @var{function}
19715796c8dcSSimon SchubertThe shell function @var{function} is executed in the current shell
19725796c8dcSSimon Schubertenvironment.
19735796c8dcSSimon SchubertWhen it finishes, the possible completions are retrieved from the value
19745796c8dcSSimon Schubertof the @env{COMPREPLY} array variable.
19755796c8dcSSimon Schubert
1976*a45ae5f8SJohn Marino@item -G @var{globpat}
1977*a45ae5f8SJohn MarinoThe filename expansion pattern @var{globpat} is expanded to generate
1978*a45ae5f8SJohn Marinothe possible completions.
19795796c8dcSSimon Schubert
19805796c8dcSSimon Schubert@item -P @var{prefix}
19815796c8dcSSimon Schubert@var{prefix} is added at the beginning of each possible completion
19825796c8dcSSimon Schubertafter all other options have been applied.
19835796c8dcSSimon Schubert
19845796c8dcSSimon Schubert@item -S @var{suffix}
19855796c8dcSSimon Schubert@var{suffix} is appended to each possible completion
19865796c8dcSSimon Schubertafter all other options have been applied.
1987*a45ae5f8SJohn Marino
1988*a45ae5f8SJohn Marino@item -W @var{wordlist}
1989*a45ae5f8SJohn MarinoThe @var{wordlist} is split using the characters in the
1990*a45ae5f8SJohn Marino@env{IFS} special variable as delimiters, and each resultant word
1991*a45ae5f8SJohn Marinois expanded.
1992*a45ae5f8SJohn MarinoThe possible completions are the members of the resultant list which
1993*a45ae5f8SJohn Marinomatch the word being completed.
1994*a45ae5f8SJohn Marino
1995*a45ae5f8SJohn Marino@item -X @var{filterpat}
1996*a45ae5f8SJohn Marino@var{filterpat} is a pattern as used for filename expansion.
1997*a45ae5f8SJohn MarinoIt is applied to the list of possible completions generated by the
1998*a45ae5f8SJohn Marinopreceding options and arguments, and each completion matching
1999*a45ae5f8SJohn Marino@var{filterpat} is removed from the list.
2000*a45ae5f8SJohn MarinoA leading @samp{!} in @var{filterpat} negates the pattern; in this
2001*a45ae5f8SJohn Marinocase, any completion not matching @var{filterpat} is removed.
20025796c8dcSSimon Schubert@end table
20035796c8dcSSimon Schubert
20045796c8dcSSimon SchubertThe return value is true unless an invalid option is supplied, an option
20055796c8dcSSimon Schubertother than @option{-p} or @option{-r} is supplied without a @var{name}
20065796c8dcSSimon Schubertargument, an attempt is made to remove a completion specification for
20075796c8dcSSimon Schuberta @var{name} for which no specification exists, or
20085796c8dcSSimon Schubertan error occurs adding a completion specification.
20095796c8dcSSimon Schubert
2010*a45ae5f8SJohn Marino@item compopt
2011*a45ae5f8SJohn Marino@btindex compopt
2012*a45ae5f8SJohn Marino@example
2013*a45ae5f8SJohn Marino@code{compopt} [-o @var{option}] [-DE] [+o @var{option}] [@var{name}]
2014*a45ae5f8SJohn Marino@end example
2015*a45ae5f8SJohn MarinoModify completion options for each @var{name} according to the
2016*a45ae5f8SJohn Marino@var{option}s, or for the currently-executing completion if no @var{name}s
2017*a45ae5f8SJohn Marinoare supplied.
2018*a45ae5f8SJohn MarinoIf no @var{option}s are given, display the completion options for each
2019*a45ae5f8SJohn Marino@var{name} or the current completion.
2020*a45ae5f8SJohn MarinoThe possible values of @var{option} are those valid for the @code{complete}
2021*a45ae5f8SJohn Marinobuiltin described above.
2022*a45ae5f8SJohn MarinoThe @option{-D} option indicates that the remaining options should
2023*a45ae5f8SJohn Marinoapply to the ``default'' command completion; that is, completion attempted
2024*a45ae5f8SJohn Marinoon a command for which no completion has previously been defined.
2025*a45ae5f8SJohn MarinoThe @option{-E} option indicates that the remaining options should
2026*a45ae5f8SJohn Marinoapply to ``empty'' command completion; that is, completion attempted on a
2027*a45ae5f8SJohn Marinoblank line.
2028*a45ae5f8SJohn Marino
2029*a45ae5f8SJohn MarinoThe @option{-D} option takes precedence over @option{-E}.
2030*a45ae5f8SJohn Marino
2031*a45ae5f8SJohn MarinoThe return value is true unless an invalid option is supplied, an attempt
2032*a45ae5f8SJohn Marinois made to modify the options for a @var{name} for which no completion
2033*a45ae5f8SJohn Marinospecification exists, or an output error occurs.
2034*a45ae5f8SJohn Marino
20355796c8dcSSimon Schubert@end table
2036*a45ae5f8SJohn Marino
20375796c8dcSSimon Schubert@end ifset
2038