Annotation of embedaddon/readline/doc/rluser.texi, revision 1.1
1.1 ! misho 1: @comment %**start of header (This is for running Texinfo on a region.)
! 2: @setfilename rluser.info
! 3: @comment %**end of header (This is for running Texinfo on a region.)
! 4:
! 5: @ignore
! 6: This file documents the end user interface to the GNU command line
! 7: editing features. It is to be an appendix to manuals for programs which
! 8: use these features. There is a document entitled "readline.texinfo"
! 9: which contains both end-user and programmer documentation for the
! 10: GNU Readline Library.
! 11:
! 12: Copyright (C) 1988--2014 Free Software Foundation, Inc.
! 13:
! 14: Authored by Brian Fox and Chet Ramey.
! 15:
! 16: Permission is granted to process this file through Tex and print the
! 17: results, provided the printed document carries copying permission notice
! 18: identical to this one except for the removal of this paragraph (this
! 19: paragraph not being relevant to the printed manual).
! 20:
! 21: Permission is granted to make and distribute verbatim copies of this manual
! 22: provided the copyright notice and this permission notice are preserved on
! 23: all copies.
! 24:
! 25: Permission is granted to copy and distribute modified versions of this
! 26: manual under the conditions for verbatim copying, provided also that the
! 27: GNU Copyright statement is available to the distributee, and provided that
! 28: the entire resulting derived work is distributed under the terms of a
! 29: permission notice identical to this one.
! 30:
! 31: Permission is granted to copy and distribute translations of this manual
! 32: into another language, under the above conditions for modified versions.
! 33: @end ignore
! 34:
! 35: @comment If you are including this manual as an appendix, then set the
! 36: @comment variable readline-appendix.
! 37:
! 38: @ifclear BashFeatures
! 39: @defcodeindex bt
! 40: @end ifclear
! 41:
! 42: @node Command Line Editing
! 43: @chapter Command Line Editing
! 44:
! 45: This chapter describes the basic features of the @sc{gnu}
! 46: command line editing interface.
! 47: @ifset BashFeatures
! 48: Command line editing is provided by the Readline library, which is
! 49: used by several different programs, including Bash.
! 50: Command line editing is enabled by default when using an interactive shell,
! 51: unless the @option{--noediting} option is supplied at shell invocation.
! 52: Line editing is also used when using the @option{-e} option to the
! 53: @code{read} builtin command (@pxref{Bash Builtins}).
! 54: By default, the line editing commands are similar to those of Emacs.
! 55: A vi-style line editing interface is also available.
! 56: Line editing can be enabled at any time using the @option{-o emacs} or
! 57: @option{-o vi} options to the @code{set} builtin command
! 58: (@pxref{The Set Builtin}), or disabled using the @option{+o emacs} or
! 59: @option{+o vi} options to @code{set}.
! 60: @end ifset
! 61:
! 62: @menu
! 63: * Introduction and Notation:: Notation used in this text.
! 64: * Readline Interaction:: The minimum set of commands for editing a line.
! 65: * Readline Init File:: Customizing Readline from a user's view.
! 66: * Bindable Readline Commands:: A description of most of the Readline commands
! 67: available for binding
! 68: * Readline vi Mode:: A short description of how to make Readline
! 69: behave like the vi editor.
! 70: @ifset BashFeatures
! 71: * Programmable Completion:: How to specify the possible completions for
! 72: a specific command.
! 73: * Programmable Completion Builtins:: Builtin commands to specify how to
! 74: complete arguments for a particular command.
! 75: * A Programmable Completion Example:: An example shell function for
! 76: generating possible completions.
! 77: @end ifset
! 78: @end menu
! 79:
! 80: @node Introduction and Notation
! 81: @section Introduction to Line Editing
! 82:
! 83: The following paragraphs describe the notation used to represent
! 84: keystrokes.
! 85:
! 86: The text @kbd{C-k} is read as `Control-K' and describes the character
! 87: produced when the @key{k} key is pressed while the Control key
! 88: is depressed.
! 89:
! 90: The text @kbd{M-k} is read as `Meta-K' and describes the character
! 91: produced when the Meta key (if you have one) is depressed, and the @key{k}
! 92: key is pressed.
! 93: The Meta key is labeled @key{ALT} on many keyboards.
! 94: On keyboards with two keys labeled @key{ALT} (usually to either side of
! 95: the space bar), the @key{ALT} on the left side is generally set to
! 96: work as a Meta key.
! 97: The @key{ALT} key on the right may also be configured to work as a
! 98: Meta key or may be configured as some other modifier, such as a
! 99: Compose key for typing accented characters.
! 100:
! 101: If you do not have a Meta or @key{ALT} key, or another key working as
! 102: a Meta key, the identical keystroke can be generated by typing @key{ESC}
! 103: @emph{first}, and then typing @key{k}.
! 104: Either process is known as @dfn{metafying} the @key{k} key.
! 105:
! 106: The text @kbd{M-C-k} is read as `Meta-Control-k' and describes the
! 107: character produced by @dfn{metafying} @kbd{C-k}.
! 108:
! 109: In addition, several keys have their own names. Specifically,
! 110: @key{DEL}, @key{ESC}, @key{LFD}, @key{SPC}, @key{RET}, and @key{TAB} all
! 111: stand for themselves when seen in this text, or in an init file
! 112: (@pxref{Readline Init File}).
! 113: If your keyboard lacks a @key{LFD} key, typing @key{C-j} will
! 114: produce the desired character.
! 115: The @key{RET} key may be labeled @key{Return} or @key{Enter} on
! 116: some keyboards.
! 117:
! 118: @node Readline Interaction
! 119: @section Readline Interaction
! 120: @cindex interaction, readline
! 121:
! 122: Often during an interactive session you type in a long line of text,
! 123: only to notice that the first word on the line is misspelled. The
! 124: Readline library gives you a set of commands for manipulating the text
! 125: as you type it in, allowing you to just fix your typo, and not forcing
! 126: you to retype the majority of the line. Using these editing commands,
! 127: you move the cursor to the place that needs correction, and delete or
! 128: insert the text of the corrections. Then, when you are satisfied with
! 129: the line, you simply press @key{RET}. You do not have to be at the
! 130: end of the line to press @key{RET}; the entire line is accepted
! 131: regardless of the location of the cursor within the line.
! 132:
! 133: @menu
! 134: * Readline Bare Essentials:: The least you need to know about Readline.
! 135: * Readline Movement Commands:: Moving about the input line.
! 136: * Readline Killing Commands:: How to delete text, and how to get it back!
! 137: * Readline Arguments:: Giving numeric arguments to commands.
! 138: * Searching:: Searching through previous lines.
! 139: @end menu
! 140:
! 141: @node Readline Bare Essentials
! 142: @subsection Readline Bare Essentials
! 143: @cindex notation, readline
! 144: @cindex command editing
! 145: @cindex editing command lines
! 146:
! 147: In order to enter characters into the line, simply type them. The typed
! 148: character appears where the cursor was, and then the cursor moves one
! 149: space to the right. If you mistype a character, you can use your
! 150: erase character to back up and delete the mistyped character.
! 151:
! 152: Sometimes you may mistype a character, and
! 153: not notice the error until you have typed several other characters. In
! 154: that case, you can type @kbd{C-b} to move the cursor to the left, and then
! 155: correct your mistake. Afterwards, you can move the cursor to the right
! 156: with @kbd{C-f}.
! 157:
! 158: When you add text in the middle of a line, you will notice that characters
! 159: to the right of the cursor are `pushed over' to make room for the text
! 160: that you have inserted. Likewise, when you delete text behind the cursor,
! 161: characters to the right of the cursor are `pulled back' to fill in the
! 162: blank space created by the removal of the text. A list of the bare
! 163: essentials for editing the text of an input line follows.
! 164:
! 165: @table @asis
! 166: @item @kbd{C-b}
! 167: Move back one character.
! 168: @item @kbd{C-f}
! 169: Move forward one character.
! 170: @item @key{DEL} or @key{Backspace}
! 171: Delete the character to the left of the cursor.
! 172: @item @kbd{C-d}
! 173: Delete the character underneath the cursor.
! 174: @item @w{Printing characters}
! 175: Insert the character into the line at the cursor.
! 176: @item @kbd{C-_} or @kbd{C-x C-u}
! 177: Undo the last editing command. You can undo all the way back to an
! 178: empty line.
! 179: @end table
! 180:
! 181: @noindent
! 182: (Depending on your configuration, the @key{Backspace} key be set to
! 183: delete the character to the left of the cursor and the @key{DEL} key set
! 184: to delete the character underneath the cursor, like @kbd{C-d}, rather
! 185: than the character to the left of the cursor.)
! 186:
! 187: @node Readline Movement Commands
! 188: @subsection Readline Movement Commands
! 189:
! 190:
! 191: The above table describes the most basic keystrokes that you need
! 192: in order to do editing of the input line. For your convenience, many
! 193: other commands have been added in addition to @kbd{C-b}, @kbd{C-f},
! 194: @kbd{C-d}, and @key{DEL}. Here are some commands for moving more rapidly
! 195: about the line.
! 196:
! 197: @table @kbd
! 198: @item C-a
! 199: Move to the start of the line.
! 200: @item C-e
! 201: Move to the end of the line.
! 202: @item M-f
! 203: Move forward a word, where a word is composed of letters and digits.
! 204: @item M-b
! 205: Move backward a word.
! 206: @item C-l
! 207: Clear the screen, reprinting the current line at the top.
! 208: @end table
! 209:
! 210: Notice how @kbd{C-f} moves forward a character, while @kbd{M-f} moves
! 211: forward a word. It is a loose convention that control keystrokes
! 212: operate on characters while meta keystrokes operate on words.
! 213:
! 214: @node Readline Killing Commands
! 215: @subsection Readline Killing Commands
! 216:
! 217: @cindex killing text
! 218: @cindex yanking text
! 219:
! 220: @dfn{Killing} text means to delete the text from the line, but to save
! 221: it away for later use, usually by @dfn{yanking} (re-inserting)
! 222: it back into the line.
! 223: (`Cut' and `paste' are more recent jargon for `kill' and `yank'.)
! 224:
! 225: If the description for a command says that it `kills' text, then you can
! 226: be sure that you can get the text back in a different (or the same)
! 227: place later.
! 228:
! 229: When you use a kill command, the text is saved in a @dfn{kill-ring}.
! 230: Any number of consecutive kills save all of the killed text together, so
! 231: that when you yank it back, you get it all. The kill
! 232: ring is not line specific; the text that you killed on a previously
! 233: typed line is available to be yanked back later, when you are typing
! 234: another line.
! 235: @cindex kill ring
! 236:
! 237: Here is the list of commands for killing text.
! 238:
! 239: @table @kbd
! 240: @item C-k
! 241: Kill the text from the current cursor position to the end of the line.
! 242:
! 243: @item M-d
! 244: Kill from the cursor to the end of the current word, or, if between
! 245: words, to the end of the next word.
! 246: Word boundaries are the same as those used by @kbd{M-f}.
! 247:
! 248: @item M-@key{DEL}
! 249: Kill from the cursor the start of the current word, or, if between
! 250: words, to the start of the previous word.
! 251: Word boundaries are the same as those used by @kbd{M-b}.
! 252:
! 253: @item C-w
! 254: Kill from the cursor to the previous whitespace. This is different than
! 255: @kbd{M-@key{DEL}} because the word boundaries differ.
! 256:
! 257: @end table
! 258:
! 259: Here is how to @dfn{yank} the text back into the line. Yanking
! 260: means to copy the most-recently-killed text from the kill buffer.
! 261:
! 262: @table @kbd
! 263: @item C-y
! 264: Yank the most recently killed text back into the buffer at the cursor.
! 265:
! 266: @item M-y
! 267: Rotate the kill-ring, and yank the new top. You can only do this if
! 268: the prior command is @kbd{C-y} or @kbd{M-y}.
! 269: @end table
! 270:
! 271: @node Readline Arguments
! 272: @subsection Readline Arguments
! 273:
! 274: You can pass numeric arguments to Readline commands. Sometimes the
! 275: argument acts as a repeat count, other times it is the @i{sign} of the
! 276: argument that is significant. If you pass a negative argument to a
! 277: command which normally acts in a forward direction, that command will
! 278: act in a backward direction. For example, to kill text back to the
! 279: start of the line, you might type @samp{M-- C-k}.
! 280:
! 281: The general way to pass numeric arguments to a command is to type meta
! 282: digits before the command. If the first `digit' typed is a minus
! 283: sign (@samp{-}), then the sign of the argument will be negative. Once
! 284: you have typed one meta digit to get the argument started, you can type
! 285: the remainder of the digits, and then the command. For example, to give
! 286: the @kbd{C-d} command an argument of 10, you could type @samp{M-1 0 C-d},
! 287: which will delete the next ten characters on the input line.
! 288:
! 289: @node Searching
! 290: @subsection Searching for Commands in the History
! 291:
! 292: Readline provides commands for searching through the command history
! 293: @ifset BashFeatures
! 294: (@pxref{Bash History Facilities})
! 295: @end ifset
! 296: for lines containing a specified string.
! 297: There are two search modes: @dfn{incremental} and @dfn{non-incremental}.
! 298:
! 299: Incremental searches begin before the user has finished typing the
! 300: search string.
! 301: As each character of the search string is typed, Readline displays
! 302: the next entry from the history matching the string typed so far.
! 303: An incremental search requires only as many characters as needed to
! 304: find the desired history entry.
! 305: To search backward in the history for a particular string, type
! 306: @kbd{C-r}. Typing @kbd{C-s} searches forward through the history.
! 307: The characters present in the value of the @code{isearch-terminators} variable
! 308: are used to terminate an incremental search.
! 309: If that variable has not been assigned a value, the @key{ESC} and
! 310: @kbd{C-J} characters will terminate an incremental search.
! 311: @kbd{C-g} will abort an incremental search and restore the original line.
! 312: When the search is terminated, the history entry containing the
! 313: search string becomes the current line.
! 314:
! 315: To find other matching entries in the history list, type @kbd{C-r} or
! 316: @kbd{C-s} as appropriate.
! 317: This will search backward or forward in the history for the next
! 318: entry matching the search string typed so far.
! 319: Any other key sequence bound to a Readline command will terminate
! 320: the search and execute that command.
! 321: For instance, a @key{RET} will terminate the search and accept
! 322: the line, thereby executing the command from the history list.
! 323: A movement command will terminate the search, make the last line found
! 324: the current line, and begin editing.
! 325:
! 326: Readline remembers the last incremental search string. If two
! 327: @kbd{C-r}s are typed without any intervening characters defining a new
! 328: search string, any remembered search string is used.
! 329:
! 330: Non-incremental searches read the entire search string before starting
! 331: to search for matching history lines. The search string may be
! 332: typed by the user or be part of the contents of the current line.
! 333:
! 334: @node Readline Init File
! 335: @section Readline Init File
! 336: @cindex initialization file, readline
! 337:
! 338: Although the Readline library comes with a set of Emacs-like
! 339: keybindings installed by default, it is possible to use a different set
! 340: of keybindings.
! 341: Any user can customize programs that use Readline by putting
! 342: commands in an @dfn{inputrc} file, conventionally in his home directory.
! 343: The name of this
! 344: @ifset BashFeatures
! 345: file is taken from the value of the shell variable @env{INPUTRC}. If
! 346: @end ifset
! 347: @ifclear BashFeatures
! 348: file is taken from the value of the environment variable @env{INPUTRC}. If
! 349: @end ifclear
! 350: that variable is unset, the default is @file{~/.inputrc}. If that
! 351: file does not exist or cannot be read, the ultimate default is
! 352: @file{/etc/inputrc}.
! 353:
! 354: When a program which uses the Readline library starts up, the
! 355: init file is read, and the key bindings are set.
! 356:
! 357: In addition, the @code{C-x C-r} command re-reads this init file, thus
! 358: incorporating any changes that you might have made to it.
! 359:
! 360: @menu
! 361: * Readline Init File Syntax:: Syntax for the commands in the inputrc file.
! 362:
! 363: * Conditional Init Constructs:: Conditional key bindings in the inputrc file.
! 364:
! 365: * Sample Init File:: An example inputrc file.
! 366: @end menu
! 367:
! 368: @node Readline Init File Syntax
! 369: @subsection Readline Init File Syntax
! 370:
! 371: There are only a few basic constructs allowed in the
! 372: Readline init file. Blank lines are ignored.
! 373: Lines beginning with a @samp{#} are comments.
! 374: Lines beginning with a @samp{$} indicate conditional
! 375: constructs (@pxref{Conditional Init Constructs}). Other lines
! 376: denote variable settings and key bindings.
! 377:
! 378: @table @asis
! 379: @item Variable Settings
! 380: You can modify the run-time behavior of Readline by
! 381: altering the values of variables in Readline
! 382: using the @code{set} command within the init file.
! 383: The syntax is simple:
! 384:
! 385: @example
! 386: set @var{variable} @var{value}
! 387: @end example
! 388:
! 389: @noindent
! 390: Here, for example, is how to
! 391: change from the default Emacs-like key binding to use
! 392: @code{vi} line editing commands:
! 393:
! 394: @example
! 395: set editing-mode vi
! 396: @end example
! 397:
! 398: Variable names and values, where appropriate, are recognized without regard
! 399: to case. Unrecognized variable names are ignored.
! 400:
! 401: Boolean variables (those that can be set to on or off) are set to on if
! 402: the value is null or empty, @var{on} (case-insensitive), or 1. Any other
! 403: value results in the variable being set to off.
! 404:
! 405: @ifset BashFeatures
! 406: The @w{@code{bind -V}} command lists the current Readline variable names
! 407: and values. @xref{Bash Builtins}.
! 408: @end ifset
! 409:
! 410: A great deal of run-time behavior is changeable with the following
! 411: variables.
! 412:
! 413: @cindex variables, readline
! 414: @table @code
! 415:
! 416: @item bell-style
! 417: @vindex bell-style
! 418: Controls what happens when Readline wants to ring the terminal bell.
! 419: If set to @samp{none}, Readline never rings the bell. If set to
! 420: @samp{visible}, Readline uses a visible bell if one is available.
! 421: If set to @samp{audible} (the default), Readline attempts to ring
! 422: the terminal's bell.
! 423:
! 424: @item bind-tty-special-chars
! 425: @vindex bind-tty-special-chars
! 426: If set to @samp{on}, Readline attempts to bind the control characters
! 427: treated specially by the kernel's terminal driver to their Readline
! 428: equivalents.
! 429:
! 430: @item colored-stats
! 431: @vindex colored-stats
! 432: If set to @samp{on}, Readline displays possible completions using different
! 433: colors to indicate their file type.
! 434: The color definitions are taken from the value of the @env{LS_COLORS}
! 435: environment variable.
! 436: The default is @samp{off}.
! 437:
! 438: @item comment-begin
! 439: @vindex comment-begin
! 440: The string to insert at the beginning of the line when the
! 441: @code{insert-comment} command is executed. The default value
! 442: is @code{"#"}.
! 443:
! 444: @item completion-display-width
! 445: @vindex completion-display-width
! 446: The number of screen columns used to display possible matches
! 447: when performing completion.
! 448: The value is ignored if it is less than 0 or greater than the terminal
! 449: screen width.
! 450: A value of 0 will cause matches to be displayed one per line.
! 451: The default value is -1.
! 452:
! 453: @item completion-ignore-case
! 454: @vindex completion-ignore-case
! 455: If set to @samp{on}, Readline performs filename matching and completion
! 456: in a case-insensitive fashion.
! 457: The default value is @samp{off}.
! 458:
! 459: @item completion-map-case
! 460: @vindex completion-map-case
! 461: If set to @samp{on}, and @var{completion-ignore-case} is enabled, Readline
! 462: treats hyphens (@samp{-}) and underscores (@samp{_}) as equivalent when
! 463: performing case-insensitive filename matching and completion.
! 464:
! 465: @item completion-prefix-display-length
! 466: @vindex completion-prefix-display-length
! 467: The length in characters of the common prefix of a list of possible
! 468: completions that is displayed without modification. When set to a
! 469: value greater than zero, common prefixes longer than this value are
! 470: replaced with an ellipsis when displaying possible completions.
! 471:
! 472: @item completion-query-items
! 473: @vindex completion-query-items
! 474: The number of possible completions that determines when the user is
! 475: asked whether the list of possibilities should be displayed.
! 476: If the number of possible completions is greater than this value,
! 477: Readline will ask the user whether or not he wishes to view
! 478: them; otherwise, they are simply listed.
! 479: This variable must be set to an integer value greater than or equal to 0.
! 480: A negative value means Readline should never ask.
! 481: The default limit is @code{100}.
! 482:
! 483: @item convert-meta
! 484: @vindex convert-meta
! 485: If set to @samp{on}, Readline will convert characters with the
! 486: eighth bit set to an @sc{ascii} key sequence by stripping the eighth
! 487: bit and prefixing an @key{ESC} character, converting them to a
! 488: meta-prefixed key sequence. The default value is @samp{on}.
! 489:
! 490: @item disable-completion
! 491: @vindex disable-completion
! 492: If set to @samp{On}, Readline will inhibit word completion.
! 493: Completion characters will be inserted into the line as if they had
! 494: been mapped to @code{self-insert}. The default is @samp{off}.
! 495:
! 496: @item editing-mode
! 497: @vindex editing-mode
! 498: The @code{editing-mode} variable controls which default set of
! 499: key bindings is used. By default, Readline starts up in Emacs editing
! 500: mode, where the keystrokes are most similar to Emacs. This variable can be
! 501: set to either @samp{emacs} or @samp{vi}.
! 502:
! 503: @item echo-control-characters
! 504: When set to @samp{on}, on operating systems that indicate they support it,
! 505: readline echoes a character corresponding to a signal generated from the
! 506: keyboard. The default is @samp{on}.
! 507:
! 508: @item enable-keypad
! 509: @vindex enable-keypad
! 510: When set to @samp{on}, Readline will try to enable the application
! 511: keypad when it is called. Some systems need this to enable the
! 512: arrow keys. The default is @samp{off}.
! 513:
! 514: @item enable-meta-key
! 515: When set to @samp{on}, Readline will try to enable any meta modifier
! 516: key the terminal claims to support when it is called. On many terminals,
! 517: the meta key is used to send eight-bit characters.
! 518: The default is @samp{on}.
! 519:
! 520: @item expand-tilde
! 521: @vindex expand-tilde
! 522: If set to @samp{on}, tilde expansion is performed when Readline
! 523: attempts word completion. The default is @samp{off}.
! 524:
! 525: @item history-preserve-point
! 526: @vindex history-preserve-point
! 527: If set to @samp{on}, the history code attempts to place the point (the
! 528: current cursor position) at the
! 529: same location on each history line retrieved with @code{previous-history}
! 530: or @code{next-history}. The default is @samp{off}.
! 531:
! 532: @item history-size
! 533: @vindex history-size
! 534: Set the maximum number of history entries saved in the history list.
! 535: If set to zero, any existing history entries are deleted and no new entries
! 536: are saved.
! 537: If set to a value less than zero, the number of history entries is not
! 538: limited.
! 539: By default, the number of history entries is not limited.
! 540:
! 541: @item horizontal-scroll-mode
! 542: @vindex horizontal-scroll-mode
! 543: This variable can be set to either @samp{on} or @samp{off}. Setting it
! 544: to @samp{on} means that the text of the lines being edited will scroll
! 545: horizontally on a single screen line when they are longer than the width
! 546: of the screen, instead of wrapping onto a new screen line. By default,
! 547: this variable is set to @samp{off}.
! 548:
! 549: @item input-meta
! 550: @vindex input-meta
! 551: @vindex meta-flag
! 552: If set to @samp{on}, Readline will enable eight-bit input (it
! 553: will not clear the eighth bit in the characters it reads),
! 554: regardless of what the terminal claims it can support. The
! 555: default value is @samp{off}. The name @code{meta-flag} is a
! 556: synonym for this variable.
! 557:
! 558: @item isearch-terminators
! 559: @vindex isearch-terminators
! 560: The string of characters that should terminate an incremental search without
! 561: subsequently executing the character as a command (@pxref{Searching}).
! 562: If this variable has not been given a value, the characters @key{ESC} and
! 563: @kbd{C-J} will terminate an incremental search.
! 564:
! 565: @item keymap
! 566: @vindex keymap
! 567: Sets Readline's idea of the current keymap for key binding commands.
! 568: Acceptable @code{keymap} names are
! 569: @code{emacs},
! 570: @code{emacs-standard},
! 571: @code{emacs-meta},
! 572: @code{emacs-ctlx},
! 573: @code{vi},
! 574: @code{vi-move},
! 575: @code{vi-command}, and
! 576: @code{vi-insert}.
! 577: @code{vi} is equivalent to @code{vi-command}; @code{emacs} is
! 578: equivalent to @code{emacs-standard}. The default value is @code{emacs}.
! 579: The value of the @code{editing-mode} variable also affects the
! 580: default keymap.
! 581:
! 582: @item keyseq-timeout
! 583: Specifies the duration Readline will wait for a character when reading an
! 584: ambiguous key sequence (one that can form a complete key sequence using
! 585: the input read so far, or can take additional input to complete a longer
! 586: key sequence).
! 587: If no input is received within the timeout, Readline will use the shorter
! 588: but complete key sequence.
! 589: Readline uses this value to determine whether or not input is
! 590: available on the current input source (@code{rl_instream} by default).
! 591: The value is specified in milliseconds, so a value of 1000 means that
! 592: Readline will wait one second for additional input.
! 593: If this variable is set to a value less than or equal to zero, or to a
! 594: non-numeric value, Readline will wait until another key is pressed to
! 595: decide which key sequence to complete.
! 596: The default value is @code{500}.
! 597:
! 598: @item mark-directories
! 599: If set to @samp{on}, completed directory names have a slash
! 600: appended. The default is @samp{on}.
! 601:
! 602: @item mark-modified-lines
! 603: @vindex mark-modified-lines
! 604: This variable, when set to @samp{on}, causes Readline to display an
! 605: asterisk (@samp{*}) at the start of history lines which have been modified.
! 606: This variable is @samp{off} by default.
! 607:
! 608: @item mark-symlinked-directories
! 609: @vindex mark-symlinked-directories
! 610: If set to @samp{on}, completed names which are symbolic links
! 611: to directories have a slash appended (subject to the value of
! 612: @code{mark-directories}).
! 613: The default is @samp{off}.
! 614:
! 615: @item match-hidden-files
! 616: @vindex match-hidden-files
! 617: This variable, when set to @samp{on}, causes Readline to match files whose
! 618: names begin with a @samp{.} (hidden files) when performing filename
! 619: completion.
! 620: If set to @samp{off}, the leading @samp{.} must be
! 621: supplied by the user in the filename to be completed.
! 622: This variable is @samp{on} by default.
! 623:
! 624: @item menu-complete-display-prefix
! 625: @vindex menu-complete-display-prefix
! 626: If set to @samp{on}, menu completion displays the common prefix of the
! 627: list of possible completions (which may be empty) before cycling through
! 628: the list. The default is @samp{off}.
! 629:
! 630: @item output-meta
! 631: @vindex output-meta
! 632: If set to @samp{on}, Readline will display characters with the
! 633: eighth bit set directly rather than as a meta-prefixed escape
! 634: sequence. The default is @samp{off}.
! 635:
! 636: @item page-completions
! 637: @vindex page-completions
! 638: If set to @samp{on}, Readline uses an internal @code{more}-like pager
! 639: to display a screenful of possible completions at a time.
! 640: This variable is @samp{on} by default.
! 641:
! 642: @item print-completions-horizontally
! 643: If set to @samp{on}, Readline will display completions with matches
! 644: sorted horizontally in alphabetical order, rather than down the screen.
! 645: The default is @samp{off}.
! 646:
! 647: @item revert-all-at-newline
! 648: @vindex revert-all-at-newline
! 649: If set to @samp{on}, Readline will undo all changes to history lines
! 650: before returning when @code{accept-line} is executed. By default,
! 651: history lines may be modified and retain individual undo lists across
! 652: calls to @code{readline}. The default is @samp{off}.
! 653:
! 654: @item show-all-if-ambiguous
! 655: @vindex show-all-if-ambiguous
! 656: This alters the default behavior of the completion functions. If
! 657: set to @samp{on},
! 658: words which have more than one possible completion cause the
! 659: matches to be listed immediately instead of ringing the bell.
! 660: The default value is @samp{off}.
! 661:
! 662: @item show-all-if-unmodified
! 663: @vindex show-all-if-unmodified
! 664: This alters the default behavior of the completion functions in
! 665: a fashion similar to @var{show-all-if-ambiguous}.
! 666: If set to @samp{on},
! 667: words which have more than one possible completion without any
! 668: possible partial completion (the possible completions don't share
! 669: a common prefix) cause the matches to be listed immediately instead
! 670: of ringing the bell.
! 671: The default value is @samp{off}.
! 672:
! 673: @item show-mode-in-prompt
! 674: @vindex show-mode-in-prompt
! 675: If set to @samp{on}, add a character to the beginning of the prompt
! 676: indicating the editing mode: emacs (@samp{@@}), vi command (@samp{:}),
! 677: or vi insertion (@samp{+}).
! 678: The default value is @samp{off}.
! 679:
! 680: @item skip-completed-text
! 681: @vindex skip-completed-text
! 682: If set to @samp{on}, this alters the default completion behavior when
! 683: inserting a single match into the line. It's only active when
! 684: performing completion in the middle of a word. If enabled, readline
! 685: does not insert characters from the completion that match characters
! 686: after point in the word being completed, so portions of the word
! 687: following the cursor are not duplicated.
! 688: For instance, if this is enabled, attempting completion when the cursor
! 689: is after the @samp{e} in @samp{Makefile} will result in @samp{Makefile}
! 690: rather than @samp{Makefilefile}, assuming there is a single possible
! 691: completion.
! 692: The default value is @samp{off}.
! 693:
! 694: @item visible-stats
! 695: @vindex visible-stats
! 696: If set to @samp{on}, a character denoting a file's type
! 697: is appended to the filename when listing possible
! 698: completions. The default is @samp{off}.
! 699:
! 700: @end table
! 701:
! 702: @item Key Bindings
! 703: The syntax for controlling key bindings in the init file is
! 704: simple. First you need to find the name of the command that you
! 705: want to change. The following sections contain tables of the command
! 706: name, the default keybinding, if any, and a short description of what
! 707: the command does.
! 708:
! 709: Once you know the name of the command, simply place on a line
! 710: in the init file the name of the key
! 711: you wish to bind the command to, a colon, and then the name of the
! 712: command.
! 713: There can be no space between the key name and the colon -- that will be
! 714: interpreted as part of the key name.
! 715: The name of the key can be expressed in different ways, depending on
! 716: what you find most comfortable.
! 717:
! 718: In addition to command names, readline allows keys to be bound
! 719: to a string that is inserted when the key is pressed (a @var{macro}).
! 720:
! 721: @ifset BashFeatures
! 722: The @w{@code{bind -p}} command displays Readline function names and
! 723: bindings in a format that can put directly into an initialization file.
! 724: @xref{Bash Builtins}.
! 725: @end ifset
! 726:
! 727: @table @asis
! 728: @item @w{@var{keyname}: @var{function-name} or @var{macro}}
! 729: @var{keyname} is the name of a key spelled out in English. For example:
! 730: @example
! 731: Control-u: universal-argument
! 732: Meta-Rubout: backward-kill-word
! 733: Control-o: "> output"
! 734: @end example
! 735:
! 736: In the above example, @kbd{C-u} is bound to the function
! 737: @code{universal-argument},
! 738: @kbd{M-DEL} is bound to the function @code{backward-kill-word}, and
! 739: @kbd{C-o} is bound to run the macro
! 740: expressed on the right hand side (that is, to insert the text
! 741: @samp{> output} into the line).
! 742:
! 743: A number of symbolic character names are recognized while
! 744: processing this key binding syntax:
! 745: @var{DEL},
! 746: @var{ESC},
! 747: @var{ESCAPE},
! 748: @var{LFD},
! 749: @var{NEWLINE},
! 750: @var{RET},
! 751: @var{RETURN},
! 752: @var{RUBOUT},
! 753: @var{SPACE},
! 754: @var{SPC},
! 755: and
! 756: @var{TAB}.
! 757:
! 758: @item @w{"@var{keyseq}": @var{function-name} or @var{macro}}
! 759: @var{keyseq} differs from @var{keyname} above in that strings
! 760: denoting an entire key sequence can be specified, by placing
! 761: the key sequence in double quotes. Some @sc{gnu} Emacs style key
! 762: escapes can be used, as in the following example, but the
! 763: special character names are not recognized.
! 764:
! 765: @example
! 766: "\C-u": universal-argument
! 767: "\C-x\C-r": re-read-init-file
! 768: "\e[11~": "Function Key 1"
! 769: @end example
! 770:
! 771: In the above example, @kbd{C-u} is again bound to the function
! 772: @code{universal-argument} (just as it was in the first example),
! 773: @samp{@kbd{C-x} @kbd{C-r}} is bound to the function @code{re-read-init-file},
! 774: and @samp{@key{ESC} @key{[} @key{1} @key{1} @key{~}} is bound to insert
! 775: the text @samp{Function Key 1}.
! 776:
! 777: @end table
! 778:
! 779: The following @sc{gnu} Emacs style escape sequences are available when
! 780: specifying key sequences:
! 781:
! 782: @table @code
! 783: @item @kbd{\C-}
! 784: control prefix
! 785: @item @kbd{\M-}
! 786: meta prefix
! 787: @item @kbd{\e}
! 788: an escape character
! 789: @item @kbd{\\}
! 790: backslash
! 791: @item @kbd{\"}
! 792: @key{"}, a double quotation mark
! 793: @item @kbd{\'}
! 794: @key{'}, a single quote or apostrophe
! 795: @end table
! 796:
! 797: In addition to the @sc{gnu} Emacs style escape sequences, a second
! 798: set of backslash escapes is available:
! 799:
! 800: @table @code
! 801: @item \a
! 802: alert (bell)
! 803: @item \b
! 804: backspace
! 805: @item \d
! 806: delete
! 807: @item \f
! 808: form feed
! 809: @item \n
! 810: newline
! 811: @item \r
! 812: carriage return
! 813: @item \t
! 814: horizontal tab
! 815: @item \v
! 816: vertical tab
! 817: @item \@var{nnn}
! 818: the eight-bit character whose value is the octal value @var{nnn}
! 819: (one to three digits)
! 820: @item \x@var{HH}
! 821: the eight-bit character whose value is the hexadecimal value @var{HH}
! 822: (one or two hex digits)
! 823: @end table
! 824:
! 825: When entering the text of a macro, single or double quotes must
! 826: be used to indicate a macro definition.
! 827: Unquoted text is assumed to be a function name.
! 828: In the macro body, the backslash escapes described above are expanded.
! 829: Backslash will quote any other character in the macro text,
! 830: including @samp{"} and @samp{'}.
! 831: For example, the following binding will make @samp{@kbd{C-x} \}
! 832: insert a single @samp{\} into the line:
! 833: @example
! 834: "\C-x\\": "\\"
! 835: @end example
! 836:
! 837: @end table
! 838:
! 839: @node Conditional Init Constructs
! 840: @subsection Conditional Init Constructs
! 841:
! 842: Readline implements a facility similar in spirit to the conditional
! 843: compilation features of the C preprocessor which allows key
! 844: bindings and variable settings to be performed as the result
! 845: of tests. There are four parser directives used.
! 846:
! 847: @table @code
! 848: @item $if
! 849: The @code{$if} construct allows bindings to be made based on the
! 850: editing mode, the terminal being used, or the application using
! 851: Readline. The text of the test extends to the end of the line;
! 852: no characters are required to isolate it.
! 853:
! 854: @table @code
! 855: @item mode
! 856: The @code{mode=} form of the @code{$if} directive is used to test
! 857: whether Readline is in @code{emacs} or @code{vi} mode.
! 858: This may be used in conjunction
! 859: with the @samp{set keymap} command, for instance, to set bindings in
! 860: the @code{emacs-standard} and @code{emacs-ctlx} keymaps only if
! 861: Readline is starting out in @code{emacs} mode.
! 862:
! 863: @item term
! 864: The @code{term=} form may be used to include terminal-specific
! 865: key bindings, perhaps to bind the key sequences output by the
! 866: terminal's function keys. The word on the right side of the
! 867: @samp{=} is tested against both the full name of the terminal and
! 868: the portion of the terminal name before the first @samp{-}. This
! 869: allows @code{sun} to match both @code{sun} and @code{sun-cmd},
! 870: for instance.
! 871:
! 872: @item application
! 873: The @var{application} construct is used to include
! 874: application-specific settings. Each program using the Readline
! 875: library sets the @var{application name}, and you can test for
! 876: a particular value.
! 877: This could be used to bind key sequences to functions useful for
! 878: a specific program. For instance, the following command adds a
! 879: key sequence that quotes the current or previous word in Bash:
! 880: @example
! 881: $if Bash
! 882: # Quote the current or previous word
! 883: "\C-xq": "\eb\"\ef\""
! 884: $endif
! 885: @end example
! 886: @end table
! 887:
! 888: @item $endif
! 889: This command, as seen in the previous example, terminates an
! 890: @code{$if} command.
! 891:
! 892: @item $else
! 893: Commands in this branch of the @code{$if} directive are executed if
! 894: the test fails.
! 895:
! 896: @item $include
! 897: This directive takes a single filename as an argument and reads commands
! 898: and bindings from that file.
! 899: For example, the following directive reads from @file{/etc/inputrc}:
! 900: @example
! 901: $include /etc/inputrc
! 902: @end example
! 903: @end table
! 904:
! 905: @node Sample Init File
! 906: @subsection Sample Init File
! 907:
! 908: Here is an example of an @var{inputrc} file. This illustrates key
! 909: binding, variable assignment, and conditional syntax.
! 910:
! 911: @example
! 912: @page
! 913: # This file controls the behaviour of line input editing for
! 914: # programs that use the GNU Readline library. Existing
! 915: # programs include FTP, Bash, and GDB.
! 916: #
! 917: # You can re-read the inputrc file with C-x C-r.
! 918: # Lines beginning with '#' are comments.
! 919: #
! 920: # First, include any system-wide bindings and variable
! 921: # assignments from /etc/Inputrc
! 922: $include /etc/Inputrc
! 923:
! 924: #
! 925: # Set various bindings for emacs mode.
! 926:
! 927: set editing-mode emacs
! 928:
! 929: $if mode=emacs
! 930:
! 931: Meta-Control-h: backward-kill-word Text after the function name is ignored
! 932:
! 933: #
! 934: # Arrow keys in keypad mode
! 935: #
! 936: #"\M-OD": backward-char
! 937: #"\M-OC": forward-char
! 938: #"\M-OA": previous-history
! 939: #"\M-OB": next-history
! 940: #
! 941: # Arrow keys in ANSI mode
! 942: #
! 943: "\M-[D": backward-char
! 944: "\M-[C": forward-char
! 945: "\M-[A": previous-history
! 946: "\M-[B": next-history
! 947: #
! 948: # Arrow keys in 8 bit keypad mode
! 949: #
! 950: #"\M-\C-OD": backward-char
! 951: #"\M-\C-OC": forward-char
! 952: #"\M-\C-OA": previous-history
! 953: #"\M-\C-OB": next-history
! 954: #
! 955: # Arrow keys in 8 bit ANSI mode
! 956: #
! 957: #"\M-\C-[D": backward-char
! 958: #"\M-\C-[C": forward-char
! 959: #"\M-\C-[A": previous-history
! 960: #"\M-\C-[B": next-history
! 961:
! 962: C-q: quoted-insert
! 963:
! 964: $endif
! 965:
! 966: # An old-style binding. This happens to be the default.
! 967: TAB: complete
! 968:
! 969: # Macros that are convenient for shell interaction
! 970: $if Bash
! 971: # edit the path
! 972: "\C-xp": "PATH=$@{PATH@}\e\C-e\C-a\ef\C-f"
! 973: # prepare to type a quoted word --
! 974: # insert open and close double quotes
! 975: # and move to just after the open quote
! 976: "\C-x\"": "\"\"\C-b"
! 977: # insert a backslash (testing backslash escapes
! 978: # in sequences and macros)
! 979: "\C-x\\": "\\"
! 980: # Quote the current or previous word
! 981: "\C-xq": "\eb\"\ef\""
! 982: # Add a binding to refresh the line, which is unbound
! 983: "\C-xr": redraw-current-line
! 984: # Edit variable on current line.
! 985: "\M-\C-v": "\C-a\C-k$\C-y\M-\C-e\C-a\C-y="
! 986: $endif
! 987:
! 988: # use a visible bell if one is available
! 989: set bell-style visible
! 990:
! 991: # don't strip characters to 7 bits when reading
! 992: set input-meta on
! 993:
! 994: # allow iso-latin1 characters to be inserted rather
! 995: # than converted to prefix-meta sequences
! 996: set convert-meta off
! 997:
! 998: # display characters with the eighth bit set directly
! 999: # rather than as meta-prefixed characters
! 1000: set output-meta on
! 1001:
! 1002: # if there are more than 150 possible completions for
! 1003: # a word, ask the user if he wants to see all of them
! 1004: set completion-query-items 150
! 1005:
! 1006: # For FTP
! 1007: $if Ftp
! 1008: "\C-xg": "get \M-?"
! 1009: "\C-xt": "put \M-?"
! 1010: "\M-.": yank-last-arg
! 1011: $endif
! 1012: @end example
! 1013:
! 1014: @node Bindable Readline Commands
! 1015: @section Bindable Readline Commands
! 1016:
! 1017: @menu
! 1018: * Commands For Moving:: Moving about the line.
! 1019: * Commands For History:: Getting at previous lines.
! 1020: * Commands For Text:: Commands for changing text.
! 1021: * Commands For Killing:: Commands for killing and yanking.
! 1022: * Numeric Arguments:: Specifying numeric arguments, repeat counts.
! 1023: * Commands For Completion:: Getting Readline to do the typing for you.
! 1024: * Keyboard Macros:: Saving and re-executing typed characters
! 1025: * Miscellaneous Commands:: Other miscellaneous commands.
! 1026: @end menu
! 1027:
! 1028: This section describes Readline commands that may be bound to key
! 1029: sequences.
! 1030: @ifset BashFeatures
! 1031: You can list your key bindings by executing
! 1032: @w{@code{bind -P}} or, for a more terse format, suitable for an
! 1033: @var{inputrc} file, @w{@code{bind -p}}. (@xref{Bash Builtins}.)
! 1034: @end ifset
! 1035: Command names without an accompanying key sequence are unbound by default.
! 1036:
! 1037: In the following descriptions, @dfn{point} refers to the current cursor
! 1038: position, and @dfn{mark} refers to a cursor position saved by the
! 1039: @code{set-mark} command.
! 1040: The text between the point and mark is referred to as the @dfn{region}.
! 1041:
! 1042: @node Commands For Moving
! 1043: @subsection Commands For Moving
! 1044: @ftable @code
! 1045: @item beginning-of-line (C-a)
! 1046: Move to the start of the current line.
! 1047:
! 1048: @item end-of-line (C-e)
! 1049: Move to the end of the line.
! 1050:
! 1051: @item forward-char (C-f)
! 1052: Move forward a character.
! 1053:
! 1054: @item backward-char (C-b)
! 1055: Move back a character.
! 1056:
! 1057: @item forward-word (M-f)
! 1058: Move forward to the end of the next word.
! 1059: Words are composed of letters and digits.
! 1060:
! 1061: @item backward-word (M-b)
! 1062: Move back to the start of the current or previous word.
! 1063: Words are composed of letters and digits.
! 1064:
! 1065: @ifset BashFeatures
! 1066: @item shell-forward-word ()
! 1067: Move forward to the end of the next word.
! 1068: Words are delimited by non-quoted shell metacharacters.
! 1069:
! 1070: @item shell-backward-word ()
! 1071: Move back to the start of the current or previous word.
! 1072: Words are delimited by non-quoted shell metacharacters.
! 1073: @end ifset
! 1074:
! 1075: @item clear-screen (C-l)
! 1076: Clear the screen and redraw the current line,
! 1077: leaving the current line at the top of the screen.
! 1078:
! 1079: @item redraw-current-line ()
! 1080: Refresh the current line. By default, this is unbound.
! 1081:
! 1082: @end ftable
! 1083:
! 1084: @node Commands For History
! 1085: @subsection Commands For Manipulating The History
! 1086:
! 1087: @ftable @code
! 1088: @item accept-line (Newline or Return)
! 1089: @ifset BashFeatures
! 1090: Accept the line regardless of where the cursor is.
! 1091: If this line is
! 1092: non-empty, add it to the history list according to the setting of
! 1093: the @env{HISTCONTROL} and @env{HISTIGNORE} variables.
! 1094: If this line is a modified history line, then restore the history line
! 1095: to its original state.
! 1096: @end ifset
! 1097: @ifclear BashFeatures
! 1098: Accept the line regardless of where the cursor is.
! 1099: If this line is
! 1100: non-empty, it may be added to the history list for future recall with
! 1101: @code{add_history()}.
! 1102: If this line is a modified history line, the history line is restored
! 1103: to its original state.
! 1104: @end ifclear
! 1105:
! 1106: @item previous-history (C-p)
! 1107: Move `back' through the history list, fetching the previous command.
! 1108:
! 1109: @item next-history (C-n)
! 1110: Move `forward' through the history list, fetching the next command.
! 1111:
! 1112: @item beginning-of-history (M-<)
! 1113: Move to the first line in the history.
! 1114:
! 1115: @item end-of-history (M->)
! 1116: Move to the end of the input history, i.e., the line currently
! 1117: being entered.
! 1118:
! 1119: @item reverse-search-history (C-r)
! 1120: Search backward starting at the current line and moving `up' through
! 1121: the history as necessary. This is an incremental search.
! 1122:
! 1123: @item forward-search-history (C-s)
! 1124: Search forward starting at the current line and moving `down' through
! 1125: the the history as necessary. This is an incremental search.
! 1126:
! 1127: @item non-incremental-reverse-search-history (M-p)
! 1128: Search backward starting at the current line and moving `up'
! 1129: through the history as necessary using a non-incremental search
! 1130: for a string supplied by the user.
! 1131:
! 1132: @item non-incremental-forward-search-history (M-n)
! 1133: Search forward starting at the current line and moving `down'
! 1134: through the the history as necessary using a non-incremental search
! 1135: for a string supplied by the user.
! 1136:
! 1137: @item history-search-forward ()
! 1138: Search forward through the history for the string of characters
! 1139: between the start of the current line and the point.
! 1140: The search string must match at the beginning of a history line.
! 1141: This is a non-incremental search.
! 1142: By default, this command is unbound.
! 1143:
! 1144: @item history-search-backward ()
! 1145: Search backward through the history for the string of characters
! 1146: between the start of the current line and the point.
! 1147: The search string must match at the beginning of a history line.
! 1148: This is a non-incremental search.
! 1149: By default, this command is unbound.
! 1150:
! 1151: @item history-substr-search-forward ()
! 1152: Search forward through the history for the string of characters
! 1153: between the start of the current line and the point.
! 1154: The search string may match anywhere in a history line.
! 1155: This is a non-incremental search.
! 1156: By default, this command is unbound.
! 1157:
! 1158: @item history-substr-search-backward ()
! 1159: Search backward through the history for the string of characters
! 1160: between the start of the current line and the point.
! 1161: The search string may match anywhere in a history line.
! 1162: This is a non-incremental search.
! 1163: By default, this command is unbound.
! 1164:
! 1165: @item yank-nth-arg (M-C-y)
! 1166: Insert the first argument to the previous command (usually
! 1167: the second word on the previous line) at point.
! 1168: With an argument @var{n},
! 1169: insert the @var{n}th word from the previous command (the words
! 1170: in the previous command begin with word 0). A negative argument
! 1171: inserts the @var{n}th word from the end of the previous command.
! 1172: Once the argument @var{n} is computed, the argument is extracted
! 1173: as if the @samp{!@var{n}} history expansion had been specified.
! 1174:
! 1175: @item yank-last-arg (M-. or M-_)
! 1176: Insert last argument to the previous command (the last word of the
! 1177: previous history entry).
! 1178: With a numeric argument, behave exactly like @code{yank-nth-arg}.
! 1179: Successive calls to @code{yank-last-arg} move back through the history
! 1180: list, inserting the last word (or the word specified by the argument to
! 1181: the first call) of each line in turn.
! 1182: Any numeric argument supplied to these successive calls determines
! 1183: the direction to move through the history. A negative argument switches
! 1184: the direction through the history (back or forward).
! 1185: The history expansion facilities are used to extract the last argument,
! 1186: as if the @samp{!$} history expansion had been specified.
! 1187:
! 1188: @end ftable
! 1189:
! 1190: @node Commands For Text
! 1191: @subsection Commands For Changing Text
! 1192:
! 1193: @ftable @code
! 1194:
! 1195: @item @i{end-of-file} (usually C-d)
! 1196: The character indicating end-of-file as set, for example, by
! 1197: @code{stty}. If this character is read when there are no characters
! 1198: on the line, and point is at the beginning of the line, Readline
! 1199: interprets it as the end of input and returns @sc{eof}.
! 1200:
! 1201: @item delete-char (C-d)
! 1202: Delete the character at point. If this function is bound to the
! 1203: same character as the tty @sc{eof} character, as @kbd{C-d}
! 1204: commonly is, see above for the effects.
! 1205:
! 1206: @item backward-delete-char (Rubout)
! 1207: Delete the character behind the cursor. A numeric argument means
! 1208: to kill the characters instead of deleting them.
! 1209:
! 1210: @item forward-backward-delete-char ()
! 1211: Delete the character under the cursor, unless the cursor is at the
! 1212: end of the line, in which case the character behind the cursor is
! 1213: deleted. By default, this is not bound to a key.
! 1214:
! 1215: @item quoted-insert (C-q or C-v)
! 1216: Add the next character typed to the line verbatim. This is
! 1217: how to insert key sequences like @kbd{C-q}, for example.
! 1218:
! 1219: @ifclear BashFeatures
! 1220: @item tab-insert (M-@key{TAB})
! 1221: Insert a tab character.
! 1222: @end ifclear
! 1223:
! 1224: @item self-insert (a, b, A, 1, !, @dots{})
! 1225: Insert yourself.
! 1226:
! 1227: @item transpose-chars (C-t)
! 1228: Drag the character before the cursor forward over
! 1229: the character at the cursor, moving the
! 1230: cursor forward as well. If the insertion point
! 1231: is at the end of the line, then this
! 1232: transposes the last two characters of the line.
! 1233: Negative arguments have no effect.
! 1234:
! 1235: @item transpose-words (M-t)
! 1236: Drag the word before point past the word after point,
! 1237: moving point past that word as well.
! 1238: If the insertion point is at the end of the line, this transposes
! 1239: the last two words on the line.
! 1240:
! 1241: @item upcase-word (M-u)
! 1242: Uppercase the current (or following) word. With a negative argument,
! 1243: uppercase the previous word, but do not move the cursor.
! 1244:
! 1245: @item downcase-word (M-l)
! 1246: Lowercase the current (or following) word. With a negative argument,
! 1247: lowercase the previous word, but do not move the cursor.
! 1248:
! 1249: @item capitalize-word (M-c)
! 1250: Capitalize the current (or following) word. With a negative argument,
! 1251: capitalize the previous word, but do not move the cursor.
! 1252:
! 1253: @item overwrite-mode ()
! 1254: Toggle overwrite mode. With an explicit positive numeric argument,
! 1255: switches to overwrite mode. With an explicit non-positive numeric
! 1256: argument, switches to insert mode. This command affects only
! 1257: @code{emacs} mode; @code{vi} mode does overwrite differently.
! 1258: Each call to @code{readline()} starts in insert mode.
! 1259:
! 1260: In overwrite mode, characters bound to @code{self-insert} replace
! 1261: the text at point rather than pushing the text to the right.
! 1262: Characters bound to @code{backward-delete-char} replace the character
! 1263: before point with a space.
! 1264:
! 1265: By default, this command is unbound.
! 1266:
! 1267: @end ftable
! 1268:
! 1269: @node Commands For Killing
! 1270: @subsection Killing And Yanking
! 1271:
! 1272: @ftable @code
! 1273:
! 1274: @item kill-line (C-k)
! 1275: Kill the text from point to the end of the line.
! 1276:
! 1277: @item backward-kill-line (C-x Rubout)
! 1278: Kill backward to the beginning of the line.
! 1279:
! 1280: @item unix-line-discard (C-u)
! 1281: Kill backward from the cursor to the beginning of the current line.
! 1282:
! 1283: @item kill-whole-line ()
! 1284: Kill all characters on the current line, no matter where point is.
! 1285: By default, this is unbound.
! 1286:
! 1287: @item kill-word (M-d)
! 1288: Kill from point to the end of the current word, or if between
! 1289: words, to the end of the next word.
! 1290: Word boundaries are the same as @code{forward-word}.
! 1291:
! 1292: @item backward-kill-word (M-@key{DEL})
! 1293: Kill the word behind point.
! 1294: Word boundaries are the same as @code{backward-word}.
! 1295:
! 1296: @ifset BashFeatures
! 1297: @item shell-kill-word ()
! 1298: Kill from point to the end of the current word, or if between
! 1299: words, to the end of the next word.
! 1300: Word boundaries are the same as @code{shell-forward-word}.
! 1301:
! 1302: @item shell-backward-kill-word ()
! 1303: Kill the word behind point.
! 1304: Word boundaries are the same as @code{shell-backward-word}.
! 1305: @end ifset
! 1306:
! 1307: @item unix-word-rubout (C-w)
! 1308: Kill the word behind point, using white space as a word boundary.
! 1309: The killed text is saved on the kill-ring.
! 1310:
! 1311: @item unix-filename-rubout ()
! 1312: Kill the word behind point, using white space and the slash character
! 1313: as the word boundaries.
! 1314: The killed text is saved on the kill-ring.
! 1315:
! 1316: @item delete-horizontal-space ()
! 1317: Delete all spaces and tabs around point. By default, this is unbound.
! 1318:
! 1319: @item kill-region ()
! 1320: Kill the text in the current region.
! 1321: By default, this command is unbound.
! 1322:
! 1323: @item copy-region-as-kill ()
! 1324: Copy the text in the region to the kill buffer, so it can be yanked
! 1325: right away. By default, this command is unbound.
! 1326:
! 1327: @item copy-backward-word ()
! 1328: Copy the word before point to the kill buffer.
! 1329: The word boundaries are the same as @code{backward-word}.
! 1330: By default, this command is unbound.
! 1331:
! 1332: @item copy-forward-word ()
! 1333: Copy the word following point to the kill buffer.
! 1334: The word boundaries are the same as @code{forward-word}.
! 1335: By default, this command is unbound.
! 1336:
! 1337: @item yank (C-y)
! 1338: Yank the top of the kill ring into the buffer at point.
! 1339:
! 1340: @item yank-pop (M-y)
! 1341: Rotate the kill-ring, and yank the new top. You can only do this if
! 1342: the prior command is @code{yank} or @code{yank-pop}.
! 1343: @end ftable
! 1344:
! 1345: @node Numeric Arguments
! 1346: @subsection Specifying Numeric Arguments
! 1347: @ftable @code
! 1348:
! 1349: @item digit-argument (@kbd{M-0}, @kbd{M-1}, @dots{} @kbd{M--})
! 1350: Add this digit to the argument already accumulating, or start a new
! 1351: argument. @kbd{M--} starts a negative argument.
! 1352:
! 1353: @item universal-argument ()
! 1354: This is another way to specify an argument.
! 1355: If this command is followed by one or more digits, optionally with a
! 1356: leading minus sign, those digits define the argument.
! 1357: If the command is followed by digits, executing @code{universal-argument}
! 1358: again ends the numeric argument, but is otherwise ignored.
! 1359: As a special case, if this command is immediately followed by a
! 1360: character that is neither a digit or minus sign, the argument count
! 1361: for the next command is multiplied by four.
! 1362: The argument count is initially one, so executing this function the
! 1363: first time makes the argument count four, a second time makes the
! 1364: argument count sixteen, and so on.
! 1365: By default, this is not bound to a key.
! 1366: @end ftable
! 1367:
! 1368: @node Commands For Completion
! 1369: @subsection Letting Readline Type For You
! 1370:
! 1371: @ftable @code
! 1372: @item complete (@key{TAB})
! 1373: Attempt to perform completion on the text before point.
! 1374: The actual completion performed is application-specific.
! 1375: @ifset BashFeatures
! 1376: Bash attempts completion treating the text as a variable (if the
! 1377: text begins with @samp{$}), username (if the text begins with
! 1378: @samp{~}), hostname (if the text begins with @samp{@@}), or
! 1379: command (including aliases and functions) in turn. If none
! 1380: of these produces a match, filename completion is attempted.
! 1381: @end ifset
! 1382: @ifclear BashFeatures
! 1383: The default is filename completion.
! 1384: @end ifclear
! 1385:
! 1386: @item possible-completions (M-?)
! 1387: List the possible completions of the text before point.
! 1388: When displaying completions, Readline sets the number of columns used
! 1389: for display to the value of @code{completion-display-width}, the value of
! 1390: the environment variable @env{COLUMNS}, or the screen width, in that order.
! 1391:
! 1392: @item insert-completions (M-*)
! 1393: Insert all completions of the text before point that would have
! 1394: been generated by @code{possible-completions}.
! 1395:
! 1396: @item menu-complete ()
! 1397: Similar to @code{complete}, but replaces the word to be completed
! 1398: with a single match from the list of possible completions.
! 1399: Repeated execution of @code{menu-complete} steps through the list
! 1400: of possible completions, inserting each match in turn.
! 1401: At the end of the list of completions, the bell is rung
! 1402: (subject to the setting of @code{bell-style})
! 1403: and the original text is restored.
! 1404: An argument of @var{n} moves @var{n} positions forward in the list
! 1405: of matches; a negative argument may be used to move backward
! 1406: through the list.
! 1407: This command is intended to be bound to @key{TAB}, but is unbound
! 1408: by default.
! 1409:
! 1410: @item menu-complete-backward ()
! 1411: Identical to @code{menu-complete}, but moves backward through the list
! 1412: of possible completions, as if @code{menu-complete} had been given a
! 1413: negative argument.
! 1414:
! 1415: @item delete-char-or-list ()
! 1416: Deletes the character under the cursor if not at the beginning or
! 1417: end of the line (like @code{delete-char}).
! 1418: If at the end of the line, behaves identically to
! 1419: @code{possible-completions}.
! 1420: This command is unbound by default.
! 1421:
! 1422: @ifset BashFeatures
! 1423: @item complete-filename (M-/)
! 1424: Attempt filename completion on the text before point.
! 1425:
! 1426: @item possible-filename-completions (C-x /)
! 1427: List the possible completions of the text before point,
! 1428: treating it as a filename.
! 1429:
! 1430: @item complete-username (M-~)
! 1431: Attempt completion on the text before point, treating
! 1432: it as a username.
! 1433:
! 1434: @item possible-username-completions (C-x ~)
! 1435: List the possible completions of the text before point,
! 1436: treating it as a username.
! 1437:
! 1438: @item complete-variable (M-$)
! 1439: Attempt completion on the text before point, treating
! 1440: it as a shell variable.
! 1441:
! 1442: @item possible-variable-completions (C-x $)
! 1443: List the possible completions of the text before point,
! 1444: treating it as a shell variable.
! 1445:
! 1446: @item complete-hostname (M-@@)
! 1447: Attempt completion on the text before point, treating
! 1448: it as a hostname.
! 1449:
! 1450: @item possible-hostname-completions (C-x @@)
! 1451: List the possible completions of the text before point,
! 1452: treating it as a hostname.
! 1453:
! 1454: @item complete-command (M-!)
! 1455: Attempt completion on the text before point, treating
! 1456: it as a command name. Command completion attempts to
! 1457: match the text against aliases, reserved words, shell
! 1458: functions, shell builtins, and finally executable filenames,
! 1459: in that order.
! 1460:
! 1461: @item possible-command-completions (C-x !)
! 1462: List the possible completions of the text before point,
! 1463: treating it as a command name.
! 1464:
! 1465: @item dynamic-complete-history (M-@key{TAB})
! 1466: Attempt completion on the text before point, comparing
! 1467: the text against lines from the history list for possible
! 1468: completion matches.
! 1469:
! 1470: @item dabbrev-expand ()
! 1471: Attempt menu completion on the text before point, comparing
! 1472: the text against lines from the history list for possible
! 1473: completion matches.
! 1474:
! 1475: @item complete-into-braces (M-@{)
! 1476: Perform filename completion and insert the list of possible completions
! 1477: enclosed within braces so the list is available to the shell
! 1478: (@pxref{Brace Expansion}).
! 1479:
! 1480: @end ifset
! 1481: @end ftable
! 1482:
! 1483: @node Keyboard Macros
! 1484: @subsection Keyboard Macros
! 1485: @ftable @code
! 1486:
! 1487: @item start-kbd-macro (C-x ()
! 1488: Begin saving the characters typed into the current keyboard macro.
! 1489:
! 1490: @item end-kbd-macro (C-x ))
! 1491: Stop saving the characters typed into the current keyboard macro
! 1492: and save the definition.
! 1493:
! 1494: @item call-last-kbd-macro (C-x e)
! 1495: Re-execute the last keyboard macro defined, by making the characters
! 1496: in the macro appear as if typed at the keyboard.
! 1497:
! 1498: @item print-last-kbd-macro ()
! 1499: Print the last keboard macro defined in a format suitable for the
! 1500: @var{inputrc} file.
! 1501:
! 1502: @end ftable
! 1503:
! 1504: @node Miscellaneous Commands
! 1505: @subsection Some Miscellaneous Commands
! 1506: @ftable @code
! 1507:
! 1508: @item re-read-init-file (C-x C-r)
! 1509: Read in the contents of the @var{inputrc} file, and incorporate
! 1510: any bindings or variable assignments found there.
! 1511:
! 1512: @item abort (C-g)
! 1513: Abort the current editing command and
! 1514: ring the terminal's bell (subject to the setting of
! 1515: @code{bell-style}).
! 1516:
! 1517: @item do-uppercase-version (M-a, M-b, M-@var{x}, @dots{})
! 1518: If the metafied character @var{x} is lowercase, run the command
! 1519: that is bound to the corresponding uppercase character.
! 1520:
! 1521: @item prefix-meta (@key{ESC})
! 1522: Metafy the next character typed. This is for keyboards
! 1523: without a meta key. Typing @samp{@key{ESC} f} is equivalent to typing
! 1524: @kbd{M-f}.
! 1525:
! 1526: @item undo (C-_ or C-x C-u)
! 1527: Incremental undo, separately remembered for each line.
! 1528:
! 1529: @item revert-line (M-r)
! 1530: Undo all changes made to this line. This is like executing the @code{undo}
! 1531: command enough times to get back to the beginning.
! 1532:
! 1533: @ifset BashFeatures
! 1534: @item tilde-expand (M-&)
! 1535: @end ifset
! 1536: @ifclear BashFeatures
! 1537: @item tilde-expand (M-~)
! 1538: @end ifclear
! 1539: Perform tilde expansion on the current word.
! 1540:
! 1541: @item set-mark (C-@@)
! 1542: Set the mark to the point. If a
! 1543: numeric argument is supplied, the mark is set to that position.
! 1544:
! 1545: @item exchange-point-and-mark (C-x C-x)
! 1546: Swap the point with the mark. The current cursor position is set to
! 1547: the saved position, and the old cursor position is saved as the mark.
! 1548:
! 1549: @item character-search (C-])
! 1550: A character is read and point is moved to the next occurrence of that
! 1551: character. A negative count searches for previous occurrences.
! 1552:
! 1553: @item character-search-backward (M-C-])
! 1554: A character is read and point is moved to the previous occurrence
! 1555: of that character. A negative count searches for subsequent
! 1556: occurrences.
! 1557:
! 1558: @item skip-csi-sequence ()
! 1559: Read enough characters to consume a multi-key sequence such as those
! 1560: defined for keys like Home and End. Such sequences begin with a
! 1561: Control Sequence Indicator (CSI), usually ESC-[. If this sequence is
! 1562: bound to "\e[", keys producing such sequences will have no effect
! 1563: unless explicitly bound to a readline command, instead of inserting
! 1564: stray characters into the editing buffer. This is unbound by default,
! 1565: but usually bound to ESC-[.
! 1566:
! 1567: @item insert-comment (M-#)
! 1568: Without a numeric argument, the value of the @code{comment-begin}
! 1569: variable is inserted at the beginning of the current line.
! 1570: If a numeric argument is supplied, this command acts as a toggle: if
! 1571: the characters at the beginning of the line do not match the value
! 1572: of @code{comment-begin}, the value is inserted, otherwise
! 1573: the characters in @code{comment-begin} are deleted from the beginning of
! 1574: the line.
! 1575: In either case, the line is accepted as if a newline had been typed.
! 1576: @ifset BashFeatures
! 1577: The default value of @code{comment-begin} causes this command
! 1578: to make the current line a shell comment.
! 1579: If a numeric argument causes the comment character to be removed, the line
! 1580: will be executed by the shell.
! 1581: @end ifset
! 1582:
! 1583: @item dump-functions ()
! 1584: Print all of the functions and their key bindings to the
! 1585: Readline output stream. If a numeric argument is supplied,
! 1586: the output is formatted in such a way that it can be made part
! 1587: of an @var{inputrc} file. This command is unbound by default.
! 1588:
! 1589: @item dump-variables ()
! 1590: Print all of the settable variables and their values to the
! 1591: Readline output stream. If a numeric argument is supplied,
! 1592: the output is formatted in such a way that it can be made part
! 1593: of an @var{inputrc} file. This command is unbound by default.
! 1594:
! 1595: @item dump-macros ()
! 1596: Print all of the Readline key sequences bound to macros and the
! 1597: strings they output. If a numeric argument is supplied,
! 1598: the output is formatted in such a way that it can be made part
! 1599: of an @var{inputrc} file. This command is unbound by default.
! 1600:
! 1601: @ifset BashFeatures
! 1602: @item glob-complete-word (M-g)
! 1603: The word before point is treated as a pattern for pathname expansion,
! 1604: with an asterisk implicitly appended. This pattern is used to
! 1605: generate a list of matching file names for possible completions.
! 1606:
! 1607: @item glob-expand-word (C-x *)
! 1608: The word before point is treated as a pattern for pathname expansion,
! 1609: and the list of matching file names is inserted, replacing the word.
! 1610: If a numeric argument is supplied, a @samp{*} is appended before
! 1611: pathname expansion.
! 1612:
! 1613: @item glob-list-expansions (C-x g)
! 1614: The list of expansions that would have been generated by
! 1615: @code{glob-expand-word} is displayed, and the line is redrawn.
! 1616: If a numeric argument is supplied, a @samp{*} is appended before
! 1617: pathname expansion.
! 1618:
! 1619: @item display-shell-version (C-x C-v)
! 1620: Display version information about the current instance of Bash.
! 1621:
! 1622: @item shell-expand-line (M-C-e)
! 1623: Expand the line as the shell does.
! 1624: This performs alias and history expansion as well as all of the shell
! 1625: word expansions (@pxref{Shell Expansions}).
! 1626:
! 1627: @item history-expand-line (M-^)
! 1628: Perform history expansion on the current line.
! 1629:
! 1630: @item magic-space ()
! 1631: Perform history expansion on the current line and insert a space
! 1632: (@pxref{History Interaction}).
! 1633:
! 1634: @item alias-expand-line ()
! 1635: Perform alias expansion on the current line (@pxref{Aliases}).
! 1636:
! 1637: @item history-and-alias-expand-line ()
! 1638: Perform history and alias expansion on the current line.
! 1639:
! 1640: @item insert-last-argument (M-. or M-_)
! 1641: A synonym for @code{yank-last-arg}.
! 1642:
! 1643: @item operate-and-get-next (C-o)
! 1644: Accept the current line for execution and fetch the next line
! 1645: relative to the current line from the history for editing. Any
! 1646: argument is ignored.
! 1647:
! 1648: @item edit-and-execute-command (C-xC-e)
! 1649: Invoke an editor on the current command line, and execute the result as shell
! 1650: commands.
! 1651: Bash attempts to invoke
! 1652: @code{$VISUAL}, @code{$EDITOR}, and @code{emacs}
! 1653: as the editor, in that order.
! 1654:
! 1655: @end ifset
! 1656:
! 1657: @ifclear BashFeatures
! 1658: @item emacs-editing-mode (C-e)
! 1659: When in @code{vi} command mode, this causes a switch to @code{emacs}
! 1660: editing mode.
! 1661:
! 1662: @item vi-editing-mode (M-C-j)
! 1663: When in @code{emacs} editing mode, this causes a switch to @code{vi}
! 1664: editing mode.
! 1665:
! 1666: @end ifclear
! 1667:
! 1668: @end ftable
! 1669:
! 1670: @node Readline vi Mode
! 1671: @section Readline vi Mode
! 1672:
! 1673: While the Readline library does not have a full set of @code{vi}
! 1674: editing functions, it does contain enough to allow simple editing
! 1675: of the line. The Readline @code{vi} mode behaves as specified in
! 1676: the @sc{posix} standard.
! 1677:
! 1678: @ifset BashFeatures
! 1679: In order to switch interactively between @code{emacs} and @code{vi}
! 1680: editing modes, use the @samp{set -o emacs} and @samp{set -o vi}
! 1681: commands (@pxref{The Set Builtin}).
! 1682: @end ifset
! 1683: @ifclear BashFeatures
! 1684: In order to switch interactively between @code{emacs} and @code{vi}
! 1685: editing modes, use the command @kbd{M-C-j} (bound to emacs-editing-mode
! 1686: when in @code{vi} mode and to vi-editing-mode in @code{emacs} mode).
! 1687: @end ifclear
! 1688: The Readline default is @code{emacs} mode.
! 1689:
! 1690: When you enter a line in @code{vi} mode, you are already placed in
! 1691: `insertion' mode, as if you had typed an @samp{i}. Pressing @key{ESC}
! 1692: switches you into `command' mode, where you can edit the text of the
! 1693: line with the standard @code{vi} movement keys, move to previous
! 1694: history lines with @samp{k} and subsequent lines with @samp{j}, and
! 1695: so forth.
! 1696:
! 1697: @ifset BashFeatures
! 1698: @node Programmable Completion
! 1699: @section Programmable Completion
! 1700: @cindex programmable completion
! 1701:
! 1702: When word completion is attempted for an argument to a command for
! 1703: which a completion specification (a @var{compspec}) has been defined
! 1704: using the @code{complete} builtin (@pxref{Programmable Completion Builtins}),
! 1705: the programmable completion facilities are invoked.
! 1706:
! 1707: First, the command name is identified.
! 1708: If a compspec has been defined for that command, the
! 1709: compspec is used to generate the list of possible completions for the word.
! 1710: If the command word is the empty string (completion attempted at the
! 1711: beginning of an empty line), any compspec defined with
! 1712: the @option{-E} option to @code{complete} is used.
! 1713: If the command word is a full pathname, a compspec for the full
! 1714: pathname is searched for first.
! 1715: If no compspec is found for the full pathname, an attempt is made to
! 1716: find a compspec for the portion following the final slash.
! 1717: If those searches do not result in a compspec, any compspec defined with
! 1718: the @option{-D} option to @code{complete} is used as the default.
! 1719:
! 1720: Once a compspec has been found, it is used to generate the list of
! 1721: matching words.
! 1722: If a compspec is not found, the default Bash completion
! 1723: described above (@pxref{Commands For Completion}) is performed.
! 1724:
! 1725: First, the actions specified by the compspec are used.
! 1726: Only matches which are prefixed by the word being completed are
! 1727: returned.
! 1728: When the @option{-f} or @option{-d} option is used for filename or
! 1729: directory name completion, the shell variable @env{FIGNORE} is
! 1730: used to filter the matches.
! 1731: @xref{Bash Variables}, for a description of @env{FIGNORE}.
! 1732:
! 1733: Any completions specified by a filename expansion pattern to the
! 1734: @option{-G} option are generated next.
! 1735: The words generated by the pattern need not match the word being completed.
! 1736: The @env{GLOBIGNORE} shell variable is not used to filter the matches,
! 1737: but the @env{FIGNORE} shell variable is used.
! 1738:
! 1739: Next, the string specified as the argument to the @option{-W} option
! 1740: is considered.
! 1741: The string is first split using the characters in the @env{IFS}
! 1742: special variable as delimiters.
! 1743: Shell quoting is honored.
! 1744: Each word is then expanded using
! 1745: brace expansion, tilde expansion, parameter and variable expansion,
! 1746: command substitution, and arithmetic expansion,
! 1747: as described above (@pxref{Shell Expansions}).
! 1748: The results are split using the rules described above
! 1749: (@pxref{Word Splitting}).
! 1750: The results of the expansion are prefix-matched against the word being
! 1751: completed, and the matching words become the possible completions.
! 1752:
! 1753: After these matches have been generated, any shell function or command
! 1754: specified with the @option{-F} and @option{-C} options is invoked.
! 1755: When the command or function is invoked, the @env{COMP_LINE},
! 1756: @env{COMP_POINT}, @env{COMP_KEY}, and @env{COMP_TYPE} variables are
! 1757: assigned values as described above (@pxref{Bash Variables}).
! 1758: If a shell function is being invoked, the @env{COMP_WORDS} and
! 1759: @env{COMP_CWORD} variables are also set.
! 1760: When the function or command is invoked, the first argument ($1) is the
! 1761: name of the command whose arguments are being completed, the
! 1762: second argument ($2) is the word being completed, and the third argument
! 1763: ($3) is the word preceding the word being completed on the current command
! 1764: line.
! 1765: No filtering of the generated completions against the word being completed
! 1766: is performed; the function or command has complete freedom in generating
! 1767: the matches.
! 1768:
! 1769: Any function specified with @option{-F} is invoked first.
! 1770: The function may use any of the shell facilities, including the
! 1771: @code{compgen} and @code{compopt} builtins described below
! 1772: (@pxref{Programmable Completion Builtins}), to generate the matches.
! 1773: It must put the possible completions in the @env{COMPREPLY} array
! 1774: variable, one per array element.
! 1775:
! 1776: Next, any command specified with the @option{-C} option is invoked
! 1777: in an environment equivalent to command substitution.
! 1778: It should print a list of completions, one per line, to
! 1779: the standard output.
! 1780: Backslash may be used to escape a newline, if necessary.
! 1781:
! 1782: After all of the possible completions are generated, any filter
! 1783: specified with the @option{-X} option is applied to the list.
! 1784: The filter is a pattern as used for pathname expansion; a @samp{&}
! 1785: in the pattern is replaced with the text of the word being completed.
! 1786: A literal @samp{&} may be escaped with a backslash; the backslash
! 1787: is removed before attempting a match.
! 1788: Any completion that matches the pattern will be removed from the list.
! 1789: A leading @samp{!} negates the pattern; in this case any completion
! 1790: not matching the pattern will be removed.
! 1791:
! 1792: Finally, any prefix and suffix specified with the @option{-P} and @option{-S}
! 1793: options are added to each member of the completion list, and the result is
! 1794: returned to the Readline completion code as the list of possible
! 1795: completions.
! 1796:
! 1797: If the previously-applied actions do not generate any matches, and the
! 1798: @option{-o dirnames} option was supplied to @code{complete} when the
! 1799: compspec was defined, directory name completion is attempted.
! 1800:
! 1801: If the @option{-o plusdirs} option was supplied to @code{complete} when
! 1802: the compspec was defined, directory name completion is attempted and any
! 1803: matches are added to the results of the other actions.
! 1804:
! 1805: By default, if a compspec is found, whatever it generates is returned to
! 1806: the completion code as the full set of possible completions.
! 1807: The default Bash completions are not attempted, and the Readline default
! 1808: of filename completion is disabled.
! 1809: If the @option{-o bashdefault} option was supplied to @code{complete} when
! 1810: the compspec was defined, the default Bash completions are attempted
! 1811: if the compspec generates no matches.
! 1812: If the @option{-o default} option was supplied to @code{complete} when the
! 1813: compspec was defined, Readline's default completion will be performed
! 1814: if the compspec (and, if attempted, the default Bash completions)
! 1815: generate no matches.
! 1816:
! 1817: When a compspec indicates that directory name completion is desired,
! 1818: the programmable completion functions force Readline to append a slash
! 1819: to completed names which are symbolic links to directories, subject to
! 1820: the value of the @var{mark-directories} Readline variable, regardless
! 1821: of the setting of the @var{mark-symlinked-directories} Readline variable.
! 1822:
! 1823: There is some support for dynamically modifying completions. This is
! 1824: most useful when used in combination with a default completion specified
! 1825: with @option{-D}. It's possible for shell functions executed as completion
! 1826: handlers to indicate that completion should be retried by returning an
! 1827: exit status of 124. If a shell function returns 124, and changes
! 1828: the compspec associated with the command on which completion is being
! 1829: attempted (supplied as the first argument when the function is executed),
! 1830: programmable completion restarts from the beginning, with an
! 1831: attempt to find a new compspec for that command. This allows a set of
! 1832: completions to be built dynamically as completion is attempted, rather than
! 1833: being loaded all at once.
! 1834:
! 1835: For instance, assuming that there is a library of compspecs, each kept in a
! 1836: file corresponding to the name of the command, the following default
! 1837: completion function would load completions dynamically:
! 1838:
! 1839: @example
! 1840: _completion_loader()
! 1841: @{
! 1842: . "/etc/bash_completion.d/$1.sh" >/dev/null 2>&1 && return 124
! 1843: @}
! 1844: complete -D -F _completion_loader -o bashdefault -o default
! 1845: @end example
! 1846:
! 1847: @node Programmable Completion Builtins
! 1848: @section Programmable Completion Builtins
! 1849: @cindex completion builtins
! 1850:
! 1851: Three builtin commands are available to manipulate the programmable completion
! 1852: facilities: one to specify how the arguments to a particular command are to
! 1853: be completed, and two to modify the completion as it is happening.
! 1854:
! 1855: @table @code
! 1856: @item compgen
! 1857: @btindex compgen
! 1858: @example
! 1859: @code{compgen [@var{option}] [@var{word}]}
! 1860: @end example
! 1861:
! 1862: Generate possible completion matches for @var{word} according to
! 1863: the @var{option}s, which may be any option accepted by the
! 1864: @code{complete}
! 1865: builtin with the exception of @option{-p} and @option{-r}, and write
! 1866: the matches to the standard output.
! 1867: When using the @option{-F} or @option{-C} options, the various shell variables
! 1868: set by the programmable completion facilities, while available, will not
! 1869: have useful values.
! 1870:
! 1871: The matches will be generated in the same way as if the programmable
! 1872: completion code had generated them directly from a completion specification
! 1873: with the same flags.
! 1874: If @var{word} is specified, only those completions matching @var{word}
! 1875: will be displayed.
! 1876:
! 1877: The return value is true unless an invalid option is supplied, or no
! 1878: matches were generated.
! 1879:
! 1880: @item complete
! 1881: @btindex complete
! 1882: @example
! 1883: @code{complete [-abcdefgjksuv] [-o @var{comp-option}] [-DE] [-A @var{action}] [-G @var{globpat}] [-W @var{wordlist}]
! 1884: [-F @var{function}] [-C @var{command}] [-X @var{filterpat}]
! 1885: [-P @var{prefix}] [-S @var{suffix}] @var{name} [@var{name} @dots{}]}
! 1886: @code{complete -pr [-DE] [@var{name} @dots{}]}
! 1887: @end example
! 1888:
! 1889: Specify how arguments to each @var{name} should be completed.
! 1890: If the @option{-p} option is supplied, or if no options are supplied, existing
! 1891: completion specifications are printed in a way that allows them to be
! 1892: reused as input.
! 1893: The @option{-r} option removes a completion specification for
! 1894: each @var{name}, or, if no @var{name}s are supplied, all
! 1895: completion specifications.
! 1896: The @option{-D} option indicates that the remaining options and actions should
! 1897: apply to the ``default'' command completion; that is, completion attempted
! 1898: on a command for which no completion has previously been defined.
! 1899: The @option{-E} option indicates that the remaining options and actions should
! 1900: apply to ``empty'' command completion; that is, completion attempted on a
! 1901: blank line.
! 1902:
! 1903: The process of applying these completion specifications when word completion
! 1904: is attempted is described above (@pxref{Programmable Completion}). The
! 1905: @option{-D} option takes precedence over @option{-E}.
! 1906:
! 1907: Other options, if specified, have the following meanings.
! 1908: The arguments to the @option{-G}, @option{-W}, and @option{-X} options
! 1909: (and, if necessary, the @option{-P} and @option{-S} options)
! 1910: should be quoted to protect them from expansion before the
! 1911: @code{complete} builtin is invoked.
! 1912:
! 1913:
! 1914: @table @code
! 1915: @item -o @var{comp-option}
! 1916: The @var{comp-option} controls several aspects of the compspec's behavior
! 1917: beyond the simple generation of completions.
! 1918: @var{comp-option} may be one of:
! 1919:
! 1920: @table @code
! 1921:
! 1922: @item bashdefault
! 1923: Perform the rest of the default Bash completions if the compspec
! 1924: generates no matches.
! 1925:
! 1926: @item default
! 1927: Use Readline's default filename completion if the compspec generates
! 1928: no matches.
! 1929:
! 1930: @item dirnames
! 1931: Perform directory name completion if the compspec generates no matches.
! 1932:
! 1933: @item filenames
! 1934: Tell Readline that the compspec generates filenames, so it can perform any
! 1935: filename-specific processing (like adding a slash to directory names
! 1936: quoting special characters, or suppressing trailing spaces).
! 1937: This option is intended to be used with shell functions specified
! 1938: with @option{-F}.
! 1939:
! 1940: @item noquote
! 1941: Tell Readline not to quote the completed words if they are filenames
! 1942: (quoting filenames is the default).
! 1943:
! 1944: @item nospace
! 1945: Tell Readline not to append a space (the default) to words completed at
! 1946: the end of the line.
! 1947:
! 1948: @item plusdirs
! 1949: After any matches defined by the compspec are generated,
! 1950: directory name completion is attempted and any
! 1951: matches are added to the results of the other actions.
! 1952:
! 1953: @end table
! 1954:
! 1955: @item -A @var{action}
! 1956: The @var{action} may be one of the following to generate a list of possible
! 1957: completions:
! 1958:
! 1959: @table @code
! 1960: @item alias
! 1961: Alias names. May also be specified as @option{-a}.
! 1962:
! 1963: @item arrayvar
! 1964: Array variable names.
! 1965:
! 1966: @item binding
! 1967: Readline key binding names (@pxref{Bindable Readline Commands}).
! 1968:
! 1969: @item builtin
! 1970: Names of shell builtin commands. May also be specified as @option{-b}.
! 1971:
! 1972: @item command
! 1973: Command names. May also be specified as @option{-c}.
! 1974:
! 1975: @item directory
! 1976: Directory names. May also be specified as @option{-d}.
! 1977:
! 1978: @item disabled
! 1979: Names of disabled shell builtins.
! 1980:
! 1981: @item enabled
! 1982: Names of enabled shell builtins.
! 1983:
! 1984: @item export
! 1985: Names of exported shell variables. May also be specified as @option{-e}.
! 1986:
! 1987: @item file
! 1988: File names. May also be specified as @option{-f}.
! 1989:
! 1990: @item function
! 1991: Names of shell functions.
! 1992:
! 1993: @item group
! 1994: Group names. May also be specified as @option{-g}.
! 1995:
! 1996: @item helptopic
! 1997: Help topics as accepted by the @code{help} builtin (@pxref{Bash Builtins}).
! 1998:
! 1999: @item hostname
! 2000: Hostnames, as taken from the file specified by the
! 2001: @env{HOSTFILE} shell variable (@pxref{Bash Variables}).
! 2002:
! 2003: @item job
! 2004: Job names, if job control is active. May also be specified as @option{-j}.
! 2005:
! 2006: @item keyword
! 2007: Shell reserved words. May also be specified as @option{-k}.
! 2008:
! 2009: @item running
! 2010: Names of running jobs, if job control is active.
! 2011:
! 2012: @item service
! 2013: Service names. May also be specified as @option{-s}.
! 2014:
! 2015: @item setopt
! 2016: Valid arguments for the @option{-o} option to the @code{set} builtin
! 2017: (@pxref{The Set Builtin}).
! 2018:
! 2019: @item shopt
! 2020: Shell option names as accepted by the @code{shopt} builtin
! 2021: (@pxref{Bash Builtins}).
! 2022:
! 2023: @item signal
! 2024: Signal names.
! 2025:
! 2026: @item stopped
! 2027: Names of stopped jobs, if job control is active.
! 2028:
! 2029: @item user
! 2030: User names. May also be specified as @option{-u}.
! 2031:
! 2032: @item variable
! 2033: Names of all shell variables. May also be specified as @option{-v}.
! 2034: @end table
! 2035:
! 2036: @item -C @var{command}
! 2037: @var{command} is executed in a subshell environment, and its output is
! 2038: used as the possible completions.
! 2039:
! 2040: @item -F @var{function}
! 2041: The shell function @var{function} is executed in the current shell
! 2042: environment.
! 2043: When it is executed, $1 is the name of the command whose arguments are
! 2044: being completed, $2 is the word being completed, and $3 is the word
! 2045: preceding the word being completed, as described above
! 2046: (@pxref{Programmable Completion}).
! 2047: When it finishes, the possible completions are retrieved from the value
! 2048: of the @env{COMPREPLY} array variable.
! 2049:
! 2050: @item -G @var{globpat}
! 2051: The filename expansion pattern @var{globpat} is expanded to generate
! 2052: the possible completions.
! 2053:
! 2054: @item -P @var{prefix}
! 2055: @var{prefix} is added at the beginning of each possible completion
! 2056: after all other options have been applied.
! 2057:
! 2058: @item -S @var{suffix}
! 2059: @var{suffix} is appended to each possible completion
! 2060: after all other options have been applied.
! 2061:
! 2062: @item -W @var{wordlist}
! 2063: The @var{wordlist} is split using the characters in the
! 2064: @env{IFS} special variable as delimiters, and each resultant word
! 2065: is expanded.
! 2066: The possible completions are the members of the resultant list which
! 2067: match the word being completed.
! 2068:
! 2069: @item -X @var{filterpat}
! 2070: @var{filterpat} is a pattern as used for filename expansion.
! 2071: It is applied to the list of possible completions generated by the
! 2072: preceding options and arguments, and each completion matching
! 2073: @var{filterpat} is removed from the list.
! 2074: A leading @samp{!} in @var{filterpat} negates the pattern; in this
! 2075: case, any completion not matching @var{filterpat} is removed.
! 2076: @end table
! 2077:
! 2078: The return value is true unless an invalid option is supplied, an option
! 2079: other than @option{-p} or @option{-r} is supplied without a @var{name}
! 2080: argument, an attempt is made to remove a completion specification for
! 2081: a @var{name} for which no specification exists, or
! 2082: an error occurs adding a completion specification.
! 2083:
! 2084: @item compopt
! 2085: @btindex compopt
! 2086: @example
! 2087: @code{compopt} [-o @var{option}] [-DE] [+o @var{option}] [@var{name}]
! 2088: @end example
! 2089: Modify completion options for each @var{name} according to the
! 2090: @var{option}s, or for the currently-executing completion if no @var{name}s
! 2091: are supplied.
! 2092: If no @var{option}s are given, display the completion options for each
! 2093: @var{name} or the current completion.
! 2094: The possible values of @var{option} are those valid for the @code{complete}
! 2095: builtin described above.
! 2096: The @option{-D} option indicates that the remaining options should
! 2097: apply to the ``default'' command completion; that is, completion attempted
! 2098: on a command for which no completion has previously been defined.
! 2099: The @option{-E} option indicates that the remaining options should
! 2100: apply to ``empty'' command completion; that is, completion attempted on a
! 2101: blank line.
! 2102:
! 2103: The @option{-D} option takes precedence over @option{-E}.
! 2104:
! 2105: The return value is true unless an invalid option is supplied, an attempt
! 2106: is made to modify the options for a @var{name} for which no completion
! 2107: specification exists, or an output error occurs.
! 2108:
! 2109: @end table
! 2110:
! 2111: @node A Programmable Completion Example
! 2112: @section A Programmable Completion Example
! 2113:
! 2114: The most common way to obtain additional completion functionality beyond
! 2115: the default actions @code{complete} and @code{compgen} provide is to use
! 2116: a shell function and bind it to a particular command using @code{complete -F}.
! 2117:
! 2118: The following function provides completions for the @code{cd} builtin.
! 2119: It is a reasonably good example of what shell functions must do when
! 2120: used for completion. This function uses the word passsed as @code{$2}
! 2121: to determine the directory name to complete. You can also use the
! 2122: @code{COMP_WORDS} array variable; the current word is indexed by the
! 2123: @code{COMP_CWORD} variable.
! 2124:
! 2125: The function relies on the @code{complete} and @code{compgen} builtins
! 2126: to do much of the work, adding only the things that the Bash @code{cd}
! 2127: does beyond accepting basic directory names:
! 2128: tilde expansion (@pxref{Tilde Expansion}),
! 2129: searching directories in @var{$CDPATH}, which is described above
! 2130: (@pxref{Bourne Shell Builtins}),
! 2131: and basic support for the @code{cdable_vars} shell option
! 2132: (@pxref{The Shopt Builtin}).
! 2133: @code{_comp_cd} modifies the value of @var{IFS} so that it contains only
! 2134: a newline to accommodate file names containing spaces and tabs --
! 2135: @code{compgen} prints the possible completions it generates one per line.
! 2136:
! 2137: Possible completions go into the @var{COMPREPLY} array variable, one
! 2138: completion per array element. The programmable completion system retrieves
! 2139: the completions from there when the function returns.
! 2140:
! 2141: @example
! 2142: # A completion function for the cd builtin
! 2143: # based on the cd completion function from the bash_completion package
! 2144: _comp_cd()
! 2145: @{
! 2146: local IFS=$' \t\n' # normalize IFS
! 2147: local cur _skipdot _cdpath
! 2148: local i j k
! 2149:
! 2150: # Tilde expansion, with side effect of expanding tilde to full pathname
! 2151: case "$2" in
! 2152: \~*) eval cur="$2" ;;
! 2153: *) cur=$2 ;;
! 2154: esac
! 2155:
! 2156: # no cdpath or absolute pathname -- straight directory completion
! 2157: if [[ -z "$@{CDPATH:-@}" ]] || [[ "$cur" == @@(./*|../*|/*) ]]; then
! 2158: # compgen prints paths one per line; could also use while loop
! 2159: IFS=$'\n'
! 2160: COMPREPLY=( $(compgen -d -- "$cur") )
! 2161: IFS=$' \t\n'
! 2162: # CDPATH+directories in the current directory if not in CDPATH
! 2163: else
! 2164: IFS=$'\n'
! 2165: _skipdot=false
! 2166: # preprocess CDPATH to convert null directory names to .
! 2167: _cdpath=$@{CDPATH/#:/.:@}
! 2168: _cdpath=$@{_cdpath//::/:.:@}
! 2169: _cdpath=$@{_cdpath/%:/:.@}
! 2170: for i in $@{_cdpath//:/$'\n'@}; do
! 2171: if [[ $i -ef . ]]; then _skipdot=true; fi
! 2172: k="$@{#COMPREPLY[@@]@}"
! 2173: for j in $( compgen -d -- "$i/$cur" ); do
! 2174: COMPREPLY[k++]=$@{j#$i/@} # cut off directory
! 2175: done
! 2176: done
! 2177: $_skipdot || COMPREPLY+=( $(compgen -d -- "$cur") )
! 2178: IFS=$' \t\n'
! 2179: fi
! 2180:
! 2181: # variable names if appropriate shell option set and no completions
! 2182: if shopt -q cdable_vars && [[ $@{#COMPREPLY[@@]@} -eq 0 ]]; then
! 2183: COMPREPLY=( $(compgen -v -- "$cur") )
! 2184: fi
! 2185:
! 2186: return 0
! 2187: @}
! 2188: @end example
! 2189:
! 2190: We install the completion function using the @option{-F} option to
! 2191: @code{complete}:
! 2192:
! 2193: @example
! 2194: # Tell readline to quote appropriate and append slashes to directories;
! 2195: # use the bash default completion for other arguments
! 2196: complete -o filenames -o nospace -o bashdefault -F _comp_cd cd
! 2197: @end example
! 2198:
! 2199: @noindent
! 2200: Since we'd like Bash and Readline to take care of some
! 2201: of the other details for us, we use several other options to tell Bash
! 2202: and Readline what to do. The @option{-o filenames} option tells Readline
! 2203: that the possible completions should be treated as filenames, and quoted
! 2204: appropriately. That option will also cause Readline to append a slash to
! 2205: filenames it can determine are directories (which is why we might want to
! 2206: extend @code{_comp_cd} to append a slash if we're using directories found
! 2207: via @var{CDPATH}: Readline can't tell those completions are directories).
! 2208: The @option{-o nospace} option tells Readline to not append a space
! 2209: character to the directory name, in case we want to append to it.
! 2210: The @option{-o bashdefault} option brings in the rest of the "Bash default"
! 2211: completions -- possible completion that Bash adds to the default Readline
! 2212: set. These include things like command name completion, variable completion
! 2213: for words beginning with @samp{@{}, completions containing pathname
! 2214: expansion patterns (@pxref{Filename Expansion}), and so on.
! 2215:
! 2216: Once installed using @code{complete}, @code{_comp_cd} will be called every
! 2217: time we attempt word completion for a @code{cd} command.
! 2218:
! 2219: Many more examples -- an extensive collection of completions for most of
! 2220: the common GNU, Unix, and Linux commands -- are available as part of the
! 2221: bash_completion project. This is installed by default on many GNU/Linux
! 2222: distributions. Originally written by Ian Macdonald, the project now lives
! 2223: at @url{http://bash-completion.alioth.debian.org/}. There are ports for
! 2224: other systems such as Solaris and Mac OS X.
! 2225:
! 2226: An older version of the bash_completion package is distributed with bash
! 2227: in the @file{examples/complete} subdirectory.
! 2228:
! 2229: @end ifset
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to rluser.texi CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / readline / doc