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