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