Annotation of embedaddon/readline/doc/readline.info, revision 1.1
1.1 ! misho 1: This is readline.info, produced by makeinfo version 4.13 from
! 2: /usr/homes/chet/src/bash/readline-src/doc/rlman.texi.
! 3:
! 4: This manual describes the GNU Readline Library (version 6.3, 6 January
! 5: 2014), a library which aids in the consistency of user interface across
! 6: discrete programs which provide a command line interface.
! 7:
! 8: Copyright (C) 1988-2014 Free Software Foundation, Inc.
! 9:
! 10: Permission is granted to copy, distribute and/or modify this
! 11: document under the terms of the GNU Free Documentation License,
! 12: Version 1.3 or any later version published by the Free Software
! 13: Foundation; with no Invariant Sections, no Front-Cover Texts, and
! 14: no Back-Cover Texts. A copy of the license is included in the
! 15: section entitled "GNU Free Documentation License".
! 16:
! 17:
! 18: INFO-DIR-SECTION Libraries
! 19: START-INFO-DIR-ENTRY
! 20: * Readline: (readline). The GNU readline library API.
! 21: END-INFO-DIR-ENTRY
! 22:
! 23:
! 24: File: readline.info, Node: Top, Next: Command Line Editing, Up: (dir)
! 25:
! 26: GNU Readline Library
! 27: ********************
! 28:
! 29: This document describes the GNU Readline Library, a utility which aids
! 30: in the consistency of user interface across discrete programs which
! 31: provide a command line interface. The Readline home page is
! 32: `http://www.gnu.org/software/readline/'.
! 33:
! 34: * Menu:
! 35:
! 36: * Command Line Editing:: GNU Readline User's Manual.
! 37: * Programming with GNU Readline:: GNU Readline Programmer's Manual.
! 38: * GNU Free Documentation License:: License for copying this manual.
! 39: * Concept Index:: Index of concepts described in this manual.
! 40: * Function and Variable Index:: Index of externally visible functions
! 41: and variables.
! 42:
! 43:
! 44: File: readline.info, Node: Command Line Editing, Next: Programming with GNU Readline, Prev: Top, Up: Top
! 45:
! 46: 1 Command Line Editing
! 47: **********************
! 48:
! 49: This chapter describes the basic features of the GNU command line
! 50: editing interface.
! 51:
! 52: * Menu:
! 53:
! 54: * Introduction and Notation:: Notation used in this text.
! 55: * Readline Interaction:: The minimum set of commands for editing a line.
! 56: * Readline Init File:: Customizing Readline from a user's view.
! 57: * Bindable Readline Commands:: A description of most of the Readline commands
! 58: available for binding
! 59: * Readline vi Mode:: A short description of how to make Readline
! 60: behave like the vi editor.
! 61:
! 62:
! 63: File: readline.info, Node: Introduction and Notation, Next: Readline Interaction, Up: Command Line Editing
! 64:
! 65: 1.1 Introduction to Line Editing
! 66: ================================
! 67:
! 68: The following paragraphs describe the notation used to represent
! 69: keystrokes.
! 70:
! 71: The text `C-k' is read as `Control-K' and describes the character
! 72: produced when the <k> key is pressed while the Control key is depressed.
! 73:
! 74: The text `M-k' is read as `Meta-K' and describes the character
! 75: produced when the Meta key (if you have one) is depressed, and the <k>
! 76: key is pressed. The Meta key is labeled <ALT> on many keyboards. On
! 77: keyboards with two keys labeled <ALT> (usually to either side of the
! 78: space bar), the <ALT> on the left side is generally set to work as a
! 79: Meta key. The <ALT> key on the right may also be configured to work as
! 80: a Meta key or may be configured as some other modifier, such as a
! 81: Compose key for typing accented characters.
! 82:
! 83: If you do not have a Meta or <ALT> key, or another key working as a
! 84: Meta key, the identical keystroke can be generated by typing <ESC>
! 85: _first_, and then typing <k>. Either process is known as "metafying"
! 86: the <k> key.
! 87:
! 88: The text `M-C-k' is read as `Meta-Control-k' and describes the
! 89: character produced by "metafying" `C-k'.
! 90:
! 91: In addition, several keys have their own names. Specifically,
! 92: <DEL>, <ESC>, <LFD>, <SPC>, <RET>, and <TAB> all stand for themselves
! 93: when seen in this text, or in an init file (*note Readline Init File::).
! 94: If your keyboard lacks a <LFD> key, typing <C-j> will produce the
! 95: desired character. The <RET> key may be labeled <Return> or <Enter> on
! 96: some keyboards.
! 97:
! 98:
! 99: File: readline.info, Node: Readline Interaction, Next: Readline Init File, Prev: Introduction and Notation, Up: Command Line Editing
! 100:
! 101: 1.2 Readline Interaction
! 102: ========================
! 103:
! 104: Often during an interactive session you type in a long line of text,
! 105: only to notice that the first word on the line is misspelled. The
! 106: Readline library gives you a set of commands for manipulating the text
! 107: as you type it in, allowing you to just fix your typo, and not forcing
! 108: you to retype the majority of the line. Using these editing commands,
! 109: you move the cursor to the place that needs correction, and delete or
! 110: insert the text of the corrections. Then, when you are satisfied with
! 111: the line, you simply press <RET>. You do not have to be at the end of
! 112: the line to press <RET>; the entire line is accepted regardless of the
! 113: location of the cursor within the line.
! 114:
! 115: * Menu:
! 116:
! 117: * Readline Bare Essentials:: The least you need to know about Readline.
! 118: * Readline Movement Commands:: Moving about the input line.
! 119: * Readline Killing Commands:: How to delete text, and how to get it back!
! 120: * Readline Arguments:: Giving numeric arguments to commands.
! 121: * Searching:: Searching through previous lines.
! 122:
! 123:
! 124: File: readline.info, Node: Readline Bare Essentials, Next: Readline Movement Commands, Up: Readline Interaction
! 125:
! 126: 1.2.1 Readline Bare Essentials
! 127: ------------------------------
! 128:
! 129: In order to enter characters into the line, simply type them. The typed
! 130: character appears where the cursor was, and then the cursor moves one
! 131: space to the right. If you mistype a character, you can use your erase
! 132: character to back up and delete the mistyped character.
! 133:
! 134: Sometimes you may mistype a character, and not notice the error
! 135: until you have typed several other characters. In that case, you can
! 136: type `C-b' to move the cursor to the left, and then correct your
! 137: mistake. Afterwards, you can move the cursor to the right with `C-f'.
! 138:
! 139: When you add text in the middle of a line, you will notice that
! 140: characters to the right of the cursor are `pushed over' to make room
! 141: for the text that you have inserted. Likewise, when you delete text
! 142: behind the cursor, characters to the right of the cursor are `pulled
! 143: back' to fill in the blank space created by the removal of the text. A
! 144: list of the bare essentials for editing the text of an input line
! 145: follows.
! 146:
! 147: `C-b'
! 148: Move back one character.
! 149:
! 150: `C-f'
! 151: Move forward one character.
! 152:
! 153: <DEL> or <Backspace>
! 154: Delete the character to the left of the cursor.
! 155:
! 156: `C-d'
! 157: Delete the character underneath the cursor.
! 158:
! 159: Printing characters
! 160: Insert the character into the line at the cursor.
! 161:
! 162: `C-_' or `C-x C-u'
! 163: Undo the last editing command. You can undo all the way back to an
! 164: empty line.
! 165:
! 166: (Depending on your configuration, the <Backspace> key be set to delete
! 167: the character to the left of the cursor and the <DEL> key set to delete
! 168: the character underneath the cursor, like `C-d', rather than the
! 169: character to the left of the cursor.)
! 170:
! 171:
! 172: File: readline.info, Node: Readline Movement Commands, Next: Readline Killing Commands, Prev: Readline Bare Essentials, Up: Readline Interaction
! 173:
! 174: 1.2.2 Readline Movement Commands
! 175: --------------------------------
! 176:
! 177: The above table describes the most basic keystrokes that you need in
! 178: order to do editing of the input line. For your convenience, many
! 179: other commands have been added in addition to `C-b', `C-f', `C-d', and
! 180: <DEL>. Here are some commands for moving more rapidly about the line.
! 181:
! 182: `C-a'
! 183: Move to the start of the line.
! 184:
! 185: `C-e'
! 186: Move to the end of the line.
! 187:
! 188: `M-f'
! 189: Move forward a word, where a word is composed of letters and
! 190: digits.
! 191:
! 192: `M-b'
! 193: Move backward a word.
! 194:
! 195: `C-l'
! 196: Clear the screen, reprinting the current line at the top.
! 197:
! 198: Notice how `C-f' moves forward a character, while `M-f' moves
! 199: forward a word. It is a loose convention that control keystrokes
! 200: operate on characters while meta keystrokes operate on words.
! 201:
! 202:
! 203: File: readline.info, Node: Readline Killing Commands, Next: Readline Arguments, Prev: Readline Movement Commands, Up: Readline Interaction
! 204:
! 205: 1.2.3 Readline Killing Commands
! 206: -------------------------------
! 207:
! 208: "Killing" text means to delete the text from the line, but to save it
! 209: away for later use, usually by "yanking" (re-inserting) it back into
! 210: the line. (`Cut' and `paste' are more recent jargon for `kill' and
! 211: `yank'.)
! 212:
! 213: If the description for a command says that it `kills' text, then you
! 214: can be sure that you can get the text back in a different (or the same)
! 215: place later.
! 216:
! 217: When you use a kill command, the text is saved in a "kill-ring".
! 218: Any number of consecutive kills save all of the killed text together, so
! 219: that when you yank it back, you get it all. The kill ring is not line
! 220: specific; the text that you killed on a previously typed line is
! 221: available to be yanked back later, when you are typing another line.
! 222:
! 223: Here is the list of commands for killing text.
! 224:
! 225: `C-k'
! 226: Kill the text from the current cursor position to the end of the
! 227: line.
! 228:
! 229: `M-d'
! 230: Kill from the cursor to the end of the current word, or, if between
! 231: words, to the end of the next word. Word boundaries are the same
! 232: as those used by `M-f'.
! 233:
! 234: `M-<DEL>'
! 235: Kill from the cursor the start of the current word, or, if between
! 236: words, to the start of the previous word. Word boundaries are the
! 237: same as those used by `M-b'.
! 238:
! 239: `C-w'
! 240: Kill from the cursor to the previous whitespace. This is
! 241: different than `M-<DEL>' because the word boundaries differ.
! 242:
! 243:
! 244: Here is how to "yank" the text back into the line. Yanking means to
! 245: copy the most-recently-killed text from the kill buffer.
! 246:
! 247: `C-y'
! 248: Yank the most recently killed text back into the buffer at the
! 249: cursor.
! 250:
! 251: `M-y'
! 252: Rotate the kill-ring, and yank the new top. You can only do this
! 253: if the prior command is `C-y' or `M-y'.
! 254:
! 255:
! 256: File: readline.info, Node: Readline Arguments, Next: Searching, Prev: Readline Killing Commands, Up: Readline Interaction
! 257:
! 258: 1.2.4 Readline Arguments
! 259: ------------------------
! 260:
! 261: You can pass numeric arguments to Readline commands. Sometimes the
! 262: argument acts as a repeat count, other times it is the sign of the
! 263: argument that is significant. If you pass a negative argument to a
! 264: command which normally acts in a forward direction, that command will
! 265: act in a backward direction. For example, to kill text back to the
! 266: start of the line, you might type `M-- C-k'.
! 267:
! 268: The general way to pass numeric arguments to a command is to type
! 269: meta digits before the command. If the first `digit' typed is a minus
! 270: sign (`-'), then the sign of the argument will be negative. Once you
! 271: have typed one meta digit to get the argument started, you can type the
! 272: remainder of the digits, and then the command. For example, to give
! 273: the `C-d' command an argument of 10, you could type `M-1 0 C-d', which
! 274: will delete the next ten characters on the input line.
! 275:
! 276:
! 277: File: readline.info, Node: Searching, Prev: Readline Arguments, Up: Readline Interaction
! 278:
! 279: 1.2.5 Searching for Commands in the History
! 280: -------------------------------------------
! 281:
! 282: Readline provides commands for searching through the command history
! 283: for lines containing a specified string. There are two search modes:
! 284: "incremental" and "non-incremental".
! 285:
! 286: Incremental searches begin before the user has finished typing the
! 287: search string. As each character of the search string is typed,
! 288: Readline displays the next entry from the history matching the string
! 289: typed so far. An incremental search requires only as many characters
! 290: as needed to find the desired history entry. To search backward in the
! 291: history for a particular string, type `C-r'. Typing `C-s' searches
! 292: forward through the history. The characters present in the value of
! 293: the `isearch-terminators' variable are used to terminate an incremental
! 294: search. If that variable has not been assigned a value, the <ESC> and
! 295: `C-J' characters will terminate an incremental search. `C-g' will
! 296: abort an incremental search and restore the original line. When the
! 297: search is terminated, the history entry containing the search string
! 298: becomes the current line.
! 299:
! 300: To find other matching entries in the history list, type `C-r' or
! 301: `C-s' as appropriate. This will search backward or forward in the
! 302: history for the next entry matching the search string typed so far.
! 303: Any other key sequence bound to a Readline command will terminate the
! 304: search and execute that command. For instance, a <RET> will terminate
! 305: the search and accept the line, thereby executing the command from the
! 306: history list. A movement command will terminate the search, make the
! 307: last line found the current line, and begin editing.
! 308:
! 309: Readline remembers the last incremental search string. If two
! 310: `C-r's are typed without any intervening characters defining a new
! 311: search string, any remembered search string is used.
! 312:
! 313: Non-incremental searches read the entire search string before
! 314: starting to search for matching history lines. The search string may be
! 315: typed by the user or be part of the contents of the current line.
! 316:
! 317:
! 318: File: readline.info, Node: Readline Init File, Next: Bindable Readline Commands, Prev: Readline Interaction, Up: Command Line Editing
! 319:
! 320: 1.3 Readline Init File
! 321: ======================
! 322:
! 323: Although the Readline library comes with a set of Emacs-like
! 324: keybindings installed by default, it is possible to use a different set
! 325: of keybindings. Any user can customize programs that use Readline by
! 326: putting commands in an "inputrc" file, conventionally in his home
! 327: directory. The name of this file is taken from the value of the
! 328: environment variable `INPUTRC'. If that variable is unset, the default
! 329: is `~/.inputrc'. If that file does not exist or cannot be read, the
! 330: ultimate default is `/etc/inputrc'.
! 331:
! 332: When a program which uses the Readline library starts up, the init
! 333: file is read, and the key bindings are set.
! 334:
! 335: In addition, the `C-x C-r' command re-reads this init file, thus
! 336: incorporating any changes that you might have made to it.
! 337:
! 338: * Menu:
! 339:
! 340: * Readline Init File Syntax:: Syntax for the commands in the inputrc file.
! 341:
! 342: * Conditional Init Constructs:: Conditional key bindings in the inputrc file.
! 343:
! 344: * Sample Init File:: An example inputrc file.
! 345:
! 346:
! 347: File: readline.info, Node: Readline Init File Syntax, Next: Conditional Init Constructs, Up: Readline Init File
! 348:
! 349: 1.3.1 Readline Init File Syntax
! 350: -------------------------------
! 351:
! 352: There are only a few basic constructs allowed in the Readline init
! 353: file. Blank lines are ignored. Lines beginning with a `#' are
! 354: comments. Lines beginning with a `$' indicate conditional constructs
! 355: (*note Conditional Init Constructs::). Other lines denote variable
! 356: settings and key bindings.
! 357:
! 358: Variable Settings
! 359: You can modify the run-time behavior of Readline by altering the
! 360: values of variables in Readline using the `set' command within the
! 361: init file. The syntax is simple:
! 362:
! 363: set VARIABLE VALUE
! 364:
! 365: Here, for example, is how to change from the default Emacs-like
! 366: key binding to use `vi' line editing commands:
! 367:
! 368: set editing-mode vi
! 369:
! 370: Variable names and values, where appropriate, are recognized
! 371: without regard to case. Unrecognized variable names are ignored.
! 372:
! 373: Boolean variables (those that can be set to on or off) are set to
! 374: on if the value is null or empty, ON (case-insensitive), or 1.
! 375: Any other value results in the variable being set to off.
! 376:
! 377: A great deal of run-time behavior is changeable with the following
! 378: variables.
! 379:
! 380: `bell-style'
! 381: Controls what happens when Readline wants to ring the
! 382: terminal bell. If set to `none', Readline never rings the
! 383: bell. If set to `visible', Readline uses a visible bell if
! 384: one is available. If set to `audible' (the default),
! 385: Readline attempts to ring the terminal's bell.
! 386:
! 387: `bind-tty-special-chars'
! 388: If set to `on', Readline attempts to bind the control
! 389: characters treated specially by the kernel's terminal driver
! 390: to their Readline equivalents.
! 391:
! 392: `colored-stats'
! 393: If set to `on', Readline displays possible completions using
! 394: different colors to indicate their file type. The color
! 395: definitions are taken from the value of the `LS_COLORS'
! 396: environment variable. The default is `off'.
! 397:
! 398: `comment-begin'
! 399: The string to insert at the beginning of the line when the
! 400: `insert-comment' command is executed. The default value is
! 401: `"#"'.
! 402:
! 403: `completion-display-width'
! 404: The number of screen columns used to display possible matches
! 405: when performing completion. The value is ignored if it is
! 406: less than 0 or greater than the terminal screen width. A
! 407: value of 0 will cause matches to be displayed one per line.
! 408: The default value is -1.
! 409:
! 410: `completion-ignore-case'
! 411: If set to `on', Readline performs filename matching and
! 412: completion in a case-insensitive fashion. The default value
! 413: is `off'.
! 414:
! 415: `completion-map-case'
! 416: If set to `on', and COMPLETION-IGNORE-CASE is enabled,
! 417: Readline treats hyphens (`-') and underscores (`_') as
! 418: equivalent when performing case-insensitive filename matching
! 419: and completion.
! 420:
! 421: `completion-prefix-display-length'
! 422: The length in characters of the common prefix of a list of
! 423: possible completions that is displayed without modification.
! 424: When set to a value greater than zero, common prefixes longer
! 425: than this value are replaced with an ellipsis when displaying
! 426: possible completions.
! 427:
! 428: `completion-query-items'
! 429: The number of possible completions that determines when the
! 430: user is asked whether the list of possibilities should be
! 431: displayed. If the number of possible completions is greater
! 432: than this value, Readline will ask the user whether or not he
! 433: wishes to view them; otherwise, they are simply listed. This
! 434: variable must be set to an integer value greater than or
! 435: equal to 0. A negative value means Readline should never ask.
! 436: The default limit is `100'.
! 437:
! 438: `convert-meta'
! 439: If set to `on', Readline will convert characters with the
! 440: eighth bit set to an ASCII key sequence by stripping the
! 441: eighth bit and prefixing an <ESC> character, converting them
! 442: to a meta-prefixed key sequence. The default value is `on'.
! 443:
! 444: `disable-completion'
! 445: If set to `On', Readline will inhibit word completion.
! 446: Completion characters will be inserted into the line as if
! 447: they had been mapped to `self-insert'. The default is `off'.
! 448:
! 449: `editing-mode'
! 450: The `editing-mode' variable controls which default set of key
! 451: bindings is used. By default, Readline starts up in Emacs
! 452: editing mode, where the keystrokes are most similar to Emacs.
! 453: This variable can be set to either `emacs' or `vi'.
! 454:
! 455: `echo-control-characters'
! 456: When set to `on', on operating systems that indicate they
! 457: support it, readline echoes a character corresponding to a
! 458: signal generated from the keyboard. The default is `on'.
! 459:
! 460: `enable-keypad'
! 461: When set to `on', Readline will try to enable the application
! 462: keypad when it is called. Some systems need this to enable
! 463: the arrow keys. The default is `off'.
! 464:
! 465: `enable-meta-key'
! 466: When set to `on', Readline will try to enable any meta
! 467: modifier key the terminal claims to support when it is
! 468: called. On many terminals, the meta key is used to send
! 469: eight-bit characters. The default is `on'.
! 470:
! 471: `expand-tilde'
! 472: If set to `on', tilde expansion is performed when Readline
! 473: attempts word completion. The default is `off'.
! 474:
! 475: `history-preserve-point'
! 476: If set to `on', the history code attempts to place the point
! 477: (the current cursor position) at the same location on each
! 478: history line retrieved with `previous-history' or
! 479: `next-history'. The default is `off'.
! 480:
! 481: `history-size'
! 482: Set the maximum number of history entries saved in the
! 483: history list. If set to zero, any existing history entries
! 484: are deleted and no new entries are saved. If set to a value
! 485: less than zero, the number of history entries is not limited.
! 486: By default, the number of history entries is not limited.
! 487:
! 488: `horizontal-scroll-mode'
! 489: This variable can be set to either `on' or `off'. Setting it
! 490: to `on' means that the text of the lines being edited will
! 491: scroll horizontally on a single screen line when they are
! 492: longer than the width of the screen, instead of wrapping onto
! 493: a new screen line. By default, this variable is set to `off'.
! 494:
! 495: `input-meta'
! 496: If set to `on', Readline will enable eight-bit input (it will
! 497: not clear the eighth bit in the characters it reads),
! 498: regardless of what the terminal claims it can support. The
! 499: default value is `off'. The name `meta-flag' is a synonym
! 500: for this variable.
! 501:
! 502: `isearch-terminators'
! 503: The string of characters that should terminate an incremental
! 504: search without subsequently executing the character as a
! 505: command (*note Searching::). If this variable has not been
! 506: given a value, the characters <ESC> and `C-J' will terminate
! 507: an incremental search.
! 508:
! 509: `keymap'
! 510: Sets Readline's idea of the current keymap for key binding
! 511: commands. Acceptable `keymap' names are `emacs',
! 512: `emacs-standard', `emacs-meta', `emacs-ctlx', `vi', `vi-move',
! 513: `vi-command', and `vi-insert'. `vi' is equivalent to
! 514: `vi-command'; `emacs' is equivalent to `emacs-standard'. The
! 515: default value is `emacs'. The value of the `editing-mode'
! 516: variable also affects the default keymap.
! 517:
! 518: `keyseq-timeout'
! 519: Specifies the duration Readline will wait for a character
! 520: when reading an ambiguous key sequence (one that can form a
! 521: complete key sequence using the input read so far, or can
! 522: take additional input to complete a longer key sequence). If
! 523: no input is received within the timeout, Readline will use
! 524: the shorter but complete key sequence. Readline uses this
! 525: value to determine whether or not input is available on the
! 526: current input source (`rl_instream' by default). The value
! 527: is specified in milliseconds, so a value of 1000 means that
! 528: Readline will wait one second for additional input. If this
! 529: variable is set to a value less than or equal to zero, or to a
! 530: non-numeric value, Readline will wait until another key is
! 531: pressed to decide which key sequence to complete. The
! 532: default value is `500'.
! 533:
! 534: `mark-directories'
! 535: If set to `on', completed directory names have a slash
! 536: appended. The default is `on'.
! 537:
! 538: `mark-modified-lines'
! 539: This variable, when set to `on', causes Readline to display an
! 540: asterisk (`*') at the start of history lines which have been
! 541: modified. This variable is `off' by default.
! 542:
! 543: `mark-symlinked-directories'
! 544: If set to `on', completed names which are symbolic links to
! 545: directories have a slash appended (subject to the value of
! 546: `mark-directories'). The default is `off'.
! 547:
! 548: `match-hidden-files'
! 549: This variable, when set to `on', causes Readline to match
! 550: files whose names begin with a `.' (hidden files) when
! 551: performing filename completion. If set to `off', the leading
! 552: `.' must be supplied by the user in the filename to be
! 553: completed. This variable is `on' by default.
! 554:
! 555: `menu-complete-display-prefix'
! 556: If set to `on', menu completion displays the common prefix of
! 557: the list of possible completions (which may be empty) before
! 558: cycling through the list. The default is `off'.
! 559:
! 560: `output-meta'
! 561: If set to `on', Readline will display characters with the
! 562: eighth bit set directly rather than as a meta-prefixed escape
! 563: sequence. The default is `off'.
! 564:
! 565: `page-completions'
! 566: If set to `on', Readline uses an internal `more'-like pager
! 567: to display a screenful of possible completions at a time.
! 568: This variable is `on' by default.
! 569:
! 570: `print-completions-horizontally'
! 571: If set to `on', Readline will display completions with matches
! 572: sorted horizontally in alphabetical order, rather than down
! 573: the screen. The default is `off'.
! 574:
! 575: `revert-all-at-newline'
! 576: If set to `on', Readline will undo all changes to history
! 577: lines before returning when `accept-line' is executed. By
! 578: default, history lines may be modified and retain individual
! 579: undo lists across calls to `readline'. The default is `off'.
! 580:
! 581: `show-all-if-ambiguous'
! 582: This alters the default behavior of the completion functions.
! 583: If set to `on', words which have more than one possible
! 584: completion cause the matches to be listed immediately instead
! 585: of ringing the bell. The default value is `off'.
! 586:
! 587: `show-all-if-unmodified'
! 588: This alters the default behavior of the completion functions
! 589: in a fashion similar to SHOW-ALL-IF-AMBIGUOUS. If set to
! 590: `on', words which have more than one possible completion
! 591: without any possible partial completion (the possible
! 592: completions don't share a common prefix) cause the matches to
! 593: be listed immediately instead of ringing the bell. The
! 594: default value is `off'.
! 595:
! 596: `show-mode-in-prompt'
! 597: If set to `on', add a character to the beginning of the prompt
! 598: indicating the editing mode: emacs (`@'), vi command (`:'),
! 599: or vi insertion (`+'). The default value is `off'.
! 600:
! 601: `skip-completed-text'
! 602: If set to `on', this alters the default completion behavior
! 603: when inserting a single match into the line. It's only
! 604: active when performing completion in the middle of a word.
! 605: If enabled, readline does not insert characters from the
! 606: completion that match characters after point in the word
! 607: being completed, so portions of the word following the cursor
! 608: are not duplicated. For instance, if this is enabled,
! 609: attempting completion when the cursor is after the `e' in
! 610: `Makefile' will result in `Makefile' rather than
! 611: `Makefilefile', assuming there is a single possible
! 612: completion. The default value is `off'.
! 613:
! 614: `visible-stats'
! 615: If set to `on', a character denoting a file's type is
! 616: appended to the filename when listing possible completions.
! 617: The default is `off'.
! 618:
! 619:
! 620: Key Bindings
! 621: The syntax for controlling key bindings in the init file is
! 622: simple. First you need to find the name of the command that you
! 623: want to change. The following sections contain tables of the
! 624: command name, the default keybinding, if any, and a short
! 625: description of what the command does.
! 626:
! 627: Once you know the name of the command, simply place on a line in
! 628: the init file the name of the key you wish to bind the command to,
! 629: a colon, and then the name of the command. There can be no space
! 630: between the key name and the colon - that will be interpreted as
! 631: part of the key name. The name of the key can be expressed in
! 632: different ways, depending on what you find most comfortable.
! 633:
! 634: In addition to command names, readline allows keys to be bound to
! 635: a string that is inserted when the key is pressed (a MACRO).
! 636:
! 637: KEYNAME: FUNCTION-NAME or MACRO
! 638: KEYNAME is the name of a key spelled out in English. For
! 639: example:
! 640: Control-u: universal-argument
! 641: Meta-Rubout: backward-kill-word
! 642: Control-o: "> output"
! 643:
! 644: In the above example, `C-u' is bound to the function
! 645: `universal-argument', `M-DEL' is bound to the function
! 646: `backward-kill-word', and `C-o' is bound to run the macro
! 647: expressed on the right hand side (that is, to insert the text
! 648: `> output' into the line).
! 649:
! 650: A number of symbolic character names are recognized while
! 651: processing this key binding syntax: DEL, ESC, ESCAPE, LFD,
! 652: NEWLINE, RET, RETURN, RUBOUT, SPACE, SPC, and TAB.
! 653:
! 654: "KEYSEQ": FUNCTION-NAME or MACRO
! 655: KEYSEQ differs from KEYNAME above in that strings denoting an
! 656: entire key sequence can be specified, by placing the key
! 657: sequence in double quotes. Some GNU Emacs style key escapes
! 658: can be used, as in the following example, but the special
! 659: character names are not recognized.
! 660:
! 661: "\C-u": universal-argument
! 662: "\C-x\C-r": re-read-init-file
! 663: "\e[11~": "Function Key 1"
! 664:
! 665: In the above example, `C-u' is again bound to the function
! 666: `universal-argument' (just as it was in the first example),
! 667: `C-x C-r' is bound to the function `re-read-init-file', and
! 668: `<ESC> <[> <1> <1> <~>' is bound to insert the text `Function
! 669: Key 1'.
! 670:
! 671:
! 672: The following GNU Emacs style escape sequences are available when
! 673: specifying key sequences:
! 674:
! 675: `\C-'
! 676: control prefix
! 677:
! 678: `\M-'
! 679: meta prefix
! 680:
! 681: `\e'
! 682: an escape character
! 683:
! 684: `\\'
! 685: backslash
! 686:
! 687: `\"'
! 688: <">, a double quotation mark
! 689:
! 690: `\''
! 691: <'>, a single quote or apostrophe
! 692:
! 693: In addition to the GNU Emacs style escape sequences, a second set
! 694: of backslash escapes is available:
! 695:
! 696: `\a'
! 697: alert (bell)
! 698:
! 699: `\b'
! 700: backspace
! 701:
! 702: `\d'
! 703: delete
! 704:
! 705: `\f'
! 706: form feed
! 707:
! 708: `\n'
! 709: newline
! 710:
! 711: `\r'
! 712: carriage return
! 713:
! 714: `\t'
! 715: horizontal tab
! 716:
! 717: `\v'
! 718: vertical tab
! 719:
! 720: `\NNN'
! 721: the eight-bit character whose value is the octal value NNN
! 722: (one to three digits)
! 723:
! 724: `\xHH'
! 725: the eight-bit character whose value is the hexadecimal value
! 726: HH (one or two hex digits)
! 727:
! 728: When entering the text of a macro, single or double quotes must be
! 729: used to indicate a macro definition. Unquoted text is assumed to
! 730: be a function name. In the macro body, the backslash escapes
! 731: described above are expanded. Backslash will quote any other
! 732: character in the macro text, including `"' and `''. For example,
! 733: the following binding will make `C-x \' insert a single `\' into
! 734: the line:
! 735: "\C-x\\": "\\"
! 736:
! 737:
! 738:
! 739: File: readline.info, Node: Conditional Init Constructs, Next: Sample Init File, Prev: Readline Init File Syntax, Up: Readline Init File
! 740:
! 741: 1.3.2 Conditional Init Constructs
! 742: ---------------------------------
! 743:
! 744: Readline implements a facility similar in spirit to the conditional
! 745: compilation features of the C preprocessor which allows key bindings
! 746: and variable settings to be performed as the result of tests. There
! 747: are four parser directives used.
! 748:
! 749: `$if'
! 750: The `$if' construct allows bindings to be made based on the
! 751: editing mode, the terminal being used, or the application using
! 752: Readline. The text of the test extends to the end of the line; no
! 753: characters are required to isolate it.
! 754:
! 755: `mode'
! 756: The `mode=' form of the `$if' directive is used to test
! 757: whether Readline is in `emacs' or `vi' mode. This may be
! 758: used in conjunction with the `set keymap' command, for
! 759: instance, to set bindings in the `emacs-standard' and
! 760: `emacs-ctlx' keymaps only if Readline is starting out in
! 761: `emacs' mode.
! 762:
! 763: `term'
! 764: The `term=' form may be used to include terminal-specific key
! 765: bindings, perhaps to bind the key sequences output by the
! 766: terminal's function keys. The word on the right side of the
! 767: `=' is tested against both the full name of the terminal and
! 768: the portion of the terminal name before the first `-'. This
! 769: allows `sun' to match both `sun' and `sun-cmd', for instance.
! 770:
! 771: `application'
! 772: The APPLICATION construct is used to include
! 773: application-specific settings. Each program using the
! 774: Readline library sets the APPLICATION NAME, and you can test
! 775: for a particular value. This could be used to bind key
! 776: sequences to functions useful for a specific program. For
! 777: instance, the following command adds a key sequence that
! 778: quotes the current or previous word in Bash:
! 779: $if Bash
! 780: # Quote the current or previous word
! 781: "\C-xq": "\eb\"\ef\""
! 782: $endif
! 783:
! 784: `$endif'
! 785: This command, as seen in the previous example, terminates an `$if'
! 786: command.
! 787:
! 788: `$else'
! 789: Commands in this branch of the `$if' directive are executed if the
! 790: test fails.
! 791:
! 792: `$include'
! 793: This directive takes a single filename as an argument and reads
! 794: commands and bindings from that file. For example, the following
! 795: directive reads from `/etc/inputrc':
! 796: $include /etc/inputrc
! 797:
! 798:
! 799: File: readline.info, Node: Sample Init File, Prev: Conditional Init Constructs, Up: Readline Init File
! 800:
! 801: 1.3.3 Sample Init File
! 802: ----------------------
! 803:
! 804: Here is an example of an INPUTRC file. This illustrates key binding,
! 805: variable assignment, and conditional syntax.
! 806:
! 807:
! 808: # This file controls the behaviour of line input editing for
! 809: # programs that use the GNU Readline library. Existing
! 810: # programs include FTP, Bash, and GDB.
! 811: #
! 812: # You can re-read the inputrc file with C-x C-r.
! 813: # Lines beginning with '#' are comments.
! 814: #
! 815: # First, include any system-wide bindings and variable
! 816: # assignments from /etc/Inputrc
! 817: $include /etc/Inputrc
! 818:
! 819: #
! 820: # Set various bindings for emacs mode.
! 821:
! 822: set editing-mode emacs
! 823:
! 824: $if mode=emacs
! 825:
! 826: Meta-Control-h: backward-kill-word Text after the function name is ignored
! 827:
! 828: #
! 829: # Arrow keys in keypad mode
! 830: #
! 831: #"\M-OD": backward-char
! 832: #"\M-OC": forward-char
! 833: #"\M-OA": previous-history
! 834: #"\M-OB": next-history
! 835: #
! 836: # Arrow keys in ANSI mode
! 837: #
! 838: "\M-[D": backward-char
! 839: "\M-[C": forward-char
! 840: "\M-[A": previous-history
! 841: "\M-[B": next-history
! 842: #
! 843: # Arrow keys in 8 bit keypad mode
! 844: #
! 845: #"\M-\C-OD": backward-char
! 846: #"\M-\C-OC": forward-char
! 847: #"\M-\C-OA": previous-history
! 848: #"\M-\C-OB": next-history
! 849: #
! 850: # Arrow keys in 8 bit ANSI mode
! 851: #
! 852: #"\M-\C-[D": backward-char
! 853: #"\M-\C-[C": forward-char
! 854: #"\M-\C-[A": previous-history
! 855: #"\M-\C-[B": next-history
! 856:
! 857: C-q: quoted-insert
! 858:
! 859: $endif
! 860:
! 861: # An old-style binding. This happens to be the default.
! 862: TAB: complete
! 863:
! 864: # Macros that are convenient for shell interaction
! 865: $if Bash
! 866: # edit the path
! 867: "\C-xp": "PATH=${PATH}\e\C-e\C-a\ef\C-f"
! 868: # prepare to type a quoted word --
! 869: # insert open and close double quotes
! 870: # and move to just after the open quote
! 871: "\C-x\"": "\"\"\C-b"
! 872: # insert a backslash (testing backslash escapes
! 873: # in sequences and macros)
! 874: "\C-x\\": "\\"
! 875: # Quote the current or previous word
! 876: "\C-xq": "\eb\"\ef\""
! 877: # Add a binding to refresh the line, which is unbound
! 878: "\C-xr": redraw-current-line
! 879: # Edit variable on current line.
! 880: "\M-\C-v": "\C-a\C-k$\C-y\M-\C-e\C-a\C-y="
! 881: $endif
! 882:
! 883: # use a visible bell if one is available
! 884: set bell-style visible
! 885:
! 886: # don't strip characters to 7 bits when reading
! 887: set input-meta on
! 888:
! 889: # allow iso-latin1 characters to be inserted rather
! 890: # than converted to prefix-meta sequences
! 891: set convert-meta off
! 892:
! 893: # display characters with the eighth bit set directly
! 894: # rather than as meta-prefixed characters
! 895: set output-meta on
! 896:
! 897: # if there are more than 150 possible completions for
! 898: # a word, ask the user if he wants to see all of them
! 899: set completion-query-items 150
! 900:
! 901: # For FTP
! 902: $if Ftp
! 903: "\C-xg": "get \M-?"
! 904: "\C-xt": "put \M-?"
! 905: "\M-.": yank-last-arg
! 906: $endif
! 907:
! 908:
! 909: File: readline.info, Node: Bindable Readline Commands, Next: Readline vi Mode, Prev: Readline Init File, Up: Command Line Editing
! 910:
! 911: 1.4 Bindable Readline Commands
! 912: ==============================
! 913:
! 914: * Menu:
! 915:
! 916: * Commands For Moving:: Moving about the line.
! 917: * Commands For History:: Getting at previous lines.
! 918: * Commands For Text:: Commands for changing text.
! 919: * Commands For Killing:: Commands for killing and yanking.
! 920: * Numeric Arguments:: Specifying numeric arguments, repeat counts.
! 921: * Commands For Completion:: Getting Readline to do the typing for you.
! 922: * Keyboard Macros:: Saving and re-executing typed characters
! 923: * Miscellaneous Commands:: Other miscellaneous commands.
! 924:
! 925: This section describes Readline commands that may be bound to key
! 926: sequences. Command names without an accompanying key sequence are
! 927: unbound by default.
! 928:
! 929: In the following descriptions, "point" refers to the current cursor
! 930: position, and "mark" refers to a cursor position saved by the
! 931: `set-mark' command. The text between the point and mark is referred to
! 932: as the "region".
! 933:
! 934:
! 935: File: readline.info, Node: Commands For Moving, Next: Commands For History, Up: Bindable Readline Commands
! 936:
! 937: 1.4.1 Commands For Moving
! 938: -------------------------
! 939:
! 940: `beginning-of-line (C-a)'
! 941: Move to the start of the current line.
! 942:
! 943: `end-of-line (C-e)'
! 944: Move to the end of the line.
! 945:
! 946: `forward-char (C-f)'
! 947: Move forward a character.
! 948:
! 949: `backward-char (C-b)'
! 950: Move back a character.
! 951:
! 952: `forward-word (M-f)'
! 953: Move forward to the end of the next word. Words are composed of
! 954: letters and digits.
! 955:
! 956: `backward-word (M-b)'
! 957: Move back to the start of the current or previous word. Words are
! 958: composed of letters and digits.
! 959:
! 960: `clear-screen (C-l)'
! 961: Clear the screen and redraw the current line, leaving the current
! 962: line at the top of the screen.
! 963:
! 964: `redraw-current-line ()'
! 965: Refresh the current line. By default, this is unbound.
! 966:
! 967:
! 968:
! 969: File: readline.info, Node: Commands For History, Next: Commands For Text, Prev: Commands For Moving, Up: Bindable Readline Commands
! 970:
! 971: 1.4.2 Commands For Manipulating The History
! 972: -------------------------------------------
! 973:
! 974: `accept-line (Newline or Return)'
! 975: Accept the line regardless of where the cursor is. If this line is
! 976: non-empty, it may be added to the history list for future recall
! 977: with `add_history()'. If this line is a modified history line,
! 978: the history line is restored to its original state.
! 979:
! 980: `previous-history (C-p)'
! 981: Move `back' through the history list, fetching the previous
! 982: command.
! 983:
! 984: `next-history (C-n)'
! 985: Move `forward' through the history list, fetching the next command.
! 986:
! 987: `beginning-of-history (M-<)'
! 988: Move to the first line in the history.
! 989:
! 990: `end-of-history (M->)'
! 991: Move to the end of the input history, i.e., the line currently
! 992: being entered.
! 993:
! 994: `reverse-search-history (C-r)'
! 995: Search backward starting at the current line and moving `up'
! 996: through the history as necessary. This is an incremental search.
! 997:
! 998: `forward-search-history (C-s)'
! 999: Search forward starting at the current line and moving `down'
! 1000: through the the history as necessary. This is an incremental
! 1001: search.
! 1002:
! 1003: `non-incremental-reverse-search-history (M-p)'
! 1004: Search backward starting at the current line and moving `up'
! 1005: through the history as necessary using a non-incremental search
! 1006: for a string supplied by the user.
! 1007:
! 1008: `non-incremental-forward-search-history (M-n)'
! 1009: Search forward starting at the current line and moving `down'
! 1010: through the the history as necessary using a non-incremental search
! 1011: for a string supplied by the user.
! 1012:
! 1013: `history-search-forward ()'
! 1014: Search forward through the history for the string of characters
! 1015: between the start of the current line and the point. The search
! 1016: string must match at the beginning of a history line. This is a
! 1017: non-incremental search. By default, this command is unbound.
! 1018:
! 1019: `history-search-backward ()'
! 1020: Search backward through the history for the string of characters
! 1021: between the start of the current line and the point. The search
! 1022: string must match at the beginning of a history line. This is a
! 1023: non-incremental search. By default, this command is unbound.
! 1024:
! 1025: `history-substr-search-forward ()'
! 1026: Search forward through the history for the string of characters
! 1027: between the start of the current line and the point. The search
! 1028: string may match anywhere in a history line. This is a
! 1029: non-incremental search. By default, this command is unbound.
! 1030:
! 1031: `history-substr-search-backward ()'
! 1032: Search backward through the history for the string of characters
! 1033: between the start of the current line and the point. The search
! 1034: string may match anywhere in a history line. This is a
! 1035: non-incremental search. By default, this command is unbound.
! 1036:
! 1037: `yank-nth-arg (M-C-y)'
! 1038: Insert the first argument to the previous command (usually the
! 1039: second word on the previous line) at point. With an argument N,
! 1040: insert the Nth word from the previous command (the words in the
! 1041: previous command begin with word 0). A negative argument inserts
! 1042: the Nth word from the end of the previous command. Once the
! 1043: argument N is computed, the argument is extracted as if the `!N'
! 1044: history expansion had been specified.
! 1045:
! 1046: `yank-last-arg (M-. or M-_)'
! 1047: Insert last argument to the previous command (the last word of the
! 1048: previous history entry). With a numeric argument, behave exactly
! 1049: like `yank-nth-arg'. Successive calls to `yank-last-arg' move
! 1050: back through the history list, inserting the last word (or the
! 1051: word specified by the argument to the first call) of each line in
! 1052: turn. Any numeric argument supplied to these successive calls
! 1053: determines the direction to move through the history. A negative
! 1054: argument switches the direction through the history (back or
! 1055: forward). The history expansion facilities are used to extract
! 1056: the last argument, as if the `!$' history expansion had been
! 1057: specified.
! 1058:
! 1059:
! 1060:
! 1061: File: readline.info, Node: Commands For Text, Next: Commands For Killing, Prev: Commands For History, Up: Bindable Readline Commands
! 1062:
! 1063: 1.4.3 Commands For Changing Text
! 1064: --------------------------------
! 1065:
! 1066: `end-of-file (usually C-d)'
! 1067: The character indicating end-of-file as set, for example, by
! 1068: `stty'. If this character is read when there are no characters on
! 1069: the line, and point is at the beginning of the line, Readline
! 1070: interprets it as the end of input and returns EOF.
! 1071:
! 1072: `delete-char (C-d)'
! 1073: Delete the character at point. If this function is bound to the
! 1074: same character as the tty EOF character, as `C-d' commonly is, see
! 1075: above for the effects.
! 1076:
! 1077: `backward-delete-char (Rubout)'
! 1078: Delete the character behind the cursor. A numeric argument means
! 1079: to kill the characters instead of deleting them.
! 1080:
! 1081: `forward-backward-delete-char ()'
! 1082: Delete the character under the cursor, unless the cursor is at the
! 1083: end of the line, in which case the character behind the cursor is
! 1084: deleted. By default, this is not bound to a key.
! 1085:
! 1086: `quoted-insert (C-q or C-v)'
! 1087: Add the next character typed to the line verbatim. This is how to
! 1088: insert key sequences like `C-q', for example.
! 1089:
! 1090: `tab-insert (M-<TAB>)'
! 1091: Insert a tab character.
! 1092:
! 1093: `self-insert (a, b, A, 1, !, ...)'
! 1094: Insert yourself.
! 1095:
! 1096: `transpose-chars (C-t)'
! 1097: Drag the character before the cursor forward over the character at
! 1098: the cursor, moving the cursor forward as well. If the insertion
! 1099: point is at the end of the line, then this transposes the last two
! 1100: characters of the line. Negative arguments have no effect.
! 1101:
! 1102: `transpose-words (M-t)'
! 1103: Drag the word before point past the word after point, moving point
! 1104: past that word as well. If the insertion point is at the end of
! 1105: the line, this transposes the last two words on the line.
! 1106:
! 1107: `upcase-word (M-u)'
! 1108: Uppercase the current (or following) word. With a negative
! 1109: argument, uppercase the previous word, but do not move the cursor.
! 1110:
! 1111: `downcase-word (M-l)'
! 1112: Lowercase the current (or following) word. With a negative
! 1113: argument, lowercase the previous word, but do not move the cursor.
! 1114:
! 1115: `capitalize-word (M-c)'
! 1116: Capitalize the current (or following) word. With a negative
! 1117: argument, capitalize the previous word, but do not move the cursor.
! 1118:
! 1119: `overwrite-mode ()'
! 1120: Toggle overwrite mode. With an explicit positive numeric argument,
! 1121: switches to overwrite mode. With an explicit non-positive numeric
! 1122: argument, switches to insert mode. This command affects only
! 1123: `emacs' mode; `vi' mode does overwrite differently. Each call to
! 1124: `readline()' starts in insert mode.
! 1125:
! 1126: In overwrite mode, characters bound to `self-insert' replace the
! 1127: text at point rather than pushing the text to the right.
! 1128: Characters bound to `backward-delete-char' replace the character
! 1129: before point with a space.
! 1130:
! 1131: By default, this command is unbound.
! 1132:
! 1133:
! 1134:
! 1135: File: readline.info, Node: Commands For Killing, Next: Numeric Arguments, Prev: Commands For Text, Up: Bindable Readline Commands
! 1136:
! 1137: 1.4.4 Killing And Yanking
! 1138: -------------------------
! 1139:
! 1140: `kill-line (C-k)'
! 1141: Kill the text from point to the end of the line.
! 1142:
! 1143: `backward-kill-line (C-x Rubout)'
! 1144: Kill backward to the beginning of the line.
! 1145:
! 1146: `unix-line-discard (C-u)'
! 1147: Kill backward from the cursor to the beginning of the current line.
! 1148:
! 1149: `kill-whole-line ()'
! 1150: Kill all characters on the current line, no matter where point is.
! 1151: By default, this is unbound.
! 1152:
! 1153: `kill-word (M-d)'
! 1154: Kill from point to the end of the current word, or if between
! 1155: words, to the end of the next word. Word boundaries are the same
! 1156: as `forward-word'.
! 1157:
! 1158: `backward-kill-word (M-<DEL>)'
! 1159: Kill the word behind point. Word boundaries are the same as
! 1160: `backward-word'.
! 1161:
! 1162: `unix-word-rubout (C-w)'
! 1163: Kill the word behind point, using white space as a word boundary.
! 1164: The killed text is saved on the kill-ring.
! 1165:
! 1166: `unix-filename-rubout ()'
! 1167: Kill the word behind point, using white space and the slash
! 1168: character as the word boundaries. The killed text is saved on the
! 1169: kill-ring.
! 1170:
! 1171: `delete-horizontal-space ()'
! 1172: Delete all spaces and tabs around point. By default, this is
! 1173: unbound.
! 1174:
! 1175: `kill-region ()'
! 1176: Kill the text in the current region. By default, this command is
! 1177: unbound.
! 1178:
! 1179: `copy-region-as-kill ()'
! 1180: Copy the text in the region to the kill buffer, so it can be yanked
! 1181: right away. By default, this command is unbound.
! 1182:
! 1183: `copy-backward-word ()'
! 1184: Copy the word before point to the kill buffer. The word
! 1185: boundaries are the same as `backward-word'. By default, this
! 1186: command is unbound.
! 1187:
! 1188: `copy-forward-word ()'
! 1189: Copy the word following point to the kill buffer. The word
! 1190: boundaries are the same as `forward-word'. By default, this
! 1191: command is unbound.
! 1192:
! 1193: `yank (C-y)'
! 1194: Yank the top of the kill ring into the buffer at point.
! 1195:
! 1196: `yank-pop (M-y)'
! 1197: Rotate the kill-ring, and yank the new top. You can only do this
! 1198: if the prior command is `yank' or `yank-pop'.
! 1199:
! 1200:
! 1201: File: readline.info, Node: Numeric Arguments, Next: Commands For Completion, Prev: Commands For Killing, Up: Bindable Readline Commands
! 1202:
! 1203: 1.4.5 Specifying Numeric Arguments
! 1204: ----------------------------------
! 1205:
! 1206: `digit-argument (M-0, M-1, ... M--)'
! 1207: Add this digit to the argument already accumulating, or start a new
! 1208: argument. `M--' starts a negative argument.
! 1209:
! 1210: `universal-argument ()'
! 1211: This is another way to specify an argument. If this command is
! 1212: followed by one or more digits, optionally with a leading minus
! 1213: sign, those digits define the argument. If the command is
! 1214: followed by digits, executing `universal-argument' again ends the
! 1215: numeric argument, but is otherwise ignored. As a special case, if
! 1216: this command is immediately followed by a character that is
! 1217: neither a digit or minus sign, the argument count for the next
! 1218: command is multiplied by four. The argument count is initially
! 1219: one, so executing this function the first time makes the argument
! 1220: count four, a second time makes the argument count sixteen, and so
! 1221: on. By default, this is not bound to a key.
! 1222:
! 1223:
! 1224: File: readline.info, Node: Commands For Completion, Next: Keyboard Macros, Prev: Numeric Arguments, Up: Bindable Readline Commands
! 1225:
! 1226: 1.4.6 Letting Readline Type For You
! 1227: -----------------------------------
! 1228:
! 1229: `complete (<TAB>)'
! 1230: Attempt to perform completion on the text before point. The
! 1231: actual completion performed is application-specific. The default
! 1232: is filename completion.
! 1233:
! 1234: `possible-completions (M-?)'
! 1235: List the possible completions of the text before point. When
! 1236: displaying completions, Readline sets the number of columns used
! 1237: for display to the value of `completion-display-width', the value
! 1238: of the environment variable `COLUMNS', or the screen width, in
! 1239: that order.
! 1240:
! 1241: `insert-completions (M-*)'
! 1242: Insert all completions of the text before point that would have
! 1243: been generated by `possible-completions'.
! 1244:
! 1245: `menu-complete ()'
! 1246: Similar to `complete', but replaces the word to be completed with
! 1247: a single match from the list of possible completions. Repeated
! 1248: execution of `menu-complete' steps through the list of possible
! 1249: completions, inserting each match in turn. At the end of the list
! 1250: of completions, the bell is rung (subject to the setting of
! 1251: `bell-style') and the original text is restored. An argument of N
! 1252: moves N positions forward in the list of matches; a negative
! 1253: argument may be used to move backward through the list. This
! 1254: command is intended to be bound to <TAB>, but is unbound by
! 1255: default.
! 1256:
! 1257: `menu-complete-backward ()'
! 1258: Identical to `menu-complete', but moves backward through the list
! 1259: of possible completions, as if `menu-complete' had been given a
! 1260: negative argument.
! 1261:
! 1262: `delete-char-or-list ()'
! 1263: Deletes the character under the cursor if not at the beginning or
! 1264: end of the line (like `delete-char'). If at the end of the line,
! 1265: behaves identically to `possible-completions'. This command is
! 1266: unbound by default.
! 1267:
! 1268:
! 1269:
! 1270: File: readline.info, Node: Keyboard Macros, Next: Miscellaneous Commands, Prev: Commands For Completion, Up: Bindable Readline Commands
! 1271:
! 1272: 1.4.7 Keyboard Macros
! 1273: ---------------------
! 1274:
! 1275: `start-kbd-macro (C-x ()'
! 1276: Begin saving the characters typed into the current keyboard macro.
! 1277:
! 1278: `end-kbd-macro (C-x ))'
! 1279: Stop saving the characters typed into the current keyboard macro
! 1280: and save the definition.
! 1281:
! 1282: `call-last-kbd-macro (C-x e)'
! 1283: Re-execute the last keyboard macro defined, by making the
! 1284: characters in the macro appear as if typed at the keyboard.
! 1285:
! 1286: `print-last-kbd-macro ()'
! 1287: Print the last keboard macro defined in a format suitable for the
! 1288: INPUTRC file.
! 1289:
! 1290:
! 1291:
! 1292: File: readline.info, Node: Miscellaneous Commands, Prev: Keyboard Macros, Up: Bindable Readline Commands
! 1293:
! 1294: 1.4.8 Some Miscellaneous Commands
! 1295: ---------------------------------
! 1296:
! 1297: `re-read-init-file (C-x C-r)'
! 1298: Read in the contents of the INPUTRC file, and incorporate any
! 1299: bindings or variable assignments found there.
! 1300:
! 1301: `abort (C-g)'
! 1302: Abort the current editing command and ring the terminal's bell
! 1303: (subject to the setting of `bell-style').
! 1304:
! 1305: `do-uppercase-version (M-a, M-b, M-X, ...)'
! 1306: If the metafied character X is lowercase, run the command that is
! 1307: bound to the corresponding uppercase character.
! 1308:
! 1309: `prefix-meta (<ESC>)'
! 1310: Metafy the next character typed. This is for keyboards without a
! 1311: meta key. Typing `<ESC> f' is equivalent to typing `M-f'.
! 1312:
! 1313: `undo (C-_ or C-x C-u)'
! 1314: Incremental undo, separately remembered for each line.
! 1315:
! 1316: `revert-line (M-r)'
! 1317: Undo all changes made to this line. This is like executing the
! 1318: `undo' command enough times to get back to the beginning.
! 1319:
! 1320: `tilde-expand (M-~)'
! 1321: Perform tilde expansion on the current word.
! 1322:
! 1323: `set-mark (C-@)'
! 1324: Set the mark to the point. If a numeric argument is supplied, the
! 1325: mark is set to that position.
! 1326:
! 1327: `exchange-point-and-mark (C-x C-x)'
! 1328: Swap the point with the mark. The current cursor position is set
! 1329: to the saved position, and the old cursor position is saved as the
! 1330: mark.
! 1331:
! 1332: `character-search (C-])'
! 1333: A character is read and point is moved to the next occurrence of
! 1334: that character. A negative count searches for previous
! 1335: occurrences.
! 1336:
! 1337: `character-search-backward (M-C-])'
! 1338: A character is read and point is moved to the previous occurrence
! 1339: of that character. A negative count searches for subsequent
! 1340: occurrences.
! 1341:
! 1342: `skip-csi-sequence ()'
! 1343: Read enough characters to consume a multi-key sequence such as
! 1344: those defined for keys like Home and End. Such sequences begin
! 1345: with a Control Sequence Indicator (CSI), usually ESC-[. If this
! 1346: sequence is bound to "\e[", keys producing such sequences will
! 1347: have no effect unless explicitly bound to a readline command,
! 1348: instead of inserting stray characters into the editing buffer.
! 1349: This is unbound by default, but usually bound to ESC-[.
! 1350:
! 1351: `insert-comment (M-#)'
! 1352: Without a numeric argument, the value of the `comment-begin'
! 1353: variable is inserted at the beginning of the current line. If a
! 1354: numeric argument is supplied, this command acts as a toggle: if
! 1355: the characters at the beginning of the line do not match the value
! 1356: of `comment-begin', the value is inserted, otherwise the
! 1357: characters in `comment-begin' are deleted from the beginning of
! 1358: the line. In either case, the line is accepted as if a newline
! 1359: had been typed.
! 1360:
! 1361: `dump-functions ()'
! 1362: Print all of the functions and their key bindings to the Readline
! 1363: output stream. If a numeric argument is supplied, the output is
! 1364: formatted in such a way that it can be made part of an INPUTRC
! 1365: file. This command is unbound by default.
! 1366:
! 1367: `dump-variables ()'
! 1368: Print all of the settable variables and their values to the
! 1369: Readline output stream. If a numeric argument is supplied, the
! 1370: output is formatted in such a way that it can be made part of an
! 1371: INPUTRC file. This command is unbound by default.
! 1372:
! 1373: `dump-macros ()'
! 1374: Print all of the Readline key sequences bound to macros and the
! 1375: strings they output. If a numeric argument is supplied, the
! 1376: output is formatted in such a way that it can be made part of an
! 1377: INPUTRC file. This command is unbound by default.
! 1378:
! 1379: `emacs-editing-mode (C-e)'
! 1380: When in `vi' command mode, this causes a switch to `emacs' editing
! 1381: mode.
! 1382:
! 1383: `vi-editing-mode (M-C-j)'
! 1384: When in `emacs' editing mode, this causes a switch to `vi' editing
! 1385: mode.
! 1386:
! 1387:
! 1388:
! 1389: File: readline.info, Node: Readline vi Mode, Prev: Bindable Readline Commands, Up: Command Line Editing
! 1390:
! 1391: 1.5 Readline vi Mode
! 1392: ====================
! 1393:
! 1394: While the Readline library does not have a full set of `vi' editing
! 1395: functions, it does contain enough to allow simple editing of the line.
! 1396: The Readline `vi' mode behaves as specified in the POSIX standard.
! 1397:
! 1398: In order to switch interactively between `emacs' and `vi' editing
! 1399: modes, use the command `M-C-j' (bound to emacs-editing-mode when in
! 1400: `vi' mode and to vi-editing-mode in `emacs' mode). The Readline
! 1401: default is `emacs' mode.
! 1402:
! 1403: When you enter a line in `vi' mode, you are already placed in
! 1404: `insertion' mode, as if you had typed an `i'. Pressing <ESC> switches
! 1405: you into `command' mode, where you can edit the text of the line with
! 1406: the standard `vi' movement keys, move to previous history lines with
! 1407: `k' and subsequent lines with `j', and so forth.
! 1408:
! 1409: This document describes the GNU Readline Library, a utility for
! 1410: aiding in the consistency of user interface across discrete programs
! 1411: that need to provide a command line interface.
! 1412:
! 1413: Copyright (C) 1988-2014 Free Software Foundation, Inc.
! 1414:
! 1415: Permission is granted to make and distribute verbatim copies of this
! 1416: manual provided the copyright notice and this permission notice pare
! 1417: preserved on all copies.
! 1418:
! 1419: Permission is granted to copy and distribute modified versions of
! 1420: this manual under the conditions for verbatim copying, provided that
! 1421: the entire resulting derived work is distributed under the terms of a
! 1422: permission notice identical to this one.
! 1423:
! 1424: Permission is granted to copy and distribute translations of this
! 1425: manual into another language, under the above conditions for modified
! 1426: versions, except that this permission notice may be stated in a
! 1427: translation approved by the Foundation.
! 1428:
! 1429:
! 1430: File: readline.info, Node: Programming with GNU Readline, Next: GNU Free Documentation License, Prev: Command Line Editing, Up: Top
! 1431:
! 1432: 2 Programming with GNU Readline
! 1433: *******************************
! 1434:
! 1435: This chapter describes the interface between the GNU Readline Library
! 1436: and other programs. If you are a programmer, and you wish to include
! 1437: the features found in GNU Readline such as completion, line editing,
! 1438: and interactive history manipulation in your own programs, this section
! 1439: is for you.
! 1440:
! 1441: * Menu:
! 1442:
! 1443: * Basic Behavior:: Using the default behavior of Readline.
! 1444: * Custom Functions:: Adding your own functions to Readline.
! 1445: * Readline Variables:: Variables accessible to custom
! 1446: functions.
! 1447: * Readline Convenience Functions:: Functions which Readline supplies to
! 1448: aid in writing your own custom
! 1449: functions.
! 1450: * Readline Signal Handling:: How Readline behaves when it receives signals.
! 1451: * Custom Completers:: Supplanting or supplementing Readline's
! 1452: completion functions.
! 1453:
! 1454:
! 1455: File: readline.info, Node: Basic Behavior, Next: Custom Functions, Up: Programming with GNU Readline
! 1456:
! 1457: 2.1 Basic Behavior
! 1458: ==================
! 1459:
! 1460: Many programs provide a command line interface, such as `mail', `ftp',
! 1461: and `sh'. For such programs, the default behaviour of Readline is
! 1462: sufficient. This section describes how to use Readline in the simplest
! 1463: way possible, perhaps to replace calls in your code to `gets()' or
! 1464: `fgets()'.
! 1465:
! 1466: The function `readline()' prints a prompt PROMPT and then reads and
! 1467: returns a single line of text from the user. If PROMPT is `NULL' or
! 1468: the empty string, no prompt is displayed. The line `readline' returns
! 1469: is allocated with `malloc()'; the caller should `free()' the line when
! 1470: it has finished with it. The declaration for `readline' in ANSI C is
! 1471:
! 1472: `char *readline (const char *PROMPT);'
! 1473:
! 1474: So, one might say
! 1475: `char *line = readline ("Enter a line: ");'
! 1476: in order to read a line of text from the user. The line returned
! 1477: has the final newline removed, so only the text remains.
! 1478:
! 1479: If `readline' encounters an `EOF' while reading the line, and the
! 1480: line is empty at that point, then `(char *)NULL' is returned.
! 1481: Otherwise, the line is ended just as if a newline had been typed.
! 1482:
! 1483: If you want the user to be able to get at the line later, (with
! 1484: <C-p> for example), you must call `add_history()' to save the line away
! 1485: in a "history" list of such lines.
! 1486:
! 1487: `add_history (line)';
! 1488:
! 1489: For full details on the GNU History Library, see the associated manual.
! 1490:
! 1491: It is preferable to avoid saving empty lines on the history list,
! 1492: since users rarely have a burning need to reuse a blank line. Here is
! 1493: a function which usefully replaces the standard `gets()' library
! 1494: function, and has the advantage of no static buffer to overflow:
! 1495:
! 1496: /* A static variable for holding the line. */
! 1497: static char *line_read = (char *)NULL;
! 1498:
! 1499: /* Read a string, and return a pointer to it.
! 1500: Returns NULL on EOF. */
! 1501: char *
! 1502: rl_gets ()
! 1503: {
! 1504: /* If the buffer has already been allocated,
! 1505: return the memory to the free pool. */
! 1506: if (line_read)
! 1507: {
! 1508: free (line_read);
! 1509: line_read = (char *)NULL;
! 1510: }
! 1511:
! 1512: /* Get a line from the user. */
! 1513: line_read = readline ("");
! 1514:
! 1515: /* If the line has any text in it,
! 1516: save it on the history. */
! 1517: if (line_read && *line_read)
! 1518: add_history (line_read);
! 1519:
! 1520: return (line_read);
! 1521: }
! 1522:
! 1523: This function gives the user the default behaviour of <TAB>
! 1524: completion: completion on file names. If you do not want Readline to
! 1525: complete on filenames, you can change the binding of the <TAB> key with
! 1526: `rl_bind_key()'.
! 1527:
! 1528: `int rl_bind_key (int KEY, rl_command_func_t *FUNCTION);'
! 1529:
! 1530: `rl_bind_key()' takes two arguments: KEY is the character that you
! 1531: want to bind, and FUNCTION is the address of the function to call when
! 1532: KEY is pressed. Binding <TAB> to `rl_insert()' makes <TAB> insert
! 1533: itself. `rl_bind_key()' returns non-zero if KEY is not a valid ASCII
! 1534: character code (between 0 and 255).
! 1535:
! 1536: Thus, to disable the default <TAB> behavior, the following suffices:
! 1537: `rl_bind_key ('\t', rl_insert);'
! 1538:
! 1539: This code should be executed once at the start of your program; you
! 1540: might write a function called `initialize_readline()' which performs
! 1541: this and other desired initializations, such as installing custom
! 1542: completers (*note Custom Completers::).
! 1543:
! 1544:
! 1545: File: readline.info, Node: Custom Functions, Next: Readline Variables, Prev: Basic Behavior, Up: Programming with GNU Readline
! 1546:
! 1547: 2.2 Custom Functions
! 1548: ====================
! 1549:
! 1550: Readline provides many functions for manipulating the text of the line,
! 1551: but it isn't possible to anticipate the needs of all programs. This
! 1552: section describes the various functions and variables defined within
! 1553: the Readline library which allow a user program to add customized
! 1554: functionality to Readline.
! 1555:
! 1556: Before declaring any functions that customize Readline's behavior, or
! 1557: using any functionality Readline provides in other code, an application
! 1558: writer should include the file `<readline/readline.h>' in any file that
! 1559: uses Readline's features. Since some of the definitions in
! 1560: `readline.h' use the `stdio' library, the file `<stdio.h>' should be
! 1561: included before `readline.h'.
! 1562:
! 1563: `readline.h' defines a C preprocessor variable that should be
! 1564: treated as an integer, `RL_READLINE_VERSION', which may be used to
! 1565: conditionally compile application code depending on the installed
! 1566: Readline version. The value is a hexadecimal encoding of the major and
! 1567: minor version numbers of the library, of the form 0xMMMM. MM is the
! 1568: two-digit major version number; MM is the two-digit minor version
! 1569: number. For Readline 4.2, for example, the value of
! 1570: `RL_READLINE_VERSION' would be `0x0402'.
! 1571:
! 1572: * Menu:
! 1573:
! 1574: * Readline Typedefs:: C declarations to make code readable.
! 1575: * Function Writing:: Variables and calling conventions.
! 1576:
! 1577:
! 1578: File: readline.info, Node: Readline Typedefs, Next: Function Writing, Up: Custom Functions
! 1579:
! 1580: 2.2.1 Readline Typedefs
! 1581: -----------------------
! 1582:
! 1583: For readability, we declare a number of new object types, all pointers
! 1584: to functions.
! 1585:
! 1586: The reason for declaring these new types is to make it easier to
! 1587: write code describing pointers to C functions with appropriately
! 1588: prototyped arguments and return values.
! 1589:
! 1590: For instance, say we want to declare a variable FUNC as a pointer to
! 1591: a function which takes two `int' arguments and returns an `int' (this
! 1592: is the type of all of the Readline bindable functions). Instead of the
! 1593: classic C declaration
! 1594:
! 1595: `int (*func)();'
! 1596:
! 1597: or the ANSI-C style declaration
! 1598:
! 1599: `int (*func)(int, int);'
! 1600:
! 1601: we may write
! 1602:
! 1603: `rl_command_func_t *func;'
! 1604:
! 1605: The full list of function pointer types available is
! 1606:
! 1607: `typedef int rl_command_func_t (int, int);'
! 1608:
! 1609: `typedef char *rl_compentry_func_t (const char *, int);'
! 1610:
! 1611: `typedef char **rl_completion_func_t (const char *, int, int);'
! 1612:
! 1613: `typedef char *rl_quote_func_t (char *, int, char *);'
! 1614:
! 1615: `typedef char *rl_dequote_func_t (char *, int);'
! 1616:
! 1617: `typedef int rl_compignore_func_t (char **);'
! 1618:
! 1619: `typedef void rl_compdisp_func_t (char **, int, int);'
! 1620:
! 1621: `typedef int rl_hook_func_t (void);'
! 1622:
! 1623: `typedef int rl_getc_func_t (FILE *);'
! 1624:
! 1625: `typedef int rl_linebuf_func_t (char *, int);'
! 1626:
! 1627: `typedef int rl_intfunc_t (int);'
! 1628:
! 1629: `#define rl_ivoidfunc_t rl_hook_func_t'
! 1630:
! 1631: `typedef int rl_icpfunc_t (char *);'
! 1632:
! 1633: `typedef int rl_icppfunc_t (char **);'
! 1634:
! 1635: `typedef void rl_voidfunc_t (void);'
! 1636:
! 1637: `typedef void rl_vintfunc_t (int);'
! 1638:
! 1639: `typedef void rl_vcpfunc_t (char *);'
! 1640:
! 1641: `typedef void rl_vcppfunc_t (char **);'
! 1642:
! 1643:
! 1644: File: readline.info, Node: Function Writing, Prev: Readline Typedefs, Up: Custom Functions
! 1645:
! 1646: 2.2.2 Writing a New Function
! 1647: ----------------------------
! 1648:
! 1649: In order to write new functions for Readline, you need to know the
! 1650: calling conventions for keyboard-invoked functions, and the names of the
! 1651: variables that describe the current state of the line read so far.
! 1652:
! 1653: The calling sequence for a command `foo' looks like
! 1654:
! 1655: `int foo (int count, int key)'
! 1656:
! 1657: where COUNT is the numeric argument (or 1 if defaulted) and KEY is the
! 1658: key that invoked this function.
! 1659:
! 1660: It is completely up to the function as to what should be done with
! 1661: the numeric argument. Some functions use it as a repeat count, some as
! 1662: a flag, and others to choose alternate behavior (refreshing the current
! 1663: line as opposed to refreshing the screen, for example). Some choose to
! 1664: ignore it. In general, if a function uses the numeric argument as a
! 1665: repeat count, it should be able to do something useful with both
! 1666: negative and positive arguments. At the very least, it should be aware
! 1667: that it can be passed a negative argument.
! 1668:
! 1669: A command function should return 0 if its action completes
! 1670: successfully, and a non-zero value if some error occurs. This is the
! 1671: convention obeyed by all of the builtin Readline bindable command
! 1672: functions.
! 1673:
! 1674:
! 1675: File: readline.info, Node: Readline Variables, Next: Readline Convenience Functions, Prev: Custom Functions, Up: Programming with GNU Readline
! 1676:
! 1677: 2.3 Readline Variables
! 1678: ======================
! 1679:
! 1680: These variables are available to function writers.
! 1681:
! 1682: -- Variable: char * rl_line_buffer
! 1683: This is the line gathered so far. You are welcome to modify the
! 1684: contents of the line, but see *note Allowing Undoing::. The
! 1685: function `rl_extend_line_buffer' is available to increase the
! 1686: memory allocated to `rl_line_buffer'.
! 1687:
! 1688: -- Variable: int rl_point
! 1689: The offset of the current cursor position in `rl_line_buffer' (the
! 1690: _point_).
! 1691:
! 1692: -- Variable: int rl_end
! 1693: The number of characters present in `rl_line_buffer'. When
! 1694: `rl_point' is at the end of the line, `rl_point' and `rl_end' are
! 1695: equal.
! 1696:
! 1697: -- Variable: int rl_mark
! 1698: The MARK (saved position) in the current line. If set, the mark
! 1699: and point define a _region_.
! 1700:
! 1701: -- Variable: int rl_done
! 1702: Setting this to a non-zero value causes Readline to return the
! 1703: current line immediately.
! 1704:
! 1705: -- Variable: int rl_num_chars_to_read
! 1706: Setting this to a positive value before calling `readline()' causes
! 1707: Readline to return after accepting that many characters, rather
! 1708: than reading up to a character bound to `accept-line'.
! 1709:
! 1710: -- Variable: int rl_pending_input
! 1711: Setting this to a value makes it the next keystroke read. This is
! 1712: a way to stuff a single character into the input stream.
! 1713:
! 1714: -- Variable: int rl_dispatching
! 1715: Set to a non-zero value if a function is being called from a key
! 1716: binding; zero otherwise. Application functions can test this to
! 1717: discover whether they were called directly or by Readline's
! 1718: dispatching mechanism.
! 1719:
! 1720: -- Variable: int rl_erase_empty_line
! 1721: Setting this to a non-zero value causes Readline to completely
! 1722: erase the current line, including any prompt, any time a newline
! 1723: is typed as the only character on an otherwise-empty line. The
! 1724: cursor is moved to the beginning of the newly-blank line.
! 1725:
! 1726: -- Variable: char * rl_prompt
! 1727: The prompt Readline uses. This is set from the argument to
! 1728: `readline()', and should not be assigned to directly. The
! 1729: `rl_set_prompt()' function (*note Redisplay::) may be used to
! 1730: modify the prompt string after calling `readline()'.
! 1731:
! 1732: -- Variable: char * rl_display_prompt
! 1733: The string displayed as the prompt. This is usually identical to
! 1734: RL_PROMPT, but may be changed temporarily by functions that use
! 1735: the prompt string as a message area, such as incremental search.
! 1736:
! 1737: -- Variable: int rl_already_prompted
! 1738: If an application wishes to display the prompt itself, rather than
! 1739: have Readline do it the first time `readline()' is called, it
! 1740: should set this variable to a non-zero value after displaying the
! 1741: prompt. The prompt must also be passed as the argument to
! 1742: `readline()' so the redisplay functions can update the display
! 1743: properly. The calling application is responsible for managing the
! 1744: value; Readline never sets it.
! 1745:
! 1746: -- Variable: const char * rl_library_version
! 1747: The version number of this revision of the library.
! 1748:
! 1749: -- Variable: int rl_readline_version
! 1750: An integer encoding the current version of the library. The
! 1751: encoding is of the form 0xMMMM, where MM is the two-digit major
! 1752: version number, and MM is the two-digit minor version number. For
! 1753: example, for Readline-4.2, `rl_readline_version' would have the
! 1754: value 0x0402.
! 1755:
! 1756: -- Variable: int rl_gnu_readline_p
! 1757: Always set to 1, denoting that this is GNU readline rather than
! 1758: some emulation.
! 1759:
! 1760: -- Variable: const char * rl_terminal_name
! 1761: The terminal type, used for initialization. If not set by the
! 1762: application, Readline sets this to the value of the `TERM'
! 1763: environment variable the first time it is called.
! 1764:
! 1765: -- Variable: const char * rl_readline_name
! 1766: This variable is set to a unique name by each application using
! 1767: Readline. The value allows conditional parsing of the inputrc file
! 1768: (*note Conditional Init Constructs::).
! 1769:
! 1770: -- Variable: FILE * rl_instream
! 1771: The stdio stream from which Readline reads input. If `NULL',
! 1772: Readline defaults to STDIN.
! 1773:
! 1774: -- Variable: FILE * rl_outstream
! 1775: The stdio stream to which Readline performs output. If `NULL',
! 1776: Readline defaults to STDOUT.
! 1777:
! 1778: -- Variable: int rl_prefer_env_winsize
! 1779: If non-zero, Readline gives values found in the `LINES' and
! 1780: `COLUMNS' environment variables greater precedence than values
! 1781: fetched from the kernel when computing the screen dimensions.
! 1782:
! 1783: -- Variable: rl_command_func_t * rl_last_func
! 1784: The address of the last command function Readline executed. May
! 1785: be used to test whether or not a function is being executed twice
! 1786: in succession, for example.
! 1787:
! 1788: -- Variable: rl_hook_func_t * rl_startup_hook
! 1789: If non-zero, this is the address of a function to call just before
! 1790: `readline' prints the first prompt.
! 1791:
! 1792: -- Variable: rl_hook_func_t * rl_pre_input_hook
! 1793: If non-zero, this is the address of a function to call after the
! 1794: first prompt has been printed and just before `readline' starts
! 1795: reading input characters.
! 1796:
! 1797: -- Variable: rl_hook_func_t * rl_event_hook
! 1798: If non-zero, this is the address of a function to call periodically
! 1799: when Readline is waiting for terminal input. By default, this
! 1800: will be called at most ten times a second if there is no keyboard
! 1801: input.
! 1802:
! 1803: -- Variable: rl_getc_func_t * rl_getc_function
! 1804: If non-zero, Readline will call indirectly through this pointer to
! 1805: get a character from the input stream. By default, it is set to
! 1806: `rl_getc', the default Readline character input function (*note
! 1807: Character Input::). In general, an application that sets
! 1808: RL_GETC_FUNCTION should consider setting RL_INPUT_AVAILABLE_HOOK
! 1809: as well.
! 1810:
! 1811: -- Variable: rl_hook_func_t * rl_signal_event_hook
! 1812: If non-zero, this is the address of a function to call if a read
! 1813: system call is interrupted when Readline is reading terminal input.
! 1814:
! 1815: -- Variable: rl_hook_func_t * rl_input_available_hook
! 1816: If non-zero, Readline will use this function's return value when
! 1817: it needs to determine whether or not there is available input on
! 1818: the current input source. The default hook checks `rl_instream';
! 1819: if an application is using a different input source, it should set
! 1820: the hook appropriately. Readline queries for available input when
! 1821: implementing intra-key-sequence timeouts during input and
! 1822: incremental searches. This may use an application-specific
! 1823: timeout before returning a value; Readline uses the value passed
! 1824: to `rl_set_keyboard_input_timeout()' or the value of the
! 1825: user-settable KEYSEQ-TIMEOUT variable. This is designed for use
! 1826: by applications using Readline's callback interface (*note
! 1827: Alternate Interface::), which may not use the traditional
! 1828: `read(2)' and file descriptor interface, or other applications
! 1829: using a different input mechanism. If an application uses an
! 1830: input mechanism or hook that can potentially exceed the value of
! 1831: KEYSEQ-TIMEOUT, it should increase the timeout or set this hook
! 1832: appropriately even when not using the callback interface. In
! 1833: general, an application that sets RL_GETC_FUNCTION should consider
! 1834: setting RL_INPUT_AVAILABLE_HOOK as well.
! 1835:
! 1836: -- Variable: rl_voidfunc_t * rl_redisplay_function
! 1837: If non-zero, Readline will call indirectly through this pointer to
! 1838: update the display with the current contents of the editing buffer.
! 1839: By default, it is set to `rl_redisplay', the default Readline
! 1840: redisplay function (*note Redisplay::).
! 1841:
! 1842: -- Variable: rl_vintfunc_t * rl_prep_term_function
! 1843: If non-zero, Readline will call indirectly through this pointer to
! 1844: initialize the terminal. The function takes a single argument, an
! 1845: `int' flag that says whether or not to use eight-bit characters.
! 1846: By default, this is set to `rl_prep_terminal' (*note Terminal
! 1847: Management::).
! 1848:
! 1849: -- Variable: rl_voidfunc_t * rl_deprep_term_function
! 1850: If non-zero, Readline will call indirectly through this pointer to
! 1851: reset the terminal. This function should undo the effects of
! 1852: `rl_prep_term_function'. By default, this is set to
! 1853: `rl_deprep_terminal' (*note Terminal Management::).
! 1854:
! 1855: -- Variable: Keymap rl_executing_keymap
! 1856: This variable is set to the keymap (*note Keymaps::) in which the
! 1857: currently executing readline function was found.
! 1858:
! 1859: -- Variable: Keymap rl_binding_keymap
! 1860: This variable is set to the keymap (*note Keymaps::) in which the
! 1861: last key binding occurred.
! 1862:
! 1863: -- Variable: char * rl_executing_macro
! 1864: This variable is set to the text of any currently-executing macro.
! 1865:
! 1866: -- Variable: int rl_executing_key
! 1867: The key that caused the dispatch to the currently-executing
! 1868: Readline function.
! 1869:
! 1870: -- Variable: char * rl_executing_keyseq
! 1871: The full key sequence that caused the dispatch to the
! 1872: currently-executing Readline function.
! 1873:
! 1874: -- Variable: int rl_key_sequence_length
! 1875: The number of characters in RL_EXECUTING_KEYSEQ.
! 1876:
! 1877: -- Variable: int rl_readline_state
! 1878: A variable with bit values that encapsulate the current Readline
! 1879: state. A bit is set with the `RL_SETSTATE' macro, and unset with
! 1880: the `RL_UNSETSTATE' macro. Use the `RL_ISSTATE' macro to test
! 1881: whether a particular state bit is set. Current state bits include:
! 1882:
! 1883: `RL_STATE_NONE'
! 1884: Readline has not yet been called, nor has it begun to
! 1885: initialize.
! 1886:
! 1887: `RL_STATE_INITIALIZING'
! 1888: Readline is initializing its internal data structures.
! 1889:
! 1890: `RL_STATE_INITIALIZED'
! 1891: Readline has completed its initialization.
! 1892:
! 1893: `RL_STATE_TERMPREPPED'
! 1894: Readline has modified the terminal modes to do its own input
! 1895: and redisplay.
! 1896:
! 1897: `RL_STATE_READCMD'
! 1898: Readline is reading a command from the keyboard.
! 1899:
! 1900: `RL_STATE_METANEXT'
! 1901: Readline is reading more input after reading the meta-prefix
! 1902: character.
! 1903:
! 1904: `RL_STATE_DISPATCHING'
! 1905: Readline is dispatching to a command.
! 1906:
! 1907: `RL_STATE_MOREINPUT'
! 1908: Readline is reading more input while executing an editing
! 1909: command.
! 1910:
! 1911: `RL_STATE_ISEARCH'
! 1912: Readline is performing an incremental history search.
! 1913:
! 1914: `RL_STATE_NSEARCH'
! 1915: Readline is performing a non-incremental history search.
! 1916:
! 1917: `RL_STATE_SEARCH'
! 1918: Readline is searching backward or forward through the history
! 1919: for a string.
! 1920:
! 1921: `RL_STATE_NUMERICARG'
! 1922: Readline is reading a numeric argument.
! 1923:
! 1924: `RL_STATE_MACROINPUT'
! 1925: Readline is currently getting its input from a
! 1926: previously-defined keyboard macro.
! 1927:
! 1928: `RL_STATE_MACRODEF'
! 1929: Readline is currently reading characters defining a keyboard
! 1930: macro.
! 1931:
! 1932: `RL_STATE_OVERWRITE'
! 1933: Readline is in overwrite mode.
! 1934:
! 1935: `RL_STATE_COMPLETING'
! 1936: Readline is performing word completion.
! 1937:
! 1938: `RL_STATE_SIGHANDLER'
! 1939: Readline is currently executing the readline signal handler.
! 1940:
! 1941: `RL_STATE_UNDOING'
! 1942: Readline is performing an undo.
! 1943:
! 1944: `RL_STATE_INPUTPENDING'
! 1945: Readline has input pending due to a call to
! 1946: `rl_execute_next()'.
! 1947:
! 1948: `RL_STATE_TTYCSAVED'
! 1949: Readline has saved the values of the terminal's special
! 1950: characters.
! 1951:
! 1952: `RL_STATE_CALLBACK'
! 1953: Readline is currently using the alternate (callback) interface
! 1954: (*note Alternate Interface::).
! 1955:
! 1956: `RL_STATE_VIMOTION'
! 1957: Readline is reading the argument to a vi-mode "motion"
! 1958: command.
! 1959:
! 1960: `RL_STATE_MULTIKEY'
! 1961: Readline is reading a multiple-keystroke command.
! 1962:
! 1963: `RL_STATE_VICMDONCE'
! 1964: Readline has entered vi command (movement) mode at least one
! 1965: time during the current call to `readline()'.
! 1966:
! 1967: `RL_STATE_DONE'
! 1968: Readline has read a key sequence bound to `accept-line' and
! 1969: is about to return the line to the caller.
! 1970:
! 1971:
! 1972: -- Variable: int rl_explicit_arg
! 1973: Set to a non-zero value if an explicit numeric argument was
! 1974: specified by the user. Only valid in a bindable command function.
! 1975:
! 1976: -- Variable: int rl_numeric_arg
! 1977: Set to the value of any numeric argument explicitly specified by
! 1978: the user before executing the current Readline function. Only
! 1979: valid in a bindable command function.
! 1980:
! 1981: -- Variable: int rl_editing_mode
! 1982: Set to a value denoting Readline's current editing mode. A value
! 1983: of 1 means Readline is currently in emacs mode; 0 means that vi
! 1984: mode is active.
! 1985:
! 1986:
! 1987: File: readline.info, Node: Readline Convenience Functions, Next: Readline Signal Handling, Prev: Readline Variables, Up: Programming with GNU Readline
! 1988:
! 1989: 2.4 Readline Convenience Functions
! 1990: ==================================
! 1991:
! 1992: * Menu:
! 1993:
! 1994: * Function Naming:: How to give a function you write a name.
! 1995: * Keymaps:: Making keymaps.
! 1996: * Binding Keys:: Changing Keymaps.
! 1997: * Associating Function Names and Bindings:: Translate function names to
! 1998: key sequences.
! 1999: * Allowing Undoing:: How to make your functions undoable.
! 2000: * Redisplay:: Functions to control line display.
! 2001: * Modifying Text:: Functions to modify `rl_line_buffer'.
! 2002: * Character Input:: Functions to read keyboard input.
! 2003: * Terminal Management:: Functions to manage terminal settings.
! 2004: * Utility Functions:: Generally useful functions and hooks.
! 2005: * Miscellaneous Functions:: Functions that don't fall into any category.
! 2006: * Alternate Interface:: Using Readline in a `callback' fashion.
! 2007: * A Readline Example:: An example Readline function.
! 2008: * Alternate Interface Example:: An example program using the alternate interface.
! 2009:
! 2010:
! 2011: File: readline.info, Node: Function Naming, Next: Keymaps, Up: Readline Convenience Functions
! 2012:
! 2013: 2.4.1 Naming a Function
! 2014: -----------------------
! 2015:
! 2016: The user can dynamically change the bindings of keys while using
! 2017: Readline. This is done by representing the function with a descriptive
! 2018: name. The user is able to type the descriptive name when referring to
! 2019: the function. Thus, in an init file, one might find
! 2020:
! 2021: Meta-Rubout: backward-kill-word
! 2022:
! 2023: This binds the keystroke <Meta-Rubout> to the function
! 2024: _descriptively_ named `backward-kill-word'. You, as the programmer,
! 2025: should bind the functions you write to descriptive names as well.
! 2026: Readline provides a function for doing that:
! 2027:
! 2028: -- Function: int rl_add_defun (const char *name, rl_command_func_t
! 2029: *function, int key)
! 2030: Add NAME to the list of named functions. Make FUNCTION be the
! 2031: function that gets called. If KEY is not -1, then bind it to
! 2032: FUNCTION using `rl_bind_key()'.
! 2033:
! 2034: Using this function alone is sufficient for most applications. It
! 2035: is the recommended way to add a few functions to the default functions
! 2036: that Readline has built in. If you need to do something other than
! 2037: adding a function to Readline, you may need to use the underlying
! 2038: functions described below.
! 2039:
! 2040:
! 2041: File: readline.info, Node: Keymaps, Next: Binding Keys, Prev: Function Naming, Up: Readline Convenience Functions
! 2042:
! 2043: 2.4.2 Selecting a Keymap
! 2044: ------------------------
! 2045:
! 2046: Key bindings take place on a "keymap". The keymap is the association
! 2047: between the keys that the user types and the functions that get run.
! 2048: You can make your own keymaps, copy existing keymaps, and tell Readline
! 2049: which keymap to use.
! 2050:
! 2051: -- Function: Keymap rl_make_bare_keymap (void)
! 2052: Returns a new, empty keymap. The space for the keymap is
! 2053: allocated with `malloc()'; the caller should free it by calling
! 2054: `rl_free_keymap()' when done.
! 2055:
! 2056: -- Function: Keymap rl_copy_keymap (Keymap map)
! 2057: Return a new keymap which is a copy of MAP.
! 2058:
! 2059: -- Function: Keymap rl_make_keymap (void)
! 2060: Return a new keymap with the printing characters bound to
! 2061: rl_insert, the lowercase Meta characters bound to run their
! 2062: equivalents, and the Meta digits bound to produce numeric
! 2063: arguments.
! 2064:
! 2065: -- Function: void rl_discard_keymap (Keymap keymap)
! 2066: Free the storage associated with the data in KEYMAP. The caller
! 2067: should free KEYMAP.
! 2068:
! 2069: -- Function: void rl_free_keymap (Keymap keymap)
! 2070: Free all storage associated with KEYMAP. This calls
! 2071: `rl_discard_keymap' to free subordindate keymaps and macros.
! 2072:
! 2073: Readline has several internal keymaps. These functions allow you to
! 2074: change which keymap is active.
! 2075:
! 2076: -- Function: Keymap rl_get_keymap (void)
! 2077: Returns the currently active keymap.
! 2078:
! 2079: -- Function: void rl_set_keymap (Keymap keymap)
! 2080: Makes KEYMAP the currently active keymap.
! 2081:
! 2082: -- Function: Keymap rl_get_keymap_by_name (const char *name)
! 2083: Return the keymap matching NAME. NAME is one which would be
! 2084: supplied in a `set keymap' inputrc line (*note Readline Init
! 2085: File::).
! 2086:
! 2087: -- Function: char * rl_get_keymap_name (Keymap keymap)
! 2088: Return the name matching KEYMAP. NAME is one which would be
! 2089: supplied in a `set keymap' inputrc line (*note Readline Init
! 2090: File::).
! 2091:
! 2092:
! 2093: File: readline.info, Node: Binding Keys, Next: Associating Function Names and Bindings, Prev: Keymaps, Up: Readline Convenience Functions
! 2094:
! 2095: 2.4.3 Binding Keys
! 2096: ------------------
! 2097:
! 2098: Key sequences are associate with functions through the keymap.
! 2099: Readline has several internal keymaps: `emacs_standard_keymap',
! 2100: `emacs_meta_keymap', `emacs_ctlx_keymap', `vi_movement_keymap', and
! 2101: `vi_insertion_keymap'. `emacs_standard_keymap' is the default, and the
! 2102: examples in this manual assume that.
! 2103:
! 2104: Since `readline()' installs a set of default key bindings the first
! 2105: time it is called, there is always the danger that a custom binding
! 2106: installed before the first call to `readline()' will be overridden. An
! 2107: alternate mechanism is to install custom key bindings in an
! 2108: initialization function assigned to the `rl_startup_hook' variable
! 2109: (*note Readline Variables::).
! 2110:
! 2111: These functions manage key bindings.
! 2112:
! 2113: -- Function: int rl_bind_key (int key, rl_command_func_t *function)
! 2114: Binds KEY to FUNCTION in the currently active keymap. Returns
! 2115: non-zero in the case of an invalid KEY.
! 2116:
! 2117: -- Function: int rl_bind_key_in_map (int key, rl_command_func_t
! 2118: *function, Keymap map)
! 2119: Bind KEY to FUNCTION in MAP. Returns non-zero in the case of an
! 2120: invalid KEY.
! 2121:
! 2122: -- Function: int rl_bind_key_if_unbound (int key, rl_command_func_t
! 2123: *function)
! 2124: Binds KEY to FUNCTION if it is not already bound in the currently
! 2125: active keymap. Returns non-zero in the case of an invalid KEY or
! 2126: if KEY is already bound.
! 2127:
! 2128: -- Function: int rl_bind_key_if_unbound_in_map (int key,
! 2129: rl_command_func_t *function, Keymap map)
! 2130: Binds KEY to FUNCTION if it is not already bound in MAP. Returns
! 2131: non-zero in the case of an invalid KEY or if KEY is already bound.
! 2132:
! 2133: -- Function: int rl_unbind_key (int key)
! 2134: Bind KEY to the null function in the currently active keymap.
! 2135: Returns non-zero in case of error.
! 2136:
! 2137: -- Function: int rl_unbind_key_in_map (int key, Keymap map)
! 2138: Bind KEY to the null function in MAP. Returns non-zero in case of
! 2139: error.
! 2140:
! 2141: -- Function: int rl_unbind_function_in_map (rl_command_func_t
! 2142: *function, Keymap map)
! 2143: Unbind all keys that execute FUNCTION in MAP.
! 2144:
! 2145: -- Function: int rl_unbind_command_in_map (const char *command, Keymap
! 2146: map)
! 2147: Unbind all keys that are bound to COMMAND in MAP.
! 2148:
! 2149: -- Function: int rl_bind_keyseq (const char *keyseq, rl_command_func_t
! 2150: *function)
! 2151: Bind the key sequence represented by the string KEYSEQ to the
! 2152: function FUNCTION, beginning in the current keymap. This makes
! 2153: new keymaps as necessary. The return value is non-zero if KEYSEQ
! 2154: is invalid.
! 2155:
! 2156: -- Function: int rl_bind_keyseq_in_map (const char *keyseq,
! 2157: rl_command_func_t *function, Keymap map)
! 2158: Bind the key sequence represented by the string KEYSEQ to the
! 2159: function FUNCTION. This makes new keymaps as necessary. Initial
! 2160: bindings are performed in MAP. The return value is non-zero if
! 2161: KEYSEQ is invalid.
! 2162:
! 2163: -- Function: int rl_set_key (const char *keyseq, rl_command_func_t
! 2164: *function, Keymap map)
! 2165: Equivalent to `rl_bind_keyseq_in_map'.
! 2166:
! 2167: -- Function: int rl_bind_keyseq_if_unbound (const char *keyseq,
! 2168: rl_command_func_t *function)
! 2169: Binds KEYSEQ to FUNCTION if it is not already bound in the
! 2170: currently active keymap. Returns non-zero in the case of an
! 2171: invalid KEYSEQ or if KEYSEQ is already bound.
! 2172:
! 2173: -- Function: int rl_bind_keyseq_if_unbound_in_map (const char *keyseq,
! 2174: rl_command_func_t *function, Keymap map)
! 2175: Binds KEYSEQ to FUNCTION if it is not already bound in MAP.
! 2176: Returns non-zero in the case of an invalid KEYSEQ or if KEYSEQ is
! 2177: already bound.
! 2178:
! 2179: -- Function: int rl_generic_bind (int type, const char *keyseq, char
! 2180: *data, Keymap map)
! 2181: Bind the key sequence represented by the string KEYSEQ to the
! 2182: arbitrary pointer DATA. TYPE says what kind of data is pointed to
! 2183: by DATA; this can be a function (`ISFUNC'), a macro (`ISMACR'), or
! 2184: a keymap (`ISKMAP'). This makes new keymaps as necessary. The
! 2185: initial keymap in which to do bindings is MAP.
! 2186:
! 2187: -- Function: int rl_parse_and_bind (char *line)
! 2188: Parse LINE as if it had been read from the `inputrc' file and
! 2189: perform any key bindings and variable assignments found (*note
! 2190: Readline Init File::).
! 2191:
! 2192: -- Function: int rl_read_init_file (const char *filename)
! 2193: Read keybindings and variable assignments from FILENAME (*note
! 2194: Readline Init File::).
! 2195:
! 2196:
! 2197: File: readline.info, Node: Associating Function Names and Bindings, Next: Allowing Undoing, Prev: Binding Keys, Up: Readline Convenience Functions
! 2198:
! 2199: 2.4.4 Associating Function Names and Bindings
! 2200: ---------------------------------------------
! 2201:
! 2202: These functions allow you to find out what keys invoke named functions
! 2203: and the functions invoked by a particular key sequence. You may also
! 2204: associate a new function name with an arbitrary function.
! 2205:
! 2206: -- Function: rl_command_func_t * rl_named_function (const char *name)
! 2207: Return the function with name NAME.
! 2208:
! 2209: -- Function: rl_command_func_t * rl_function_of_keyseq (const char
! 2210: *keyseq, Keymap map, int *type)
! 2211: Return the function invoked by KEYSEQ in keymap MAP. If MAP is
! 2212: `NULL', the current keymap is used. If TYPE is not `NULL', the
! 2213: type of the object is returned in the `int' variable it points to
! 2214: (one of `ISFUNC', `ISKMAP', or `ISMACR').
! 2215:
! 2216: -- Function: char ** rl_invoking_keyseqs (rl_command_func_t *function)
! 2217: Return an array of strings representing the key sequences used to
! 2218: invoke FUNCTION in the current keymap.
! 2219:
! 2220: -- Function: char ** rl_invoking_keyseqs_in_map (rl_command_func_t
! 2221: *function, Keymap map)
! 2222: Return an array of strings representing the key sequences used to
! 2223: invoke FUNCTION in the keymap MAP.
! 2224:
! 2225: -- Function: void rl_function_dumper (int readable)
! 2226: Print the readline function names and the key sequences currently
! 2227: bound to them to `rl_outstream'. If READABLE is non-zero, the
! 2228: list is formatted in such a way that it can be made part of an
! 2229: `inputrc' file and re-read.
! 2230:
! 2231: -- Function: void rl_list_funmap_names (void)
! 2232: Print the names of all bindable Readline functions to
! 2233: `rl_outstream'.
! 2234:
! 2235: -- Function: const char ** rl_funmap_names (void)
! 2236: Return a NULL terminated array of known function names. The array
! 2237: is sorted. The array itself is allocated, but not the strings
! 2238: inside. You should free the array, but not the pointers, using
! 2239: `free' or `rl_free' when you are done.
! 2240:
! 2241: -- Function: int rl_add_funmap_entry (const char *name,
! 2242: rl_command_func_t *function)
! 2243: Add NAME to the list of bindable Readline command names, and make
! 2244: FUNCTION the function to be called when NAME is invoked.
! 2245:
! 2246:
! 2247: File: readline.info, Node: Allowing Undoing, Next: Redisplay, Prev: Associating Function Names and Bindings, Up: Readline Convenience Functions
! 2248:
! 2249: 2.4.5 Allowing Undoing
! 2250: ----------------------
! 2251:
! 2252: Supporting the undo command is a painless thing, and makes your
! 2253: functions much more useful. It is certainly easy to try something if
! 2254: you know you can undo it.
! 2255:
! 2256: If your function simply inserts text once, or deletes text once, and
! 2257: uses `rl_insert_text()' or `rl_delete_text()' to do it, then undoing is
! 2258: already done for you automatically.
! 2259:
! 2260: If you do multiple insertions or multiple deletions, or any
! 2261: combination of these operations, you should group them together into
! 2262: one operation. This is done with `rl_begin_undo_group()' and
! 2263: `rl_end_undo_group()'.
! 2264:
! 2265: The types of events that can be undone are:
! 2266:
! 2267: enum undo_code { UNDO_DELETE, UNDO_INSERT, UNDO_BEGIN, UNDO_END };
! 2268:
! 2269: Notice that `UNDO_DELETE' means to insert some text, and
! 2270: `UNDO_INSERT' means to delete some text. That is, the undo code tells
! 2271: what to undo, not how to undo it. `UNDO_BEGIN' and `UNDO_END' are tags
! 2272: added by `rl_begin_undo_group()' and `rl_end_undo_group()'.
! 2273:
! 2274: -- Function: int rl_begin_undo_group (void)
! 2275: Begins saving undo information in a group construct. The undo
! 2276: information usually comes from calls to `rl_insert_text()' and
! 2277: `rl_delete_text()', but could be the result of calls to
! 2278: `rl_add_undo()'.
! 2279:
! 2280: -- Function: int rl_end_undo_group (void)
! 2281: Closes the current undo group started with `rl_begin_undo_group
! 2282: ()'. There should be one call to `rl_end_undo_group()' for each
! 2283: call to `rl_begin_undo_group()'.
! 2284:
! 2285: -- Function: void rl_add_undo (enum undo_code what, int start, int
! 2286: end, char *text)
! 2287: Remember how to undo an event (according to WHAT). The affected
! 2288: text runs from START to END, and encompasses TEXT.
! 2289:
! 2290: -- Function: void rl_free_undo_list (void)
! 2291: Free the existing undo list.
! 2292:
! 2293: -- Function: int rl_do_undo (void)
! 2294: Undo the first thing on the undo list. Returns `0' if there was
! 2295: nothing to undo, non-zero if something was undone.
! 2296:
! 2297: Finally, if you neither insert nor delete text, but directly modify
! 2298: the existing text (e.g., change its case), call `rl_modifying()' once,
! 2299: just before you modify the text. You must supply the indices of the
! 2300: text range that you are going to modify.
! 2301:
! 2302: -- Function: int rl_modifying (int start, int end)
! 2303: Tell Readline to save the text between START and END as a single
! 2304: undo unit. It is assumed that you will subsequently modify that
! 2305: text.
! 2306:
! 2307:
! 2308: File: readline.info, Node: Redisplay, Next: Modifying Text, Prev: Allowing Undoing, Up: Readline Convenience Functions
! 2309:
! 2310: 2.4.6 Redisplay
! 2311: ---------------
! 2312:
! 2313: -- Function: void rl_redisplay (void)
! 2314: Change what's displayed on the screen to reflect the current
! 2315: contents of `rl_line_buffer'.
! 2316:
! 2317: -- Function: int rl_forced_update_display (void)
! 2318: Force the line to be updated and redisplayed, whether or not
! 2319: Readline thinks the screen display is correct.
! 2320:
! 2321: -- Function: int rl_on_new_line (void)
! 2322: Tell the update functions that we have moved onto a new (empty)
! 2323: line, usually after outputting a newline.
! 2324:
! 2325: -- Function: int rl_on_new_line_with_prompt (void)
! 2326: Tell the update functions that we have moved onto a new line, with
! 2327: RL_PROMPT already displayed. This could be used by applications
! 2328: that want to output the prompt string themselves, but still need
! 2329: Readline to know the prompt string length for redisplay. It
! 2330: should be used after setting RL_ALREADY_PROMPTED.
! 2331:
! 2332: -- Function: int rl_reset_line_state (void)
! 2333: Reset the display state to a clean state and redisplay the current
! 2334: line starting on a new line.
! 2335:
! 2336: -- Function: int rl_crlf (void)
! 2337: Move the cursor to the start of the next screen line.
! 2338:
! 2339: -- Function: int rl_show_char (int c)
! 2340: Display character C on `rl_outstream'. If Readline has not been
! 2341: set to display meta characters directly, this will convert meta
! 2342: characters to a meta-prefixed key sequence. This is intended for
! 2343: use by applications which wish to do their own redisplay.
! 2344:
! 2345: -- Function: int rl_message (const char *, ...)
! 2346: The arguments are a format string as would be supplied to `printf',
! 2347: possibly containing conversion specifications such as `%d', and
! 2348: any additional arguments necessary to satisfy the conversion
! 2349: specifications. The resulting string is displayed in the "echo
! 2350: area". The echo area is also used to display numeric arguments
! 2351: and search strings. You should call `rl_save_prompt' to save the
! 2352: prompt information before calling this function.
! 2353:
! 2354: -- Function: int rl_clear_message (void)
! 2355: Clear the message in the echo area. If the prompt was saved with
! 2356: a call to `rl_save_prompt' before the last call to `rl_message',
! 2357: call `rl_restore_prompt' before calling this function.
! 2358:
! 2359: -- Function: void rl_save_prompt (void)
! 2360: Save the local Readline prompt display state in preparation for
! 2361: displaying a new message in the message area with `rl_message()'.
! 2362:
! 2363: -- Function: void rl_restore_prompt (void)
! 2364: Restore the local Readline prompt display state saved by the most
! 2365: recent call to `rl_save_prompt'. if `rl_save_prompt' was called
! 2366: to save the prompt before a call to `rl_message', this function
! 2367: should be called before the corresponding call to
! 2368: `rl_clear_message'.
! 2369:
! 2370: -- Function: int rl_expand_prompt (char *prompt)
! 2371: Expand any special character sequences in PROMPT and set up the
! 2372: local Readline prompt redisplay variables. This function is
! 2373: called by `readline()'. It may also be called to expand the
! 2374: primary prompt if the `rl_on_new_line_with_prompt()' function or
! 2375: `rl_already_prompted' variable is used. It returns the number of
! 2376: visible characters on the last line of the (possibly multi-line)
! 2377: prompt. Applications may indicate that the prompt contains
! 2378: characters that take up no physical screen space when displayed by
! 2379: bracketing a sequence of such characters with the special markers
! 2380: `RL_PROMPT_START_IGNORE' and `RL_PROMPT_END_IGNORE' (declared in
! 2381: `readline.h'. This may be used to embed terminal-specific escape
! 2382: sequences in prompts.
! 2383:
! 2384: -- Function: int rl_set_prompt (const char *prompt)
! 2385: Make Readline use PROMPT for subsequent redisplay. This calls
! 2386: `rl_expand_prompt()' to expand the prompt and sets `rl_prompt' to
! 2387: the result.
! 2388:
! 2389:
! 2390: File: readline.info, Node: Modifying Text, Next: Character Input, Prev: Redisplay, Up: Readline Convenience Functions
! 2391:
! 2392: 2.4.7 Modifying Text
! 2393: --------------------
! 2394:
! 2395: -- Function: int rl_insert_text (const char *text)
! 2396: Insert TEXT into the line at the current cursor position. Returns
! 2397: the number of characters inserted.
! 2398:
! 2399: -- Function: int rl_delete_text (int start, int end)
! 2400: Delete the text between START and END in the current line.
! 2401: Returns the number of characters deleted.
! 2402:
! 2403: -- Function: char * rl_copy_text (int start, int end)
! 2404: Return a copy of the text between START and END in the current
! 2405: line.
! 2406:
! 2407: -- Function: int rl_kill_text (int start, int end)
! 2408: Copy the text between START and END in the current line to the
! 2409: kill ring, appending or prepending to the last kill if the last
! 2410: command was a kill command. The text is deleted. If START is
! 2411: less than END, the text is appended, otherwise prepended. If the
! 2412: last command was not a kill, a new kill ring slot is used.
! 2413:
! 2414: -- Function: int rl_push_macro_input (char *macro)
! 2415: Cause MACRO to be inserted into the line, as if it had been invoked
! 2416: by a key bound to a macro. Not especially useful; use
! 2417: `rl_insert_text()' instead.
! 2418:
! 2419:
! 2420: File: readline.info, Node: Character Input, Next: Terminal Management, Prev: Modifying Text, Up: Readline Convenience Functions
! 2421:
! 2422: 2.4.8 Character Input
! 2423: ---------------------
! 2424:
! 2425: -- Function: int rl_read_key (void)
! 2426: Return the next character available from Readline's current input
! 2427: stream. This handles input inserted into the input stream via
! 2428: RL_PENDING_INPUT (*note Readline Variables::) and
! 2429: `rl_stuff_char()', macros, and characters read from the keyboard.
! 2430: While waiting for input, this function will call any function
! 2431: assigned to the `rl_event_hook' variable.
! 2432:
! 2433: -- Function: int rl_getc (FILE *stream)
! 2434: Return the next character available from STREAM, which is assumed
! 2435: to be the keyboard.
! 2436:
! 2437: -- Function: int rl_stuff_char (int c)
! 2438: Insert C into the Readline input stream. It will be "read" before
! 2439: Readline attempts to read characters from the terminal with
! 2440: `rl_read_key()'. Up to 512 characters may be pushed back.
! 2441: `rl_stuff_char' returns 1 if the character was successfully
! 2442: inserted; 0 otherwise.
! 2443:
! 2444: -- Function: int rl_execute_next (int c)
! 2445: Make C be the next command to be executed when `rl_read_key()' is
! 2446: called. This sets RL_PENDING_INPUT.
! 2447:
! 2448: -- Function: int rl_clear_pending_input (void)
! 2449: Unset RL_PENDING_INPUT, effectively negating the effect of any
! 2450: previous call to `rl_execute_next()'. This works only if the
! 2451: pending input has not already been read with `rl_read_key()'.
! 2452:
! 2453: -- Function: int rl_set_keyboard_input_timeout (int u)
! 2454: While waiting for keyboard input in `rl_read_key()', Readline will
! 2455: wait for U microseconds for input before calling any function
! 2456: assigned to `rl_event_hook'. U must be greater than or equal to
! 2457: zero (a zero-length timeout is equivalent to a poll). The default
! 2458: waiting period is one-tenth of a second. Returns the old timeout
! 2459: value.
! 2460:
! 2461:
! 2462: File: readline.info, Node: Terminal Management, Next: Utility Functions, Prev: Character Input, Up: Readline Convenience Functions
! 2463:
! 2464: 2.4.9 Terminal Management
! 2465: -------------------------
! 2466:
! 2467: -- Function: void rl_prep_terminal (int meta_flag)
! 2468: Modify the terminal settings for Readline's use, so `readline()'
! 2469: can read a single character at a time from the keyboard. The
! 2470: META_FLAG argument should be non-zero if Readline should read
! 2471: eight-bit input.
! 2472:
! 2473: -- Function: void rl_deprep_terminal (void)
! 2474: Undo the effects of `rl_prep_terminal()', leaving the terminal in
! 2475: the state in which it was before the most recent call to
! 2476: `rl_prep_terminal()'.
! 2477:
! 2478: -- Function: void rl_tty_set_default_bindings (Keymap kmap)
! 2479: Read the operating system's terminal editing characters (as would
! 2480: be displayed by `stty') to their Readline equivalents. The
! 2481: bindings are performed in KMAP.
! 2482:
! 2483: -- Function: void rl_tty_unset_default_bindings (Keymap kmap)
! 2484: Reset the bindings manipulated by `rl_tty_set_default_bindings' so
! 2485: that the terminal editing characters are bound to `rl_insert'.
! 2486: The bindings are performed in KMAP.
! 2487:
! 2488: -- Function: int rl_reset_terminal (const char *terminal_name)
! 2489: Reinitialize Readline's idea of the terminal settings using
! 2490: TERMINAL_NAME as the terminal type (e.g., `vt100'). If
! 2491: TERMINAL_NAME is `NULL', the value of the `TERM' environment
! 2492: variable is used.
! 2493:
! 2494:
! 2495: File: readline.info, Node: Utility Functions, Next: Miscellaneous Functions, Prev: Terminal Management, Up: Readline Convenience Functions
! 2496:
! 2497: 2.4.10 Utility Functions
! 2498: ------------------------
! 2499:
! 2500: -- Function: int rl_save_state (struct readline_state *sp)
! 2501: Save a snapshot of Readline's internal state to SP. The contents
! 2502: of the READLINE_STATE structure are documented in `readline.h'.
! 2503: The caller is responsible for allocating the structure.
! 2504:
! 2505: -- Function: int rl_restore_state (struct readline_state *sp)
! 2506: Restore Readline's internal state to that stored in SP, which must
! 2507: have been saved by a call to `rl_save_state'. The contents of the
! 2508: READLINE_STATE structure are documented in `readline.h'. The
! 2509: caller is responsible for freeing the structure.
! 2510:
! 2511: -- Function: void rl_free (void *mem)
! 2512: Deallocate the memory pointed to by MEM. MEM must have been
! 2513: allocated by `malloc'.
! 2514:
! 2515: -- Function: void rl_replace_line (const char *text, int clear_undo)
! 2516: Replace the contents of `rl_line_buffer' with TEXT. The point and
! 2517: mark are preserved, if possible. If CLEAR_UNDO is non-zero, the
! 2518: undo list associated with the current line is cleared.
! 2519:
! 2520: -- Function: void rl_extend_line_buffer (int len)
! 2521: Ensure that `rl_line_buffer' has enough space to hold LEN
! 2522: characters, possibly reallocating it if necessary.
! 2523:
! 2524: -- Function: int rl_initialize (void)
! 2525: Initialize or re-initialize Readline's internal state. It's not
! 2526: strictly necessary to call this; `readline()' calls it before
! 2527: reading any input.
! 2528:
! 2529: -- Function: int rl_ding (void)
! 2530: Ring the terminal bell, obeying the setting of `bell-style'.
! 2531:
! 2532: -- Function: int rl_alphabetic (int c)
! 2533: Return 1 if C is an alphabetic character.
! 2534:
! 2535: -- Function: void rl_display_match_list (char **matches, int len, int
! 2536: max)
! 2537: A convenience function for displaying a list of strings in
! 2538: columnar format on Readline's output stream. `matches' is the list
! 2539: of strings, in argv format, such as a list of completion matches.
! 2540: `len' is the number of strings in `matches', and `max' is the
! 2541: length of the longest string in `matches'. This function uses the
! 2542: setting of `print-completions-horizontally' to select how the
! 2543: matches are displayed (*note Readline Init File Syntax::). When
! 2544: displaying completions, this function sets the number of columns
! 2545: used for display to the value of `completion-display-width', the
! 2546: value of the environment variable `COLUMNS', or the screen width,
! 2547: in that order.
! 2548:
! 2549: The following are implemented as macros, defined in `chardefs.h'.
! 2550: Applications should refrain from using them.
! 2551:
! 2552: -- Function: int _rl_uppercase_p (int c)
! 2553: Return 1 if C is an uppercase alphabetic character.
! 2554:
! 2555: -- Function: int _rl_lowercase_p (int c)
! 2556: Return 1 if C is a lowercase alphabetic character.
! 2557:
! 2558: -- Function: int _rl_digit_p (int c)
! 2559: Return 1 if C is a numeric character.
! 2560:
! 2561: -- Function: int _rl_to_upper (int c)
! 2562: If C is a lowercase alphabetic character, return the corresponding
! 2563: uppercase character.
! 2564:
! 2565: -- Function: int _rl_to_lower (int c)
! 2566: If C is an uppercase alphabetic character, return the corresponding
! 2567: lowercase character.
! 2568:
! 2569: -- Function: int _rl_digit_value (int c)
! 2570: If C is a number, return the value it represents.
! 2571:
! 2572:
! 2573: File: readline.info, Node: Miscellaneous Functions, Next: Alternate Interface, Prev: Utility Functions, Up: Readline Convenience Functions
! 2574:
! 2575: 2.4.11 Miscellaneous Functions
! 2576: ------------------------------
! 2577:
! 2578: -- Function: int rl_macro_bind (const char *keyseq, const char *macro,
! 2579: Keymap map)
! 2580: Bind the key sequence KEYSEQ to invoke the macro MACRO. The
! 2581: binding is performed in MAP. When KEYSEQ is invoked, the MACRO
! 2582: will be inserted into the line. This function is deprecated; use
! 2583: `rl_generic_bind()' instead.
! 2584:
! 2585: -- Function: void rl_macro_dumper (int readable)
! 2586: Print the key sequences bound to macros and their values, using
! 2587: the current keymap, to `rl_outstream'. If READABLE is non-zero,
! 2588: the list is formatted in such a way that it can be made part of an
! 2589: `inputrc' file and re-read.
! 2590:
! 2591: -- Function: int rl_variable_bind (const char *variable, const char
! 2592: *value)
! 2593: Make the Readline variable VARIABLE have VALUE. This behaves as
! 2594: if the readline command `set VARIABLE VALUE' had been executed in
! 2595: an `inputrc' file (*note Readline Init File Syntax::).
! 2596:
! 2597: -- Function: char * rl_variable_value (const char *variable)
! 2598: Return a string representing the value of the Readline variable
! 2599: VARIABLE. For boolean variables, this string is either `on' or
! 2600: `off'.
! 2601:
! 2602: -- Function: void rl_variable_dumper (int readable)
! 2603: Print the readline variable names and their current values to
! 2604: `rl_outstream'. If READABLE is non-zero, the list is formatted in
! 2605: such a way that it can be made part of an `inputrc' file and
! 2606: re-read.
! 2607:
! 2608: -- Function: int rl_set_paren_blink_timeout (int u)
! 2609: Set the time interval (in microseconds) that Readline waits when
! 2610: showing a balancing character when `blink-matching-paren' has been
! 2611: enabled.
! 2612:
! 2613: -- Function: char * rl_get_termcap (const char *cap)
! 2614: Retrieve the string value of the termcap capability CAP. Readline
! 2615: fetches the termcap entry for the current terminal name and uses
! 2616: those capabilities to move around the screen line and perform other
! 2617: terminal-specific operations, like erasing a line. Readline does
! 2618: not use all of a terminal's capabilities, and this function will
! 2619: return values for only those capabilities Readline uses.
! 2620:
! 2621: -- Function: void rl_clear_history (void)
! 2622: Clear the history list by deleting all of the entries, in the same
! 2623: manner as the History library's `clear_history()' function. This
! 2624: differs from `clear_history' because it frees private data
! 2625: Readline saves in the history list.
! 2626:
! 2627:
! 2628: File: readline.info, Node: Alternate Interface, Next: A Readline Example, Prev: Miscellaneous Functions, Up: Readline Convenience Functions
! 2629:
! 2630: 2.4.12 Alternate Interface
! 2631: --------------------------
! 2632:
! 2633: An alternate interface is available to plain `readline()'. Some
! 2634: applications need to interleave keyboard I/O with file, device, or
! 2635: window system I/O, typically by using a main loop to `select()' on
! 2636: various file descriptors. To accommodate this need, readline can also
! 2637: be invoked as a `callback' function from an event loop. There are
! 2638: functions available to make this easy.
! 2639:
! 2640: -- Function: void rl_callback_handler_install (const char *prompt,
! 2641: rl_vcpfunc_t *lhandler)
! 2642: Set up the terminal for readline I/O and display the initial
! 2643: expanded value of PROMPT. Save the value of LHANDLER to use as a
! 2644: handler function to call when a complete line of input has been
! 2645: entered. The handler function receives the text of the line as an
! 2646: argument.
! 2647:
! 2648: -- Function: void rl_callback_read_char (void)
! 2649: Whenever an application determines that keyboard input is
! 2650: available, it should call `rl_callback_read_char()', which will
! 2651: read the next character from the current input source. If that
! 2652: character completes the line, `rl_callback_read_char' will invoke
! 2653: the LHANDLER function installed by `rl_callback_handler_install'
! 2654: to process the line. Before calling the LHANDLER function, the
! 2655: terminal settings are reset to the values they had before calling
! 2656: `rl_callback_handler_install'. If the LHANDLER function returns,
! 2657: and the line handler remains installed, the terminal settings are
! 2658: modified for Readline's use again. `EOF' is indicated by calling
! 2659: LHANDLER with a `NULL' line.
! 2660:
! 2661: -- Function: void rl_callback_handler_remove (void)
! 2662: Restore the terminal to its initial state and remove the line
! 2663: handler. This may be called from within a callback as well as
! 2664: independently. If the LHANDLER installed by
! 2665: `rl_callback_handler_install' does not exit the program, either
! 2666: this function or the function referred to by the value of
! 2667: `rl_deprep_term_function' should be called before the program
! 2668: exits to reset the terminal settings.
! 2669:
! 2670:
! 2671: File: readline.info, Node: A Readline Example, Next: Alternate Interface Example, Prev: Alternate Interface, Up: Readline Convenience Functions
! 2672:
! 2673: 2.4.13 A Readline Example
! 2674: -------------------------
! 2675:
! 2676: Here is a function which changes lowercase characters to their uppercase
! 2677: equivalents, and uppercase characters to lowercase. If this function
! 2678: was bound to `M-c', then typing `M-c' would change the case of the
! 2679: character under point. Typing `M-1 0 M-c' would change the case of the
! 2680: following 10 characters, leaving the cursor on the last character
! 2681: changed.
! 2682:
! 2683: /* Invert the case of the COUNT following characters. */
! 2684: int
! 2685: invert_case_line (count, key)
! 2686: int count, key;
! 2687: {
! 2688: register int start, end, i;
! 2689:
! 2690: start = rl_point;
! 2691:
! 2692: if (rl_point >= rl_end)
! 2693: return (0);
! 2694:
! 2695: if (count < 0)
! 2696: {
! 2697: direction = -1;
! 2698: count = -count;
! 2699: }
! 2700: else
! 2701: direction = 1;
! 2702:
! 2703: /* Find the end of the range to modify. */
! 2704: end = start + (count * direction);
! 2705:
! 2706: /* Force it to be within range. */
! 2707: if (end > rl_end)
! 2708: end = rl_end;
! 2709: else if (end < 0)
! 2710: end = 0;
! 2711:
! 2712: if (start == end)
! 2713: return (0);
! 2714:
! 2715: if (start > end)
! 2716: {
! 2717: int temp = start;
! 2718: start = end;
! 2719: end = temp;
! 2720: }
! 2721:
! 2722: /* Tell readline that we are modifying the line,
! 2723: so it will save the undo information. */
! 2724: rl_modifying (start, end);
! 2725:
! 2726: for (i = start; i != end; i++)
! 2727: {
! 2728: if (_rl_uppercase_p (rl_line_buffer[i]))
! 2729: rl_line_buffer[i] = _rl_to_lower (rl_line_buffer[i]);
! 2730: else if (_rl_lowercase_p (rl_line_buffer[i]))
! 2731: rl_line_buffer[i] = _rl_to_upper (rl_line_buffer[i]);
! 2732: }
! 2733: /* Move point to on top of the last character changed. */
! 2734: rl_point = (direction == 1) ? end - 1 : start;
! 2735: return (0);
! 2736: }
! 2737:
! 2738:
! 2739: File: readline.info, Node: Alternate Interface Example, Prev: A Readline Example, Up: Readline Convenience Functions
! 2740:
! 2741: 2.4.14 Alternate Interface Example
! 2742: ----------------------------------
! 2743:
! 2744: Here is a complete program that illustrates Readline's alternate
! 2745: interface. It reads lines from the terminal and displays them,
! 2746: providing the standard history and TAB completion functions. It
! 2747: understands the EOF character or "exit" to exit the program.
! 2748:
! 2749: /* Standard include files. stdio.h is required. */
! 2750: #include <stdlib.h>
! 2751: #include <unistd.h>
! 2752:
! 2753: /* Used for select(2) */
! 2754: #include <sys/types.h>
! 2755: #include <sys/select.h>
! 2756:
! 2757: #include <stdio.h>
! 2758:
! 2759: /* Standard readline include files. */
! 2760: #include <readline/readline.h>
! 2761: #include <readline/history.h>
! 2762:
! 2763: static void cb_linehandler (char *);
! 2764:
! 2765: int running;
! 2766: const char *prompt = "rltest$ ";
! 2767:
! 2768: /* Callback function called for each line when accept-line executed, EOF
! 2769: seen, or EOF character read. This sets a flag and returns; it could
! 2770: also call exit(3). */
! 2771: static void
! 2772: cb_linehandler (char *line)
! 2773: {
! 2774: /* Can use ^D (stty eof) or `exit' to exit. */
! 2775: if (line == NULL || strcmp (line, "exit") == 0)
! 2776: {
! 2777: if (line == 0)
! 2778: printf ("\n");
! 2779: printf ("exit\n");
! 2780: /* This function needs to be called to reset the terminal settings,
! 2781: and calling it from the line handler keeps one extra prompt from
! 2782: being displayed. */
! 2783: rl_callback_handler_remove ();
! 2784:
! 2785: running = 0;
! 2786: }
! 2787: else
! 2788: {
! 2789: if (*line)
! 2790: add_history (line);
! 2791: printf ("input line: %s\n", line);
! 2792: free (line);
! 2793: }
! 2794: }
! 2795:
! 2796: int
! 2797: main (int c, char **v)
! 2798: {
! 2799: fd_set fds;
! 2800: int r;
! 2801:
! 2802: /* Install the line handler. */
! 2803: rl_callback_handler_install (prompt, cb_linehandler);
! 2804:
! 2805: /* Enter a simple event loop. This waits until something is available
! 2806: to read on readline's input stream (defaults to standard input) and
! 2807: calls the builtin character read callback to read it. It does not
! 2808: have to modify the user's terminal settings. */
! 2809: running = 1;
! 2810: while (running)
! 2811: {
! 2812: FD_ZERO (&fds);
! 2813: FD_SET (fileno (rl_instream), &fds);
! 2814:
! 2815: r = select (FD_SETSIZE, &fds, NULL, NULL, NULL);
! 2816: if (r < 0)
! 2817: {
! 2818: perror ("rltest: select");
! 2819: rl_callback_handler_remove ();
! 2820: break;
! 2821: }
! 2822:
! 2823: if (FD_ISSET (fileno (rl_instream), &fds))
! 2824: rl_callback_read_char ();
! 2825: }
! 2826:
! 2827: printf ("rltest: Event loop has exited\n");
! 2828: return 0;
! 2829: }
! 2830:
! 2831:
! 2832: File: readline.info, Node: Readline Signal Handling, Next: Custom Completers, Prev: Readline Convenience Functions, Up: Programming with GNU Readline
! 2833:
! 2834: 2.5 Readline Signal Handling
! 2835: ============================
! 2836:
! 2837: Signals are asynchronous events sent to a process by the Unix kernel,
! 2838: sometimes on behalf of another process. They are intended to indicate
! 2839: exceptional events, like a user pressing the interrupt key on his
! 2840: terminal, or a network connection being broken. There is a class of
! 2841: signals that can be sent to the process currently reading input from
! 2842: the keyboard. Since Readline changes the terminal attributes when it
! 2843: is called, it needs to perform special processing when such a signal is
! 2844: received in order to restore the terminal to a sane state, or provide
! 2845: application writers with functions to do so manually.
! 2846:
! 2847: Readline contains an internal signal handler that is installed for a
! 2848: number of signals (`SIGINT', `SIGQUIT', `SIGTERM', `SIGHUP', `SIGALRM',
! 2849: `SIGTSTP', `SIGTTIN', and `SIGTTOU'). When one of these signals is
! 2850: received, the signal handler will reset the terminal attributes to
! 2851: those that were in effect before `readline()' was called, reset the
! 2852: signal handling to what it was before `readline()' was called, and
! 2853: resend the signal to the calling application. If and when the calling
! 2854: application's signal handler returns, Readline will reinitialize the
! 2855: terminal and continue to accept input. When a `SIGINT' is received,
! 2856: the Readline signal handler performs some additional work, which will
! 2857: cause any partially-entered line to be aborted (see the description of
! 2858: `rl_free_line_state()' below).
! 2859:
! 2860: There is an additional Readline signal handler, for `SIGWINCH', which
! 2861: the kernel sends to a process whenever the terminal's size changes (for
! 2862: example, if a user resizes an `xterm'). The Readline `SIGWINCH'
! 2863: handler updates Readline's internal screen size information, and then
! 2864: calls any `SIGWINCH' signal handler the calling application has
! 2865: installed. Readline calls the application's `SIGWINCH' signal handler
! 2866: without resetting the terminal to its original state. If the
! 2867: application's signal handler does more than update its idea of the
! 2868: terminal size and return (for example, a `longjmp' back to a main
! 2869: processing loop), it _must_ call `rl_cleanup_after_signal()' (described
! 2870: below), to restore the terminal state.
! 2871:
! 2872: Readline provides two variables that allow application writers to
! 2873: control whether or not it will catch certain signals and act on them
! 2874: when they are received. It is important that applications change the
! 2875: values of these variables only when calling `readline()', not in a
! 2876: signal handler, so Readline's internal signal state is not corrupted.
! 2877:
! 2878: -- Variable: int rl_catch_signals
! 2879: If this variable is non-zero, Readline will install signal
! 2880: handlers for `SIGINT', `SIGQUIT', `SIGTERM', `SIGHUP', `SIGALRM',
! 2881: `SIGTSTP', `SIGTTIN', and `SIGTTOU'.
! 2882:
! 2883: The default value of `rl_catch_signals' is 1.
! 2884:
! 2885: -- Variable: int rl_catch_sigwinch
! 2886: If this variable is set to a non-zero value, Readline will install
! 2887: a signal handler for `SIGWINCH'.
! 2888:
! 2889: The default value of `rl_catch_sigwinch' is 1.
! 2890:
! 2891: -- Variable: int rl_change_environment
! 2892: If this variable is set to a non-zero value, and Readline is
! 2893: handling `SIGWINCH', Readline will modify the LINES and COLUMNS
! 2894: environment variables upon receipt of a `SIGWINCH'
! 2895:
! 2896: The default value of `rl_change_environment' is 1.
! 2897:
! 2898: If an application does not wish to have Readline catch any signals,
! 2899: or to handle signals other than those Readline catches (`SIGHUP', for
! 2900: example), Readline provides convenience functions to do the necessary
! 2901: terminal and internal state cleanup upon receipt of a signal.
! 2902:
! 2903: -- Function: void rl_cleanup_after_signal (void)
! 2904: This function will reset the state of the terminal to what it was
! 2905: before `readline()' was called, and remove the Readline signal
! 2906: handlers for all signals, depending on the values of
! 2907: `rl_catch_signals' and `rl_catch_sigwinch'.
! 2908:
! 2909: -- Function: void rl_free_line_state (void)
! 2910: This will free any partial state associated with the current input
! 2911: line (undo information, any partial history entry, any
! 2912: partially-entered keyboard macro, and any partially-entered
! 2913: numeric argument). This should be called before
! 2914: `rl_cleanup_after_signal()'. The Readline signal handler for
! 2915: `SIGINT' calls this to abort the current input line.
! 2916:
! 2917: -- Function: void rl_reset_after_signal (void)
! 2918: This will reinitialize the terminal and reinstall any Readline
! 2919: signal handlers, depending on the values of `rl_catch_signals' and
! 2920: `rl_catch_sigwinch'.
! 2921:
! 2922: If an application does not wish Readline to catch `SIGWINCH', it may
! 2923: call `rl_resize_terminal()' or `rl_set_screen_size()' to force Readline
! 2924: to update its idea of the terminal size when a `SIGWINCH' is received.
! 2925:
! 2926: -- Function: void rl_echo_signal_char (int sig)
! 2927: If an application wishes to install its own signal handlers, but
! 2928: still have readline display characters that generate signals,
! 2929: calling this function with SIG set to `SIGINT', `SIGQUIT', or
! 2930: `SIGTSTP' will display the character generating that signal.
! 2931:
! 2932: -- Function: void rl_resize_terminal (void)
! 2933: Update Readline's internal screen size by reading values from the
! 2934: kernel.
! 2935:
! 2936: -- Function: void rl_set_screen_size (int rows, int cols)
! 2937: Set Readline's idea of the terminal size to ROWS rows and COLS
! 2938: columns. If either ROWS or COLUMNS is less than or equal to 0,
! 2939: Readline's idea of that terminal dimension is unchanged.
! 2940:
! 2941: If an application does not want to install a `SIGWINCH' handler, but
! 2942: is still interested in the screen dimensions, Readline's idea of the
! 2943: screen size may be queried.
! 2944:
! 2945: -- Function: void rl_get_screen_size (int *rows, int *cols)
! 2946: Return Readline's idea of the terminal's size in the variables
! 2947: pointed to by the arguments.
! 2948:
! 2949: -- Function: void rl_reset_screen_size (void)
! 2950: Cause Readline to reobtain the screen size and recalculate its
! 2951: dimensions.
! 2952:
! 2953: The following functions install and remove Readline's signal
! 2954: handlers.
! 2955:
! 2956: -- Function: int rl_set_signals (void)
! 2957: Install Readline's signal handler for `SIGINT', `SIGQUIT',
! 2958: `SIGTERM', `SIGHUP', `SIGALRM', `SIGTSTP', `SIGTTIN', `SIGTTOU',
! 2959: and `SIGWINCH', depending on the values of `rl_catch_signals' and
! 2960: `rl_catch_sigwinch'.
! 2961:
! 2962: -- Function: int rl_clear_signals (void)
! 2963: Remove all of the Readline signal handlers installed by
! 2964: `rl_set_signals()'.
! 2965:
! 2966:
! 2967: File: readline.info, Node: Custom Completers, Prev: Readline Signal Handling, Up: Programming with GNU Readline
! 2968:
! 2969: 2.6 Custom Completers
! 2970: =====================
! 2971:
! 2972: Typically, a program that reads commands from the user has a way of
! 2973: disambiguating commands and data. If your program is one of these, then
! 2974: it can provide completion for commands, data, or both. The following
! 2975: sections describe how your program and Readline cooperate to provide
! 2976: this service.
! 2977:
! 2978: * Menu:
! 2979:
! 2980: * How Completing Works:: The logic used to do completion.
! 2981: * Completion Functions:: Functions provided by Readline.
! 2982: * Completion Variables:: Variables which control completion.
! 2983: * A Short Completion Example:: An example of writing completer subroutines.
! 2984:
! 2985:
! 2986: File: readline.info, Node: How Completing Works, Next: Completion Functions, Up: Custom Completers
! 2987:
! 2988: 2.6.1 How Completing Works
! 2989: --------------------------
! 2990:
! 2991: In order to complete some text, the full list of possible completions
! 2992: must be available. That is, it is not possible to accurately expand a
! 2993: partial word without knowing all of the possible words which make sense
! 2994: in that context. The Readline library provides the user interface to
! 2995: completion, and two of the most common completion functions: filename
! 2996: and username. For completing other types of text, you must write your
! 2997: own completion function. This section describes exactly what such
! 2998: functions must do, and provides an example.
! 2999:
! 3000: There are three major functions used to perform completion:
! 3001:
! 3002: 1. The user-interface function `rl_complete()'. This function is
! 3003: called with the same arguments as other bindable Readline
! 3004: functions: COUNT and INVOKING_KEY. It isolates the word to be
! 3005: completed and calls `rl_completion_matches()' to generate a list
! 3006: of possible completions. It then either lists the possible
! 3007: completions, inserts the possible completions, or actually
! 3008: performs the completion, depending on which behavior is desired.
! 3009:
! 3010: 2. The internal function `rl_completion_matches()' uses an
! 3011: application-supplied "generator" function to generate the list of
! 3012: possible matches, and then returns the array of these matches.
! 3013: The caller should place the address of its generator function in
! 3014: `rl_completion_entry_function'.
! 3015:
! 3016: 3. The generator function is called repeatedly from
! 3017: `rl_completion_matches()', returning a string each time. The
! 3018: arguments to the generator function are TEXT and STATE. TEXT is
! 3019: the partial word to be completed. STATE is zero the first time
! 3020: the function is called, allowing the generator to perform any
! 3021: necessary initialization, and a positive non-zero integer for each
! 3022: subsequent call. The generator function returns `(char *)NULL' to
! 3023: inform `rl_completion_matches()' that there are no more
! 3024: possibilities left. Usually the generator function computes the
! 3025: list of possible completions when STATE is zero, and returns them
! 3026: one at a time on subsequent calls. Each string the generator
! 3027: function returns as a match must be allocated with `malloc()';
! 3028: Readline frees the strings when it has finished with them. Such a
! 3029: generator function is referred to as an "application-specific
! 3030: completion function".
! 3031:
! 3032:
! 3033: -- Function: int rl_complete (int ignore, int invoking_key)
! 3034: Complete the word at or before point. You have supplied the
! 3035: function that does the initial simple matching selection algorithm
! 3036: (see `rl_completion_matches()'). The default is to do filename
! 3037: completion.
! 3038:
! 3039: -- Variable: rl_compentry_func_t * rl_completion_entry_function
! 3040: This is a pointer to the generator function for
! 3041: `rl_completion_matches()'. If the value of
! 3042: `rl_completion_entry_function' is `NULL' then the default filename
! 3043: generator function, `rl_filename_completion_function()', is used.
! 3044: An "application-specific completion function" is a function whose
! 3045: address is assigned to `rl_completion_entry_function' and whose
! 3046: return values are used to generate possible completions.
! 3047:
! 3048:
! 3049: File: readline.info, Node: Completion Functions, Next: Completion Variables, Prev: How Completing Works, Up: Custom Completers
! 3050:
! 3051: 2.6.2 Completion Functions
! 3052: --------------------------
! 3053:
! 3054: Here is the complete list of callable completion functions present in
! 3055: Readline.
! 3056:
! 3057: -- Function: int rl_complete_internal (int what_to_do)
! 3058: Complete the word at or before point. WHAT_TO_DO says what to do
! 3059: with the completion. A value of `?' means list the possible
! 3060: completions. `TAB' means do standard completion. `*' means
! 3061: insert all of the possible completions. `!' means to display all
! 3062: of the possible completions, if there is more than one, as well as
! 3063: performing partial completion. `@' is similar to `!', but
! 3064: possible completions are not listed if the possible completions
! 3065: share a common prefix.
! 3066:
! 3067: -- Function: int rl_complete (int ignore, int invoking_key)
! 3068: Complete the word at or before point. You have supplied the
! 3069: function that does the initial simple matching selection algorithm
! 3070: (see `rl_completion_matches()' and `rl_completion_entry_function').
! 3071: The default is to do filename completion. This calls
! 3072: `rl_complete_internal()' with an argument depending on
! 3073: INVOKING_KEY.
! 3074:
! 3075: -- Function: int rl_possible_completions (int count, int invoking_key)
! 3076: List the possible completions. See description of `rl_complete
! 3077: ()'. This calls `rl_complete_internal()' with an argument of `?'.
! 3078:
! 3079: -- Function: int rl_insert_completions (int count, int invoking_key)
! 3080: Insert the list of possible completions into the line, deleting the
! 3081: partially-completed word. See description of `rl_complete()'.
! 3082: This calls `rl_complete_internal()' with an argument of `*'.
! 3083:
! 3084: -- Function: int rl_completion_mode (rl_command_func_t *cfunc)
! 3085: Returns the appropriate value to pass to `rl_complete_internal()'
! 3086: depending on whether CFUNC was called twice in succession and the
! 3087: values of the `show-all-if-ambiguous' and `show-all-if-unmodified'
! 3088: variables. Application-specific completion functions may use this
! 3089: function to present the same interface as `rl_complete()'.
! 3090:
! 3091: -- Function: char ** rl_completion_matches (const char *text,
! 3092: rl_compentry_func_t *entry_func)
! 3093: Returns an array of strings which is a list of completions for
! 3094: TEXT. If there are no completions, returns `NULL'. The first
! 3095: entry in the returned array is the substitution for TEXT. The
! 3096: remaining entries are the possible completions. The array is
! 3097: terminated with a `NULL' pointer.
! 3098:
! 3099: ENTRY_FUNC is a function of two args, and returns a `char *'. The
! 3100: first argument is TEXT. The second is a state argument; it is
! 3101: zero on the first call, and non-zero on subsequent calls.
! 3102: ENTRY_FUNC returns a `NULL' pointer to the caller when there are
! 3103: no more matches.
! 3104:
! 3105: -- Function: char * rl_filename_completion_function (const char *text,
! 3106: int state)
! 3107: A generator function for filename completion in the general case.
! 3108: TEXT is a partial filename. The Bash source is a useful reference
! 3109: for writing application-specific completion functions (the Bash
! 3110: completion functions call this and other Readline functions).
! 3111:
! 3112: -- Function: char * rl_username_completion_function (const char *text,
! 3113: int state)
! 3114: A completion generator for usernames. TEXT contains a partial
! 3115: username preceded by a random character (usually `~'). As with all
! 3116: completion generators, STATE is zero on the first call and non-zero
! 3117: for subsequent calls.
! 3118:
! 3119:
! 3120: File: readline.info, Node: Completion Variables, Next: A Short Completion Example, Prev: Completion Functions, Up: Custom Completers
! 3121:
! 3122: 2.6.3 Completion Variables
! 3123: --------------------------
! 3124:
! 3125: -- Variable: rl_compentry_func_t * rl_completion_entry_function
! 3126: A pointer to the generator function for `rl_completion_matches()'.
! 3127: `NULL' means to use `rl_filename_completion_function()', the
! 3128: default filename completer.
! 3129:
! 3130: -- Variable: rl_completion_func_t * rl_attempted_completion_function
! 3131: A pointer to an alternative function to create matches. The
! 3132: function is called with TEXT, START, and END. START and END are
! 3133: indices in `rl_line_buffer' defining the boundaries of TEXT, which
! 3134: is a character string. If this function exists and returns
! 3135: `NULL', or if this variable is set to `NULL', then `rl_complete()'
! 3136: will call the value of `rl_completion_entry_function' to generate
! 3137: matches, otherwise the array of strings returned will be used. If
! 3138: this function sets the `rl_attempted_completion_over' variable to
! 3139: a non-zero value, Readline will not perform its default completion
! 3140: even if this function returns no matches.
! 3141:
! 3142: -- Variable: rl_quote_func_t * rl_filename_quoting_function
! 3143: A pointer to a function that will quote a filename in an
! 3144: application-specific fashion. This is called if filename
! 3145: completion is being attempted and one of the characters in
! 3146: `rl_filename_quote_characters' appears in a completed filename.
! 3147: The function is called with TEXT, MATCH_TYPE, and QUOTE_POINTER.
! 3148: The TEXT is the filename to be quoted. The MATCH_TYPE is either
! 3149: `SINGLE_MATCH', if there is only one completion match, or
! 3150: `MULT_MATCH'. Some functions use this to decide whether or not to
! 3151: insert a closing quote character. The QUOTE_POINTER is a pointer
! 3152: to any opening quote character the user typed. Some functions
! 3153: choose to reset this character.
! 3154:
! 3155: -- Variable: rl_dequote_func_t * rl_filename_dequoting_function
! 3156: A pointer to a function that will remove application-specific
! 3157: quoting characters from a filename before completion is attempted,
! 3158: so those characters do not interfere with matching the text
! 3159: against names in the filesystem. It is called with TEXT, the text
! 3160: of the word to be dequoted, and QUOTE_CHAR, which is the quoting
! 3161: character that delimits the filename (usually `'' or `"'). If
! 3162: QUOTE_CHAR is zero, the filename was not in an embedded string.
! 3163:
! 3164: -- Variable: rl_linebuf_func_t * rl_char_is_quoted_p
! 3165: A pointer to a function to call that determines whether or not a
! 3166: specific character in the line buffer is quoted, according to
! 3167: whatever quoting mechanism the program calling Readline uses. The
! 3168: function is called with two arguments: TEXT, the text of the line,
! 3169: and INDEX, the index of the character in the line. It is used to
! 3170: decide whether a character found in
! 3171: `rl_completer_word_break_characters' should be used to break words
! 3172: for the completer.
! 3173:
! 3174: -- Variable: rl_compignore_func_t * rl_ignore_some_completions_function
! 3175: This function, if defined, is called by the completer when real
! 3176: filename completion is done, after all the matching names have
! 3177: been generated. It is passed a `NULL' terminated array of matches.
! 3178: The first element (`matches[0]') is the maximal substring common
! 3179: to all matches. This function can re-arrange the list of matches
! 3180: as required, but each element deleted from the array must be freed.
! 3181:
! 3182: -- Variable: rl_icppfunc_t * rl_directory_completion_hook
! 3183: This function, if defined, is allowed to modify the directory
! 3184: portion of filenames Readline completes. It could be used to
! 3185: expand symbolic links or shell variables in pathnames. It is
! 3186: called with the address of a string (the current directory name)
! 3187: as an argument, and may modify that string. If the string is
! 3188: replaced with a new string, the old value should be freed. Any
! 3189: modified directory name should have a trailing slash. The
! 3190: modified value will be used as part of the completion, replacing
! 3191: the directory portion of the pathname the user typed. At the
! 3192: least, even if no other expansion is performed, this function
! 3193: should remove any quote characters from the directory name,
! 3194: because its result will be passed directly to `opendir()'.
! 3195:
! 3196: The directory completion hook returns an integer that should be
! 3197: non-zero if the function modifies its directory argument. The
! 3198: function should not modify the directory argument if it returns 0.
! 3199:
! 3200: -- Variable: rl_icppfunc_t * rl_directory_rewrite_hook;
! 3201: If non-zero, this is the address of a function to call when
! 3202: completing a directory name. This function takes the address of
! 3203: the directory name to be modified as an argument. Unlike
! 3204: `rl_directory_completion_hook', it only modifies the directory
! 3205: name used in `opendir', not what is displayed when the possible
! 3206: completions are printed or inserted. It is called before
! 3207: rl_directory_completion_hook. At the least, even if no other
! 3208: expansion is performed, this function should remove any quote
! 3209: characters from the directory name, because its result will be
! 3210: passed directly to `opendir()'.
! 3211:
! 3212: The directory rewrite hook returns an integer that should be
! 3213: non-zero if the function modfies its directory argument. The
! 3214: function should not modify the directory argument if it returns 0.
! 3215:
! 3216: -- Variable: rl_icppfunc_t * rl_filename_stat_hook
! 3217: If non-zero, this is the address of a function for the completer to
! 3218: call before deciding which character to append to a completed name.
! 3219: This function modifies its filename name argument, and the
! 3220: modified value is passed to `stat()' to determine the file's type
! 3221: and characteristics. This function does not need to remove quote
! 3222: characters from the filename.
! 3223:
! 3224: The stat hook returns an integer that should be non-zero if the
! 3225: function modfies its directory argument. The function should not
! 3226: modify the directory argument if it returns 0.
! 3227:
! 3228: -- Variable: rl_dequote_func_t * rl_filename_rewrite_hook
! 3229: If non-zero, this is the address of a function called when reading
! 3230: directory entries from the filesystem for completion and comparing
! 3231: them to the partial word to be completed. The function should
! 3232: perform any necessary application or system-specific conversion on
! 3233: the filename, such as converting between character sets or
! 3234: converting from a filesystem format to a character input format.
! 3235: The function takes two arguments: FNAME, the filename to be
! 3236: converted, and FNLEN, its length in bytes. It must either return
! 3237: its first argument (if no conversion takes place) or the converted
! 3238: filename in newly-allocated memory. The converted form is used to
! 3239: compare against the word to be completed, and, if it matches, is
! 3240: added to the list of matches. Readline will free the allocated
! 3241: string.
! 3242:
! 3243: -- Variable: rl_compdisp_func_t * rl_completion_display_matches_hook
! 3244: If non-zero, then this is the address of a function to call when
! 3245: completing a word would normally display the list of possible
! 3246: matches. This function is called in lieu of Readline displaying
! 3247: the list. It takes three arguments: (`char **'MATCHES, `int'
! 3248: NUM_MATCHES, `int' MAX_LENGTH) where MATCHES is the array of
! 3249: matching strings, NUM_MATCHES is the number of strings in that
! 3250: array, and MAX_LENGTH is the length of the longest string in that
! 3251: array. Readline provides a convenience function,
! 3252: `rl_display_match_list', that takes care of doing the display to
! 3253: Readline's output stream. That function may be called from this
! 3254: hook.
! 3255:
! 3256: -- Variable: const char * rl_basic_word_break_characters
! 3257: The basic list of characters that signal a break between words for
! 3258: the completer routine. The default value of this variable is the
! 3259: characters which break words for completion in Bash: `"
! 3260: \t\n\"\\'`@$><=;|&{("'.
! 3261:
! 3262: -- Variable: const char * rl_basic_quote_characters
! 3263: A list of quote characters which can cause a word break.
! 3264:
! 3265: -- Variable: const char * rl_completer_word_break_characters
! 3266: The list of characters that signal a break between words for
! 3267: `rl_complete_internal()'. The default list is the value of
! 3268: `rl_basic_word_break_characters'.
! 3269:
! 3270: -- Variable: rl_cpvfunc_t * rl_completion_word_break_hook
! 3271: If non-zero, this is the address of a function to call when
! 3272: Readline is deciding where to separate words for word completion.
! 3273: It should return a character string like
! 3274: `rl_completer_word_break_characters' to be used to perform the
! 3275: current completion. The function may choose to set
! 3276: `rl_completer_word_break_characters' itself. If the function
! 3277: returns `NULL', `rl_completer_word_break_characters' is used.
! 3278:
! 3279: -- Variable: const char * rl_completer_quote_characters
! 3280: A list of characters which can be used to quote a substring of the
! 3281: line. Completion occurs on the entire substring, and within the
! 3282: substring `rl_completer_word_break_characters' are treated as any
! 3283: other character, unless they also appear within this list.
! 3284:
! 3285: -- Variable: const char * rl_filename_quote_characters
! 3286: A list of characters that cause a filename to be quoted by the
! 3287: completer when they appear in a completed filename. The default
! 3288: is the null string.
! 3289:
! 3290: -- Variable: const char * rl_special_prefixes
! 3291: The list of characters that are word break characters, but should
! 3292: be left in TEXT when it is passed to the completion function.
! 3293: Programs can use this to help determine what kind of completing to
! 3294: do. For instance, Bash sets this variable to "$@" so that it can
! 3295: complete shell variables and hostnames.
! 3296:
! 3297: -- Variable: int rl_completion_query_items
! 3298: Up to this many items will be displayed in response to a
! 3299: possible-completions call. After that, readline asks the user if
! 3300: she is sure she wants to see them all. The default value is 100.
! 3301: A negative value indicates that Readline should never ask the user.
! 3302:
! 3303: -- Variable: int rl_completion_append_character
! 3304: When a single completion alternative matches at the end of the
! 3305: command line, this character is appended to the inserted
! 3306: completion text. The default is a space character (` '). Setting
! 3307: this to the null character (`\0') prevents anything being appended
! 3308: automatically. This can be changed in application-specific
! 3309: completion functions to provide the "most sensible word separator
! 3310: character" according to an application-specific command line
! 3311: syntax specification.
! 3312:
! 3313: -- Variable: int rl_completion_suppress_append
! 3314: If non-zero, RL_COMPLETION_APPEND_CHARACTER is not appended to
! 3315: matches at the end of the command line, as described above. It is
! 3316: set to 0 before any application-specific completion function is
! 3317: called, and may only be changed within such a function.
! 3318:
! 3319: -- Variable: int rl_completion_quote_character
! 3320: When Readline is completing quoted text, as delimited by one of the
! 3321: characters in RL_COMPLETER_QUOTE_CHARACTERS, it sets this variable
! 3322: to the quoting character found. This is set before any
! 3323: application-specific completion function is called.
! 3324:
! 3325: -- Variable: int rl_completion_suppress_quote
! 3326: If non-zero, Readline does not append a matching quote character
! 3327: when performing completion on a quoted string. It is set to 0
! 3328: before any application-specific completion function is called, and
! 3329: may only be changed within such a function.
! 3330:
! 3331: -- Variable: int rl_completion_found_quote
! 3332: When Readline is completing quoted text, it sets this variable to
! 3333: a non-zero value if the word being completed contains or is
! 3334: delimited by any quoting characters, including backslashes. This
! 3335: is set before any application-specific completion function is
! 3336: called.
! 3337:
! 3338: -- Variable: int rl_completion_mark_symlink_dirs
! 3339: If non-zero, a slash will be appended to completed filenames that
! 3340: are symbolic links to directory names, subject to the value of the
! 3341: user-settable MARK-DIRECTORIES variable. This variable exists so
! 3342: that application-specific completion functions can override the
! 3343: user's global preference (set via the MARK-SYMLINKED-DIRECTORIES
! 3344: Readline variable) if appropriate. This variable is set to the
! 3345: user's preference before any application-specific completion
! 3346: function is called, so unless that function modifies the value,
! 3347: the user's preferences are honored.
! 3348:
! 3349: -- Variable: int rl_ignore_completion_duplicates
! 3350: If non-zero, then duplicates in the matches are removed. The
! 3351: default is 1.
! 3352:
! 3353: -- Variable: int rl_filename_completion_desired
! 3354: Non-zero means that the results of the matches are to be treated as
! 3355: filenames. This is _always_ zero when completion is attempted,
! 3356: and can only be changed within an application-specific completion
! 3357: function. If it is set to a non-zero value by such a function,
! 3358: directory names have a slash appended and Readline attempts to
! 3359: quote completed filenames if they contain any characters in
! 3360: `rl_filename_quote_characters' and `rl_filename_quoting_desired'
! 3361: is set to a non-zero value.
! 3362:
! 3363: -- Variable: int rl_filename_quoting_desired
! 3364: Non-zero means that the results of the matches are to be quoted
! 3365: using double quotes (or an application-specific quoting mechanism)
! 3366: if the completed filename contains any characters in
! 3367: `rl_filename_quote_chars'. This is _always_ non-zero when
! 3368: completion is attempted, and can only be changed within an
! 3369: application-specific completion function. The quoting is effected
! 3370: via a call to the function pointed to by
! 3371: `rl_filename_quoting_function'.
! 3372:
! 3373: -- Variable: int rl_attempted_completion_over
! 3374: If an application-specific completion function assigned to
! 3375: `rl_attempted_completion_function' sets this variable to a non-zero
! 3376: value, Readline will not perform its default filename completion
! 3377: even if the application's completion function returns no matches.
! 3378: It should be set only by an application's completion function.
! 3379:
! 3380: -- Variable: int rl_sort_completion_matches
! 3381: If an application sets this variable to 0, Readline will not sort
! 3382: the list of completions (which implies that it cannot remove any
! 3383: duplicate completions). The default value is 1, which means that
! 3384: Readline will sort the completions and, depending on the value of
! 3385: `rl_ignore_completion_duplicates', will attempt to remove duplicate
! 3386: matches.
! 3387:
! 3388: -- Variable: int rl_completion_type
! 3389: Set to a character describing the type of completion Readline is
! 3390: currently attempting; see the description of
! 3391: `rl_complete_internal()' (*note Completion Functions::) for the
! 3392: list of characters. This is set to the appropriate value before
! 3393: any application-specific completion function is called, allowing
! 3394: such functions to present the same interface as `rl_complete()'.
! 3395:
! 3396: -- Variable: int rl_completion_invoking_key
! 3397: Set to the final character in the key sequence that invoked one of
! 3398: the completion functions that call `rl_complete_internal()'. This
! 3399: is set to the appropriate value before any application-specific
! 3400: completion function is called.
! 3401:
! 3402: -- Variable: int rl_inhibit_completion
! 3403: If this variable is non-zero, completion is inhibited. The
! 3404: completion character will be inserted as any other bound to
! 3405: `self-insert'.
! 3406:
! 3407:
! 3408: File: readline.info, Node: A Short Completion Example, Prev: Completion Variables, Up: Custom Completers
! 3409:
! 3410: 2.6.4 A Short Completion Example
! 3411: --------------------------------
! 3412:
! 3413: Here is a small application demonstrating the use of the GNU Readline
! 3414: library. It is called `fileman', and the source code resides in
! 3415: `examples/fileman.c'. This sample application provides completion of
! 3416: command names, line editing features, and access to the history list.
! 3417:
! 3418: /* fileman.c -- A tiny application which demonstrates how to use the
! 3419: GNU Readline library. This application interactively allows users
! 3420: to manipulate files and their modes. */
! 3421:
! 3422: #ifdef HAVE_CONFIG_H
! 3423: # include <config.h>
! 3424: #endif
! 3425:
! 3426: #include <sys/types.h>
! 3427: #ifdef HAVE_SYS_FILE_H
! 3428: # include <sys/file.h>
! 3429: #endif
! 3430: #include <sys/stat.h>
! 3431:
! 3432: #ifdef HAVE_UNISTD_H
! 3433: # include <unistd.h>
! 3434: #endif
! 3435:
! 3436: #include <fcntl.h>
! 3437: #include <stdio.h>
! 3438: #include <errno.h>
! 3439:
! 3440: #if defined (HAVE_STRING_H)
! 3441: # include <string.h>
! 3442: #else /* !HAVE_STRING_H */
! 3443: # include <strings.h>
! 3444: #endif /* !HAVE_STRING_H */
! 3445:
! 3446: #ifdef HAVE_STDLIB_H
! 3447: # include <stdlib.h>
! 3448: #endif
! 3449:
! 3450: #include <time.h>
! 3451:
! 3452: #include <readline/readline.h>
! 3453: #include <readline/history.h>
! 3454:
! 3455: extern char *xmalloc PARAMS((size_t));
! 3456:
! 3457: /* The names of functions that actually do the manipulation. */
! 3458: int com_list PARAMS((char *));
! 3459: int com_view PARAMS((char *));
! 3460: int com_rename PARAMS((char *));
! 3461: int com_stat PARAMS((char *));
! 3462: int com_pwd PARAMS((char *));
! 3463: int com_delete PARAMS((char *));
! 3464: int com_help PARAMS((char *));
! 3465: int com_cd PARAMS((char *));
! 3466: int com_quit PARAMS((char *));
! 3467:
! 3468: /* A structure which contains information on the commands this program
! 3469: can understand. */
! 3470:
! 3471: typedef struct {
! 3472: char *name; /* User printable name of the function. */
! 3473: rl_icpfunc_t *func; /* Function to call to do the job. */
! 3474: char *doc; /* Documentation for this function. */
! 3475: } COMMAND;
! 3476:
! 3477: COMMAND commands[] = {
! 3478: { "cd", com_cd, "Change to directory DIR" },
! 3479: { "delete", com_delete, "Delete FILE" },
! 3480: { "help", com_help, "Display this text" },
! 3481: { "?", com_help, "Synonym for `help'" },
! 3482: { "list", com_list, "List files in DIR" },
! 3483: { "ls", com_list, "Synonym for `list'" },
! 3484: { "pwd", com_pwd, "Print the current working directory" },
! 3485: { "quit", com_quit, "Quit using Fileman" },
! 3486: { "rename", com_rename, "Rename FILE to NEWNAME" },
! 3487: { "stat", com_stat, "Print out statistics on FILE" },
! 3488: { "view", com_view, "View the contents of FILE" },
! 3489: { (char *)NULL, (rl_icpfunc_t *)NULL, (char *)NULL }
! 3490: };
! 3491:
! 3492: /* Forward declarations. */
! 3493: char *stripwhite ();
! 3494: COMMAND *find_command ();
! 3495:
! 3496: /* The name of this program, as taken from argv[0]. */
! 3497: char *progname;
! 3498:
! 3499: /* When non-zero, this global means the user is done using this program. */
! 3500: int done;
! 3501:
! 3502: char *
! 3503: dupstr (s)
! 3504: char *s;
! 3505: {
! 3506: char *r;
! 3507:
! 3508: r = xmalloc (strlen (s) + 1);
! 3509: strcpy (r, s);
! 3510: return (r);
! 3511: }
! 3512:
! 3513: main (argc, argv)
! 3514: int argc;
! 3515: char **argv;
! 3516: {
! 3517: char *line, *s;
! 3518:
! 3519: progname = argv[0];
! 3520:
! 3521: initialize_readline (); /* Bind our completer. */
! 3522:
! 3523: /* Loop reading and executing lines until the user quits. */
! 3524: for ( ; done == 0; )
! 3525: {
! 3526: line = readline ("FileMan: ");
! 3527:
! 3528: if (!line)
! 3529: break;
! 3530:
! 3531: /* Remove leading and trailing whitespace from the line.
! 3532: Then, if there is anything left, add it to the history list
! 3533: and execute it. */
! 3534: s = stripwhite (line);
! 3535:
! 3536: if (*s)
! 3537: {
! 3538: add_history (s);
! 3539: execute_line (s);
! 3540: }
! 3541:
! 3542: free (line);
! 3543: }
! 3544: exit (0);
! 3545: }
! 3546:
! 3547: /* Execute a command line. */
! 3548: int
! 3549: execute_line (line)
! 3550: char *line;
! 3551: {
! 3552: register int i;
! 3553: COMMAND *command;
! 3554: char *word;
! 3555:
! 3556: /* Isolate the command word. */
! 3557: i = 0;
! 3558: while (line[i] && whitespace (line[i]))
! 3559: i++;
! 3560: word = line + i;
! 3561:
! 3562: while (line[i] && !whitespace (line[i]))
! 3563: i++;
! 3564:
! 3565: if (line[i])
! 3566: line[i++] = '\0';
! 3567:
! 3568: command = find_command (word);
! 3569:
! 3570: if (!command)
! 3571: {
! 3572: fprintf (stderr, "%s: No such command for FileMan.\n", word);
! 3573: return (-1);
! 3574: }
! 3575:
! 3576: /* Get argument to command, if any. */
! 3577: while (whitespace (line[i]))
! 3578: i++;
! 3579:
! 3580: word = line + i;
! 3581:
! 3582: /* Call the function. */
! 3583: return ((*(command->func)) (word));
! 3584: }
! 3585:
! 3586: /* Look up NAME as the name of a command, and return a pointer to that
! 3587: command. Return a NULL pointer if NAME isn't a command name. */
! 3588: COMMAND *
! 3589: find_command (name)
! 3590: char *name;
! 3591: {
! 3592: register int i;
! 3593:
! 3594: for (i = 0; commands[i].name; i++)
! 3595: if (strcmp (name, commands[i].name) == 0)
! 3596: return (&commands[i]);
! 3597:
! 3598: return ((COMMAND *)NULL);
! 3599: }
! 3600:
! 3601: /* Strip whitespace from the start and end of STRING. Return a pointer
! 3602: into STRING. */
! 3603: char *
! 3604: stripwhite (string)
! 3605: char *string;
! 3606: {
! 3607: register char *s, *t;
! 3608:
! 3609: for (s = string; whitespace (*s); s++)
! 3610: ;
! 3611:
! 3612: if (*s == 0)
! 3613: return (s);
! 3614:
! 3615: t = s + strlen (s) - 1;
! 3616: while (t > s && whitespace (*t))
! 3617: t--;
! 3618: *++t = '\0';
! 3619:
! 3620: return s;
! 3621: }
! 3622:
! 3623: /* **************************************************************** */
! 3624: /* */
! 3625: /* Interface to Readline Completion */
! 3626: /* */
! 3627: /* **************************************************************** */
! 3628:
! 3629: char *command_generator PARAMS((const char *, int));
! 3630: char **fileman_completion PARAMS((const char *, int, int));
! 3631:
! 3632: /* Tell the GNU Readline library how to complete. We want to try to complete
! 3633: on command names if this is the first word in the line, or on filenames
! 3634: if not. */
! 3635: initialize_readline ()
! 3636: {
! 3637: /* Allow conditional parsing of the ~/.inputrc file. */
! 3638: rl_readline_name = "FileMan";
! 3639:
! 3640: /* Tell the completer that we want a crack first. */
! 3641: rl_attempted_completion_function = fileman_completion;
! 3642: }
! 3643:
! 3644: /* Attempt to complete on the contents of TEXT. START and END bound the
! 3645: region of rl_line_buffer that contains the word to complete. TEXT is
! 3646: the word to complete. We can use the entire contents of rl_line_buffer
! 3647: in case we want to do some simple parsing. Return the array of matches,
! 3648: or NULL if there aren't any. */
! 3649: char **
! 3650: fileman_completion (text, start, end)
! 3651: const char *text;
! 3652: int start, end;
! 3653: {
! 3654: char **matches;
! 3655:
! 3656: matches = (char **)NULL;
! 3657:
! 3658: /* If this word is at the start of the line, then it is a command
! 3659: to complete. Otherwise it is the name of a file in the current
! 3660: directory. */
! 3661: if (start == 0)
! 3662: matches = rl_completion_matches (text, command_generator);
! 3663:
! 3664: return (matches);
! 3665: }
! 3666:
! 3667: /* Generator function for command completion. STATE lets us know whether
! 3668: to start from scratch; without any state (i.e. STATE == 0), then we
! 3669: start at the top of the list. */
! 3670: char *
! 3671: command_generator (text, state)
! 3672: const char *text;
! 3673: int state;
! 3674: {
! 3675: static int list_index, len;
! 3676: char *name;
! 3677:
! 3678: /* If this is a new word to complete, initialize now. This includes
! 3679: saving the length of TEXT for efficiency, and initializing the index
! 3680: variable to 0. */
! 3681: if (!state)
! 3682: {
! 3683: list_index = 0;
! 3684: len = strlen (text);
! 3685: }
! 3686:
! 3687: /* Return the next name which partially matches from the command list. */
! 3688: while (name = commands[list_index].name)
! 3689: {
! 3690: list_index++;
! 3691:
! 3692: if (strncmp (name, text, len) == 0)
! 3693: return (dupstr(name));
! 3694: }
! 3695:
! 3696: /* If no names matched, then return NULL. */
! 3697: return ((char *)NULL);
! 3698: }
! 3699:
! 3700: /* **************************************************************** */
! 3701: /* */
! 3702: /* FileMan Commands */
! 3703: /* */
! 3704: /* **************************************************************** */
! 3705:
! 3706: /* String to pass to system (). This is for the LIST, VIEW and RENAME
! 3707: commands. */
! 3708: static char syscom[1024];
! 3709:
! 3710: /* List the file(s) named in arg. */
! 3711: com_list (arg)
! 3712: char *arg;
! 3713: {
! 3714: if (!arg)
! 3715: arg = "";
! 3716:
! 3717: sprintf (syscom, "ls -FClg %s", arg);
! 3718: return (system (syscom));
! 3719: }
! 3720:
! 3721: com_view (arg)
! 3722: char *arg;
! 3723: {
! 3724: if (!valid_argument ("view", arg))
! 3725: return 1;
! 3726:
! 3727: #if defined (__MSDOS__)
! 3728: /* more.com doesn't grok slashes in pathnames */
! 3729: sprintf (syscom, "less %s", arg);
! 3730: #else
! 3731: sprintf (syscom, "more %s", arg);
! 3732: #endif
! 3733: return (system (syscom));
! 3734: }
! 3735:
! 3736: com_rename (arg)
! 3737: char *arg;
! 3738: {
! 3739: too_dangerous ("rename");
! 3740: return (1);
! 3741: }
! 3742:
! 3743: com_stat (arg)
! 3744: char *arg;
! 3745: {
! 3746: struct stat finfo;
! 3747:
! 3748: if (!valid_argument ("stat", arg))
! 3749: return (1);
! 3750:
! 3751: if (stat (arg, &finfo) == -1)
! 3752: {
! 3753: perror (arg);
! 3754: return (1);
! 3755: }
! 3756:
! 3757: printf ("Statistics for `%s':\n", arg);
! 3758:
! 3759: printf ("%s has %d link%s, and is %d byte%s in length.\n",
! 3760: arg,
! 3761: finfo.st_nlink,
! 3762: (finfo.st_nlink == 1) ? "" : "s",
! 3763: finfo.st_size,
! 3764: (finfo.st_size == 1) ? "" : "s");
! 3765: printf ("Inode Last Change at: %s", ctime (&finfo.st_ctime));
! 3766: printf (" Last access at: %s", ctime (&finfo.st_atime));
! 3767: printf (" Last modified at: %s", ctime (&finfo.st_mtime));
! 3768: return (0);
! 3769: }
! 3770:
! 3771: com_delete (arg)
! 3772: char *arg;
! 3773: {
! 3774: too_dangerous ("delete");
! 3775: return (1);
! 3776: }
! 3777:
! 3778: /* Print out help for ARG, or for all of the commands if ARG is
! 3779: not present. */
! 3780: com_help (arg)
! 3781: char *arg;
! 3782: {
! 3783: register int i;
! 3784: int printed = 0;
! 3785:
! 3786: for (i = 0; commands[i].name; i++)
! 3787: {
! 3788: if (!*arg || (strcmp (arg, commands[i].name) == 0))
! 3789: {
! 3790: printf ("%s\t\t%s.\n", commands[i].name, commands[i].doc);
! 3791: printed++;
! 3792: }
! 3793: }
! 3794:
! 3795: if (!printed)
! 3796: {
! 3797: printf ("No commands match `%s'. Possibilties are:\n", arg);
! 3798:
! 3799: for (i = 0; commands[i].name; i++)
! 3800: {
! 3801: /* Print in six columns. */
! 3802: if (printed == 6)
! 3803: {
! 3804: printed = 0;
! 3805: printf ("\n");
! 3806: }
! 3807:
! 3808: printf ("%s\t", commands[i].name);
! 3809: printed++;
! 3810: }
! 3811:
! 3812: if (printed)
! 3813: printf ("\n");
! 3814: }
! 3815: return (0);
! 3816: }
! 3817:
! 3818: /* Change to the directory ARG. */
! 3819: com_cd (arg)
! 3820: char *arg;
! 3821: {
! 3822: if (chdir (arg) == -1)
! 3823: {
! 3824: perror (arg);
! 3825: return 1;
! 3826: }
! 3827:
! 3828: com_pwd ("");
! 3829: return (0);
! 3830: }
! 3831:
! 3832: /* Print out the current working directory. */
! 3833: com_pwd (ignore)
! 3834: char *ignore;
! 3835: {
! 3836: char dir[1024], *s;
! 3837:
! 3838: s = getcwd (dir, sizeof(dir) - 1);
! 3839: if (s == 0)
! 3840: {
! 3841: printf ("Error getting pwd: %s\n", dir);
! 3842: return 1;
! 3843: }
! 3844:
! 3845: printf ("Current directory is %s\n", dir);
! 3846: return 0;
! 3847: }
! 3848:
! 3849: /* The user wishes to quit using this program. Just set DONE non-zero. */
! 3850: com_quit (arg)
! 3851: char *arg;
! 3852: {
! 3853: done = 1;
! 3854: return (0);
! 3855: }
! 3856:
! 3857: /* Function which tells you that you can't do this. */
! 3858: too_dangerous (caller)
! 3859: char *caller;
! 3860: {
! 3861: fprintf (stderr,
! 3862: "%s: Too dangerous for me to distribute. Write it yourself.\n",
! 3863: caller);
! 3864: }
! 3865:
! 3866: /* Return non-zero if ARG is a valid argument for CALLER, else print
! 3867: an error message and return zero. */
! 3868: int
! 3869: valid_argument (caller, arg)
! 3870: char *caller, *arg;
! 3871: {
! 3872: if (!arg || !*arg)
! 3873: {
! 3874: fprintf (stderr, "%s: Argument required.\n", caller);
! 3875: return (0);
! 3876: }
! 3877:
! 3878: return (1);
! 3879: }
! 3880:
! 3881:
! 3882: File: readline.info, Node: GNU Free Documentation License, Next: Concept Index, Prev: Programming with GNU Readline, Up: Top
! 3883:
! 3884: Appendix A GNU Free Documentation License
! 3885: *****************************************
! 3886:
! 3887: Version 1.3, 3 November 2008
! 3888:
! 3889: Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
! 3890: `http://fsf.org/'
! 3891:
! 3892: Everyone is permitted to copy and distribute verbatim copies
! 3893: of this license document, but changing it is not allowed.
! 3894:
! 3895: 0. PREAMBLE
! 3896:
! 3897: The purpose of this License is to make a manual, textbook, or other
! 3898: functional and useful document "free" in the sense of freedom: to
! 3899: assure everyone the effective freedom to copy and redistribute it,
! 3900: with or without modifying it, either commercially or
! 3901: noncommercially. Secondarily, this License preserves for the
! 3902: author and publisher a way to get credit for their work, while not
! 3903: being considered responsible for modifications made by others.
! 3904:
! 3905: This License is a kind of "copyleft", which means that derivative
! 3906: works of the document must themselves be free in the same sense.
! 3907: It complements the GNU General Public License, which is a copyleft
! 3908: license designed for free software.
! 3909:
! 3910: We have designed this License in order to use it for manuals for
! 3911: free software, because free software needs free documentation: a
! 3912: free program should come with manuals providing the same freedoms
! 3913: that the software does. But this License is not limited to
! 3914: software manuals; it can be used for any textual work, regardless
! 3915: of subject matter or whether it is published as a printed book.
! 3916: We recommend this License principally for works whose purpose is
! 3917: instruction or reference.
! 3918:
! 3919: 1. APPLICABILITY AND DEFINITIONS
! 3920:
! 3921: This License applies to any manual or other work, in any medium,
! 3922: that contains a notice placed by the copyright holder saying it
! 3923: can be distributed under the terms of this License. Such a notice
! 3924: grants a world-wide, royalty-free license, unlimited in duration,
! 3925: to use that work under the conditions stated herein. The
! 3926: "Document", below, refers to any such manual or work. Any member
! 3927: of the public is a licensee, and is addressed as "you". You
! 3928: accept the license if you copy, modify or distribute the work in a
! 3929: way requiring permission under copyright law.
! 3930:
! 3931: A "Modified Version" of the Document means any work containing the
! 3932: Document or a portion of it, either copied verbatim, or with
! 3933: modifications and/or translated into another language.
! 3934:
! 3935: A "Secondary Section" is a named appendix or a front-matter section
! 3936: of the Document that deals exclusively with the relationship of the
! 3937: publishers or authors of the Document to the Document's overall
! 3938: subject (or to related matters) and contains nothing that could
! 3939: fall directly within that overall subject. (Thus, if the Document
! 3940: is in part a textbook of mathematics, a Secondary Section may not
! 3941: explain any mathematics.) The relationship could be a matter of
! 3942: historical connection with the subject or with related matters, or
! 3943: of legal, commercial, philosophical, ethical or political position
! 3944: regarding them.
! 3945:
! 3946: The "Invariant Sections" are certain Secondary Sections whose
! 3947: titles are designated, as being those of Invariant Sections, in
! 3948: the notice that says that the Document is released under this
! 3949: License. If a section does not fit the above definition of
! 3950: Secondary then it is not allowed to be designated as Invariant.
! 3951: The Document may contain zero Invariant Sections. If the Document
! 3952: does not identify any Invariant Sections then there are none.
! 3953:
! 3954: The "Cover Texts" are certain short passages of text that are
! 3955: listed, as Front-Cover Texts or Back-Cover Texts, in the notice
! 3956: that says that the Document is released under this License. A
! 3957: Front-Cover Text may be at most 5 words, and a Back-Cover Text may
! 3958: be at most 25 words.
! 3959:
! 3960: A "Transparent" copy of the Document means a machine-readable copy,
! 3961: represented in a format whose specification is available to the
! 3962: general public, that is suitable for revising the document
! 3963: straightforwardly with generic text editors or (for images
! 3964: composed of pixels) generic paint programs or (for drawings) some
! 3965: widely available drawing editor, and that is suitable for input to
! 3966: text formatters or for automatic translation to a variety of
! 3967: formats suitable for input to text formatters. A copy made in an
! 3968: otherwise Transparent file format whose markup, or absence of
! 3969: markup, has been arranged to thwart or discourage subsequent
! 3970: modification by readers is not Transparent. An image format is
! 3971: not Transparent if used for any substantial amount of text. A
! 3972: copy that is not "Transparent" is called "Opaque".
! 3973:
! 3974: Examples of suitable formats for Transparent copies include plain
! 3975: ASCII without markup, Texinfo input format, LaTeX input format,
! 3976: SGML or XML using a publicly available DTD, and
! 3977: standard-conforming simple HTML, PostScript or PDF designed for
! 3978: human modification. Examples of transparent image formats include
! 3979: PNG, XCF and JPG. Opaque formats include proprietary formats that
! 3980: can be read and edited only by proprietary word processors, SGML or
! 3981: XML for which the DTD and/or processing tools are not generally
! 3982: available, and the machine-generated HTML, PostScript or PDF
! 3983: produced by some word processors for output purposes only.
! 3984:
! 3985: The "Title Page" means, for a printed book, the title page itself,
! 3986: plus such following pages as are needed to hold, legibly, the
! 3987: material this License requires to appear in the title page. For
! 3988: works in formats which do not have any title page as such, "Title
! 3989: Page" means the text near the most prominent appearance of the
! 3990: work's title, preceding the beginning of the body of the text.
! 3991:
! 3992: The "publisher" means any person or entity that distributes copies
! 3993: of the Document to the public.
! 3994:
! 3995: A section "Entitled XYZ" means a named subunit of the Document
! 3996: whose title either is precisely XYZ or contains XYZ in parentheses
! 3997: following text that translates XYZ in another language. (Here XYZ
! 3998: stands for a specific section name mentioned below, such as
! 3999: "Acknowledgements", "Dedications", "Endorsements", or "History".)
! 4000: To "Preserve the Title" of such a section when you modify the
! 4001: Document means that it remains a section "Entitled XYZ" according
! 4002: to this definition.
! 4003:
! 4004: The Document may include Warranty Disclaimers next to the notice
! 4005: which states that this License applies to the Document. These
! 4006: Warranty Disclaimers are considered to be included by reference in
! 4007: this License, but only as regards disclaiming warranties: any other
! 4008: implication that these Warranty Disclaimers may have is void and
! 4009: has no effect on the meaning of this License.
! 4010:
! 4011: 2. VERBATIM COPYING
! 4012:
! 4013: You may copy and distribute the Document in any medium, either
! 4014: commercially or noncommercially, provided that this License, the
! 4015: copyright notices, and the license notice saying this License
! 4016: applies to the Document are reproduced in all copies, and that you
! 4017: add no other conditions whatsoever to those of this License. You
! 4018: may not use technical measures to obstruct or control the reading
! 4019: or further copying of the copies you make or distribute. However,
! 4020: you may accept compensation in exchange for copies. If you
! 4021: distribute a large enough number of copies you must also follow
! 4022: the conditions in section 3.
! 4023:
! 4024: You may also lend copies, under the same conditions stated above,
! 4025: and you may publicly display copies.
! 4026:
! 4027: 3. COPYING IN QUANTITY
! 4028:
! 4029: If you publish printed copies (or copies in media that commonly
! 4030: have printed covers) of the Document, numbering more than 100, and
! 4031: the Document's license notice requires Cover Texts, you must
! 4032: enclose the copies in covers that carry, clearly and legibly, all
! 4033: these Cover Texts: Front-Cover Texts on the front cover, and
! 4034: Back-Cover Texts on the back cover. Both covers must also clearly
! 4035: and legibly identify you as the publisher of these copies. The
! 4036: front cover must present the full title with all words of the
! 4037: title equally prominent and visible. You may add other material
! 4038: on the covers in addition. Copying with changes limited to the
! 4039: covers, as long as they preserve the title of the Document and
! 4040: satisfy these conditions, can be treated as verbatim copying in
! 4041: other respects.
! 4042:
! 4043: If the required texts for either cover are too voluminous to fit
! 4044: legibly, you should put the first ones listed (as many as fit
! 4045: reasonably) on the actual cover, and continue the rest onto
! 4046: adjacent pages.
! 4047:
! 4048: If you publish or distribute Opaque copies of the Document
! 4049: numbering more than 100, you must either include a
! 4050: machine-readable Transparent copy along with each Opaque copy, or
! 4051: state in or with each Opaque copy a computer-network location from
! 4052: which the general network-using public has access to download
! 4053: using public-standard network protocols a complete Transparent
! 4054: copy of the Document, free of added material. If you use the
! 4055: latter option, you must take reasonably prudent steps, when you
! 4056: begin distribution of Opaque copies in quantity, to ensure that
! 4057: this Transparent copy will remain thus accessible at the stated
! 4058: location until at least one year after the last time you
! 4059: distribute an Opaque copy (directly or through your agents or
! 4060: retailers) of that edition to the public.
! 4061:
! 4062: It is requested, but not required, that you contact the authors of
! 4063: the Document well before redistributing any large number of
! 4064: copies, to give them a chance to provide you with an updated
! 4065: version of the Document.
! 4066:
! 4067: 4. MODIFICATIONS
! 4068:
! 4069: You may copy and distribute a Modified Version of the Document
! 4070: under the conditions of sections 2 and 3 above, provided that you
! 4071: release the Modified Version under precisely this License, with
! 4072: the Modified Version filling the role of the Document, thus
! 4073: licensing distribution and modification of the Modified Version to
! 4074: whoever possesses a copy of it. In addition, you must do these
! 4075: things in the Modified Version:
! 4076:
! 4077: A. Use in the Title Page (and on the covers, if any) a title
! 4078: distinct from that of the Document, and from those of
! 4079: previous versions (which should, if there were any, be listed
! 4080: in the History section of the Document). You may use the
! 4081: same title as a previous version if the original publisher of
! 4082: that version gives permission.
! 4083:
! 4084: B. List on the Title Page, as authors, one or more persons or
! 4085: entities responsible for authorship of the modifications in
! 4086: the Modified Version, together with at least five of the
! 4087: principal authors of the Document (all of its principal
! 4088: authors, if it has fewer than five), unless they release you
! 4089: from this requirement.
! 4090:
! 4091: C. State on the Title page the name of the publisher of the
! 4092: Modified Version, as the publisher.
! 4093:
! 4094: D. Preserve all the copyright notices of the Document.
! 4095:
! 4096: E. Add an appropriate copyright notice for your modifications
! 4097: adjacent to the other copyright notices.
! 4098:
! 4099: F. Include, immediately after the copyright notices, a license
! 4100: notice giving the public permission to use the Modified
! 4101: Version under the terms of this License, in the form shown in
! 4102: the Addendum below.
! 4103:
! 4104: G. Preserve in that license notice the full lists of Invariant
! 4105: Sections and required Cover Texts given in the Document's
! 4106: license notice.
! 4107:
! 4108: H. Include an unaltered copy of this License.
! 4109:
! 4110: I. Preserve the section Entitled "History", Preserve its Title,
! 4111: and add to it an item stating at least the title, year, new
! 4112: authors, and publisher of the Modified Version as given on
! 4113: the Title Page. If there is no section Entitled "History" in
! 4114: the Document, create one stating the title, year, authors,
! 4115: and publisher of the Document as given on its Title Page,
! 4116: then add an item describing the Modified Version as stated in
! 4117: the previous sentence.
! 4118:
! 4119: J. Preserve the network location, if any, given in the Document
! 4120: for public access to a Transparent copy of the Document, and
! 4121: likewise the network locations given in the Document for
! 4122: previous versions it was based on. These may be placed in
! 4123: the "History" section. You may omit a network location for a
! 4124: work that was published at least four years before the
! 4125: Document itself, or if the original publisher of the version
! 4126: it refers to gives permission.
! 4127:
! 4128: K. For any section Entitled "Acknowledgements" or "Dedications",
! 4129: Preserve the Title of the section, and preserve in the
! 4130: section all the substance and tone of each of the contributor
! 4131: acknowledgements and/or dedications given therein.
! 4132:
! 4133: L. Preserve all the Invariant Sections of the Document,
! 4134: unaltered in their text and in their titles. Section numbers
! 4135: or the equivalent are not considered part of the section
! 4136: titles.
! 4137:
! 4138: M. Delete any section Entitled "Endorsements". Such a section
! 4139: may not be included in the Modified Version.
! 4140:
! 4141: N. Do not retitle any existing section to be Entitled
! 4142: "Endorsements" or to conflict in title with any Invariant
! 4143: Section.
! 4144:
! 4145: O. Preserve any Warranty Disclaimers.
! 4146:
! 4147: If the Modified Version includes new front-matter sections or
! 4148: appendices that qualify as Secondary Sections and contain no
! 4149: material copied from the Document, you may at your option
! 4150: designate some or all of these sections as invariant. To do this,
! 4151: add their titles to the list of Invariant Sections in the Modified
! 4152: Version's license notice. These titles must be distinct from any
! 4153: other section titles.
! 4154:
! 4155: You may add a section Entitled "Endorsements", provided it contains
! 4156: nothing but endorsements of your Modified Version by various
! 4157: parties--for example, statements of peer review or that the text
! 4158: has been approved by an organization as the authoritative
! 4159: definition of a standard.
! 4160:
! 4161: You may add a passage of up to five words as a Front-Cover Text,
! 4162: and a passage of up to 25 words as a Back-Cover Text, to the end
! 4163: of the list of Cover Texts in the Modified Version. Only one
! 4164: passage of Front-Cover Text and one of Back-Cover Text may be
! 4165: added by (or through arrangements made by) any one entity. If the
! 4166: Document already includes a cover text for the same cover,
! 4167: previously added by you or by arrangement made by the same entity
! 4168: you are acting on behalf of, you may not add another; but you may
! 4169: replace the old one, on explicit permission from the previous
! 4170: publisher that added the old one.
! 4171:
! 4172: The author(s) and publisher(s) of the Document do not by this
! 4173: License give permission to use their names for publicity for or to
! 4174: assert or imply endorsement of any Modified Version.
! 4175:
! 4176: 5. COMBINING DOCUMENTS
! 4177:
! 4178: You may combine the Document with other documents released under
! 4179: this License, under the terms defined in section 4 above for
! 4180: modified versions, provided that you include in the combination
! 4181: all of the Invariant Sections of all of the original documents,
! 4182: unmodified, and list them all as Invariant Sections of your
! 4183: combined work in its license notice, and that you preserve all
! 4184: their Warranty Disclaimers.
! 4185:
! 4186: The combined work need only contain one copy of this License, and
! 4187: multiple identical Invariant Sections may be replaced with a single
! 4188: copy. If there are multiple Invariant Sections with the same name
! 4189: but different contents, make the title of each such section unique
! 4190: by adding at the end of it, in parentheses, the name of the
! 4191: original author or publisher of that section if known, or else a
! 4192: unique number. Make the same adjustment to the section titles in
! 4193: the list of Invariant Sections in the license notice of the
! 4194: combined work.
! 4195:
! 4196: In the combination, you must combine any sections Entitled
! 4197: "History" in the various original documents, forming one section
! 4198: Entitled "History"; likewise combine any sections Entitled
! 4199: "Acknowledgements", and any sections Entitled "Dedications". You
! 4200: must delete all sections Entitled "Endorsements."
! 4201:
! 4202: 6. COLLECTIONS OF DOCUMENTS
! 4203:
! 4204: You may make a collection consisting of the Document and other
! 4205: documents released under this License, and replace the individual
! 4206: copies of this License in the various documents with a single copy
! 4207: that is included in the collection, provided that you follow the
! 4208: rules of this License for verbatim copying of each of the
! 4209: documents in all other respects.
! 4210:
! 4211: You may extract a single document from such a collection, and
! 4212: distribute it individually under this License, provided you insert
! 4213: a copy of this License into the extracted document, and follow
! 4214: this License in all other respects regarding verbatim copying of
! 4215: that document.
! 4216:
! 4217: 7. AGGREGATION WITH INDEPENDENT WORKS
! 4218:
! 4219: A compilation of the Document or its derivatives with other
! 4220: separate and independent documents or works, in or on a volume of
! 4221: a storage or distribution medium, is called an "aggregate" if the
! 4222: copyright resulting from the compilation is not used to limit the
! 4223: legal rights of the compilation's users beyond what the individual
! 4224: works permit. When the Document is included in an aggregate, this
! 4225: License does not apply to the other works in the aggregate which
! 4226: are not themselves derivative works of the Document.
! 4227:
! 4228: If the Cover Text requirement of section 3 is applicable to these
! 4229: copies of the Document, then if the Document is less than one half
! 4230: of the entire aggregate, the Document's Cover Texts may be placed
! 4231: on covers that bracket the Document within the aggregate, or the
! 4232: electronic equivalent of covers if the Document is in electronic
! 4233: form. Otherwise they must appear on printed covers that bracket
! 4234: the whole aggregate.
! 4235:
! 4236: 8. TRANSLATION
! 4237:
! 4238: Translation is considered a kind of modification, so you may
! 4239: distribute translations of the Document under the terms of section
! 4240: 4. Replacing Invariant Sections with translations requires special
! 4241: permission from their copyright holders, but you may include
! 4242: translations of some or all Invariant Sections in addition to the
! 4243: original versions of these Invariant Sections. You may include a
! 4244: translation of this License, and all the license notices in the
! 4245: Document, and any Warranty Disclaimers, provided that you also
! 4246: include the original English version of this License and the
! 4247: original versions of those notices and disclaimers. In case of a
! 4248: disagreement between the translation and the original version of
! 4249: this License or a notice or disclaimer, the original version will
! 4250: prevail.
! 4251:
! 4252: If a section in the Document is Entitled "Acknowledgements",
! 4253: "Dedications", or "History", the requirement (section 4) to
! 4254: Preserve its Title (section 1) will typically require changing the
! 4255: actual title.
! 4256:
! 4257: 9. TERMINATION
! 4258:
! 4259: You may not copy, modify, sublicense, or distribute the Document
! 4260: except as expressly provided under this License. Any attempt
! 4261: otherwise to copy, modify, sublicense, or distribute it is void,
! 4262: and will automatically terminate your rights under this License.
! 4263:
! 4264: However, if you cease all violation of this License, then your
! 4265: license from a particular copyright holder is reinstated (a)
! 4266: provisionally, unless and until the copyright holder explicitly
! 4267: and finally terminates your license, and (b) permanently, if the
! 4268: copyright holder fails to notify you of the violation by some
! 4269: reasonable means prior to 60 days after the cessation.
! 4270:
! 4271: Moreover, your license from a particular copyright holder is
! 4272: reinstated permanently if the copyright holder notifies you of the
! 4273: violation by some reasonable means, this is the first time you have
! 4274: received notice of violation of this License (for any work) from
! 4275: that copyright holder, and you cure the violation prior to 30 days
! 4276: after your receipt of the notice.
! 4277:
! 4278: Termination of your rights under this section does not terminate
! 4279: the licenses of parties who have received copies or rights from
! 4280: you under this License. If your rights have been terminated and
! 4281: not permanently reinstated, receipt of a copy of some or all of
! 4282: the same material does not give you any rights to use it.
! 4283:
! 4284: 10. FUTURE REVISIONS OF THIS LICENSE
! 4285:
! 4286: The Free Software Foundation may publish new, revised versions of
! 4287: the GNU Free Documentation License from time to time. Such new
! 4288: versions will be similar in spirit to the present version, but may
! 4289: differ in detail to address new problems or concerns. See
! 4290: `http://www.gnu.org/copyleft/'.
! 4291:
! 4292: Each version of the License is given a distinguishing version
! 4293: number. If the Document specifies that a particular numbered
! 4294: version of this License "or any later version" applies to it, you
! 4295: have the option of following the terms and conditions either of
! 4296: that specified version or of any later version that has been
! 4297: published (not as a draft) by the Free Software Foundation. If
! 4298: the Document does not specify a version number of this License,
! 4299: you may choose any version ever published (not as a draft) by the
! 4300: Free Software Foundation. If the Document specifies that a proxy
! 4301: can decide which future versions of this License can be used, that
! 4302: proxy's public statement of acceptance of a version permanently
! 4303: authorizes you to choose that version for the Document.
! 4304:
! 4305: 11. RELICENSING
! 4306:
! 4307: "Massive Multiauthor Collaboration Site" (or "MMC Site") means any
! 4308: World Wide Web server that publishes copyrightable works and also
! 4309: provides prominent facilities for anybody to edit those works. A
! 4310: public wiki that anybody can edit is an example of such a server.
! 4311: A "Massive Multiauthor Collaboration" (or "MMC") contained in the
! 4312: site means any set of copyrightable works thus published on the MMC
! 4313: site.
! 4314:
! 4315: "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0
! 4316: license published by Creative Commons Corporation, a not-for-profit
! 4317: corporation with a principal place of business in San Francisco,
! 4318: California, as well as future copyleft versions of that license
! 4319: published by that same organization.
! 4320:
! 4321: "Incorporate" means to publish or republish a Document, in whole or
! 4322: in part, as part of another Document.
! 4323:
! 4324: An MMC is "eligible for relicensing" if it is licensed under this
! 4325: License, and if all works that were first published under this
! 4326: License somewhere other than this MMC, and subsequently
! 4327: incorporated in whole or in part into the MMC, (1) had no cover
! 4328: texts or invariant sections, and (2) were thus incorporated prior
! 4329: to November 1, 2008.
! 4330:
! 4331: The operator of an MMC Site may republish an MMC contained in the
! 4332: site under CC-BY-SA on the same site at any time before August 1,
! 4333: 2009, provided the MMC is eligible for relicensing.
! 4334:
! 4335:
! 4336: ADDENDUM: How to use this License for your documents
! 4337: ====================================================
! 4338:
! 4339: To use this License in a document you have written, include a copy of
! 4340: the License in the document and put the following copyright and license
! 4341: notices just after the title page:
! 4342:
! 4343: Copyright (C) YEAR YOUR NAME.
! 4344: Permission is granted to copy, distribute and/or modify this document
! 4345: under the terms of the GNU Free Documentation License, Version 1.3
! 4346: or any later version published by the Free Software Foundation;
! 4347: with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
! 4348: Texts. A copy of the license is included in the section entitled ``GNU
! 4349: Free Documentation License''.
! 4350:
! 4351: If you have Invariant Sections, Front-Cover Texts and Back-Cover
! 4352: Texts, replace the "with...Texts." line with this:
! 4353:
! 4354: with the Invariant Sections being LIST THEIR TITLES, with
! 4355: the Front-Cover Texts being LIST, and with the Back-Cover Texts
! 4356: being LIST.
! 4357:
! 4358: If you have Invariant Sections without Cover Texts, or some other
! 4359: combination of the three, merge those two alternatives to suit the
! 4360: situation.
! 4361:
! 4362: If your document contains nontrivial examples of program code, we
! 4363: recommend releasing these examples in parallel under your choice of
! 4364: free software license, such as the GNU General Public License, to
! 4365: permit their use in free software.
! 4366:
! 4367:
! 4368: File: readline.info, Node: Concept Index, Next: Function and Variable Index, Prev: GNU Free Documentation License, Up: Top
! 4369:
! 4370: Concept Index
! 4371: *************
! 4372:
! 4373: [index ]
! 4374: * Menu:
! 4375:
! 4376: * application-specific completion functions: Custom Completers.
! 4377: (line 6)
! 4378: * command editing: Readline Bare Essentials.
! 4379: (line 6)
! 4380: * editing command lines: Readline Bare Essentials.
! 4381: (line 6)
! 4382: * initialization file, readline: Readline Init File. (line 6)
! 4383: * interaction, readline: Readline Interaction. (line 6)
! 4384: * kill ring: Readline Killing Commands.
! 4385: (line 19)
! 4386: * killing text: Readline Killing Commands.
! 4387: (line 6)
! 4388: * notation, readline: Readline Bare Essentials.
! 4389: (line 6)
! 4390: * readline, function: Basic Behavior. (line 12)
! 4391: * variables, readline: Readline Init File Syntax.
! 4392: (line 34)
! 4393: * yanking text: Readline Killing Commands.
! 4394: (line 6)
! 4395:
! 4396:
! 4397: File: readline.info, Node: Function and Variable Index, Prev: Concept Index, Up: Top
! 4398:
! 4399: Function and Variable Index
! 4400: ***************************
! 4401:
! 4402: [index ]
! 4403: * Menu:
! 4404:
! 4405: * _rl_digit_p: Utility Functions. (line 65)
! 4406: * _rl_digit_value: Utility Functions. (line 76)
! 4407: * _rl_lowercase_p: Utility Functions. (line 62)
! 4408: * _rl_to_lower: Utility Functions. (line 72)
! 4409: * _rl_to_upper: Utility Functions. (line 68)
! 4410: * _rl_uppercase_p: Utility Functions. (line 59)
! 4411: * abort (C-g): Miscellaneous Commands.
! 4412: (line 10)
! 4413: * accept-line (Newline or Return): Commands For History.
! 4414: (line 6)
! 4415: * backward-char (C-b): Commands For Moving. (line 15)
! 4416: * backward-delete-char (Rubout): Commands For Text. (line 17)
! 4417: * backward-kill-line (C-x Rubout): Commands For Killing.
! 4418: (line 9)
! 4419: * backward-kill-word (M-<DEL>): Commands For Killing.
! 4420: (line 24)
! 4421: * backward-word (M-b): Commands For Moving. (line 22)
! 4422: * beginning-of-history (M-<): Commands For History.
! 4423: (line 19)
! 4424: * beginning-of-line (C-a): Commands For Moving. (line 6)
! 4425: * bell-style: Readline Init File Syntax.
! 4426: (line 35)
! 4427: * bind-tty-special-chars: Readline Init File Syntax.
! 4428: (line 42)
! 4429: * call-last-kbd-macro (C-x e): Keyboard Macros. (line 13)
! 4430: * capitalize-word (M-c): Commands For Text. (line 55)
! 4431: * character-search (C-]): Miscellaneous Commands.
! 4432: (line 41)
! 4433: * character-search-backward (M-C-]): Miscellaneous Commands.
! 4434: (line 46)
! 4435: * clear-screen (C-l): Commands For Moving. (line 26)
! 4436: * colored-stats: Readline Init File Syntax.
! 4437: (line 47)
! 4438: * comment-begin: Readline Init File Syntax.
! 4439: (line 53)
! 4440: * complete (<TAB>): Commands For Completion.
! 4441: (line 6)
! 4442: * completion-display-width: Readline Init File Syntax.
! 4443: (line 58)
! 4444: * completion-ignore-case: Readline Init File Syntax.
! 4445: (line 65)
! 4446: * completion-map-case: Readline Init File Syntax.
! 4447: (line 70)
! 4448: * completion-prefix-display-length: Readline Init File Syntax.
! 4449: (line 76)
! 4450: * completion-query-items: Readline Init File Syntax.
! 4451: (line 83)
! 4452: * convert-meta: Readline Init File Syntax.
! 4453: (line 93)
! 4454: * copy-backward-word (): Commands For Killing.
! 4455: (line 49)
! 4456: * copy-forward-word (): Commands For Killing.
! 4457: (line 54)
! 4458: * copy-region-as-kill (): Commands For Killing.
! 4459: (line 45)
! 4460: * delete-char (C-d): Commands For Text. (line 12)
! 4461: * delete-char-or-list (): Commands For Completion.
! 4462: (line 39)
! 4463: * delete-horizontal-space (): Commands For Killing.
! 4464: (line 37)
! 4465: * digit-argument (M-0, M-1, ... M--): Numeric Arguments. (line 6)
! 4466: * disable-completion: Readline Init File Syntax.
! 4467: (line 99)
! 4468: * do-uppercase-version (M-a, M-b, M-X, ...): Miscellaneous Commands.
! 4469: (line 14)
! 4470: * downcase-word (M-l): Commands For Text. (line 51)
! 4471: * dump-functions (): Miscellaneous Commands.
! 4472: (line 70)
! 4473: * dump-macros (): Miscellaneous Commands.
! 4474: (line 82)
! 4475: * dump-variables (): Miscellaneous Commands.
! 4476: (line 76)
! 4477: * editing-mode: Readline Init File Syntax.
! 4478: (line 104)
! 4479: * enable-keypad: Readline Init File Syntax.
! 4480: (line 115)
! 4481: * end-kbd-macro (C-x )): Keyboard Macros. (line 9)
! 4482: * end-of-file (usually C-d): Commands For Text. (line 6)
! 4483: * end-of-history (M->): Commands For History.
! 4484: (line 22)
! 4485: * end-of-line (C-e): Commands For Moving. (line 9)
! 4486: * exchange-point-and-mark (C-x C-x): Miscellaneous Commands.
! 4487: (line 36)
! 4488: * expand-tilde: Readline Init File Syntax.
! 4489: (line 126)
! 4490: * forward-backward-delete-char (): Commands For Text. (line 21)
! 4491: * forward-char (C-f): Commands For Moving. (line 12)
! 4492: * forward-search-history (C-s): Commands For History.
! 4493: (line 30)
! 4494: * forward-word (M-f): Commands For Moving. (line 18)
! 4495: * history-preserve-point: Readline Init File Syntax.
! 4496: (line 130)
! 4497: * history-search-backward (): Commands For History.
! 4498: (line 51)
! 4499: * history-search-forward (): Commands For History.
! 4500: (line 45)
! 4501: * history-size: Readline Init File Syntax.
! 4502: (line 136)
! 4503: * history-substr-search-backward (): Commands For History.
! 4504: (line 63)
! 4505: * history-substr-search-forward (): Commands For History.
! 4506: (line 57)
! 4507: * horizontal-scroll-mode: Readline Init File Syntax.
! 4508: (line 143)
! 4509: * input-meta: Readline Init File Syntax.
! 4510: (line 150)
! 4511: * insert-comment (M-#): Miscellaneous Commands.
! 4512: (line 60)
! 4513: * insert-completions (M-*): Commands For Completion.
! 4514: (line 18)
! 4515: * isearch-terminators: Readline Init File Syntax.
! 4516: (line 157)
! 4517: * keymap: Readline Init File Syntax.
! 4518: (line 164)
! 4519: * kill-line (C-k): Commands For Killing.
! 4520: (line 6)
! 4521: * kill-region (): Commands For Killing.
! 4522: (line 41)
! 4523: * kill-whole-line (): Commands For Killing.
! 4524: (line 15)
! 4525: * kill-word (M-d): Commands For Killing.
! 4526: (line 19)
! 4527: * mark-modified-lines: Readline Init File Syntax.
! 4528: (line 193)
! 4529: * mark-symlinked-directories: Readline Init File Syntax.
! 4530: (line 198)
! 4531: * match-hidden-files: Readline Init File Syntax.
! 4532: (line 203)
! 4533: * menu-complete (): Commands For Completion.
! 4534: (line 22)
! 4535: * menu-complete-backward (): Commands For Completion.
! 4536: (line 34)
! 4537: * menu-complete-display-prefix: Readline Init File Syntax.
! 4538: (line 210)
! 4539: * meta-flag: Readline Init File Syntax.
! 4540: (line 150)
! 4541: * next-history (C-n): Commands For History.
! 4542: (line 16)
! 4543: * non-incremental-forward-search-history (M-n): Commands For History.
! 4544: (line 40)
! 4545: * non-incremental-reverse-search-history (M-p): Commands For History.
! 4546: (line 35)
! 4547: * output-meta: Readline Init File Syntax.
! 4548: (line 215)
! 4549: * overwrite-mode (): Commands For Text. (line 59)
! 4550: * page-completions: Readline Init File Syntax.
! 4551: (line 220)
! 4552: * possible-completions (M-?): Commands For Completion.
! 4553: (line 11)
! 4554: * prefix-meta (<ESC>): Miscellaneous Commands.
! 4555: (line 18)
! 4556: * previous-history (C-p): Commands For History.
! 4557: (line 12)
! 4558: * print-last-kbd-macro (): Keyboard Macros. (line 17)
! 4559: * quoted-insert (C-q or C-v): Commands For Text. (line 26)
! 4560: * re-read-init-file (C-x C-r): Miscellaneous Commands.
! 4561: (line 6)
! 4562: * readline: Basic Behavior. (line 12)
! 4563: * redraw-current-line (): Commands For Moving. (line 30)
! 4564: * reverse-search-history (C-r): Commands For History.
! 4565: (line 26)
! 4566: * revert-all-at-newline: Readline Init File Syntax.
! 4567: (line 230)
! 4568: * revert-line (M-r): Miscellaneous Commands.
! 4569: (line 25)
! 4570: * rl_add_defun: Function Naming. (line 20)
! 4571: * rl_add_funmap_entry: Associating Function Names and Bindings.
! 4572: (line 47)
! 4573: * rl_add_undo: Allowing Undoing. (line 41)
! 4574: * rl_alphabetic: Utility Functions. (line 39)
! 4575: * rl_already_prompted: Readline Variables. (line 64)
! 4576: * rl_attempted_completion_function: Completion Variables.
! 4577: (line 12)
! 4578: * rl_attempted_completion_over: Completion Variables.
! 4579: (line 255)
! 4580: * rl_basic_quote_characters: Completion Variables.
! 4581: (line 144)
! 4582: * rl_basic_word_break_characters: Completion Variables.
! 4583: (line 138)
! 4584: * rl_begin_undo_group: Allowing Undoing. (line 29)
! 4585: * rl_bind_key: Binding Keys. (line 22)
! 4586: * rl_bind_key_if_unbound: Binding Keys. (line 32)
! 4587: * rl_bind_key_if_unbound_in_map: Binding Keys. (line 38)
! 4588: * rl_bind_key_in_map: Binding Keys. (line 27)
! 4589: * rl_bind_keyseq: Binding Keys. (line 59)
! 4590: * rl_bind_keyseq_if_unbound: Binding Keys. (line 77)
! 4591: * rl_bind_keyseq_if_unbound_in_map: Binding Keys. (line 83)
! 4592: * rl_bind_keyseq_in_map: Binding Keys. (line 66)
! 4593: * rl_binding_keymap: Readline Variables. (line 186)
! 4594: * rl_callback_handler_install: Alternate Interface. (line 15)
! 4595: * rl_callback_handler_remove: Alternate Interface. (line 35)
! 4596: * rl_callback_read_char: Alternate Interface. (line 22)
! 4597: * rl_catch_signals: Readline Signal Handling.
! 4598: (line 48)
! 4599: * rl_catch_sigwinch: Readline Signal Handling.
! 4600: (line 55)
! 4601: * rl_change_environment: Readline Signal Handling.
! 4602: (line 61)
! 4603: * rl_char_is_quoted_p: Completion Variables.
! 4604: (line 46)
! 4605: * rl_cleanup_after_signal: Readline Signal Handling.
! 4606: (line 73)
! 4607: * rl_clear_history: Miscellaneous Functions.
! 4608: (line 50)
! 4609: * rl_clear_message: Redisplay. (line 48)
! 4610: * rl_clear_pending_input: Character Input. (line 30)
! 4611: * rl_clear_signals: Readline Signal Handling.
! 4612: (line 132)
! 4613: * rl_complete <1>: How Completing Works.
! 4614: (line 49)
! 4615: * rl_complete: Completion Functions.
! 4616: (line 20)
! 4617: * rl_complete_internal: Completion Functions.
! 4618: (line 10)
! 4619: * rl_completer_quote_characters: Completion Variables.
! 4620: (line 161)
! 4621: * rl_completer_word_break_characters: Completion Variables.
! 4622: (line 147)
! 4623: * rl_completion_append_character: Completion Variables.
! 4624: (line 185)
! 4625: * rl_completion_display_matches_hook: Completion Variables.
! 4626: (line 125)
! 4627: * rl_completion_entry_function <1>: How Completing Works.
! 4628: (line 55)
! 4629: * rl_completion_entry_function: Completion Variables.
! 4630: (line 7)
! 4631: * rl_completion_found_quote: Completion Variables.
! 4632: (line 213)
! 4633: * rl_completion_invoking_key: Completion Variables.
! 4634: (line 278)
! 4635: * rl_completion_mark_symlink_dirs: Completion Variables.
! 4636: (line 220)
! 4637: * rl_completion_matches: Completion Functions.
! 4638: (line 45)
! 4639: * rl_completion_mode: Completion Functions.
! 4640: (line 37)
! 4641: * rl_completion_query_items: Completion Variables.
! 4642: (line 179)
! 4643: * rl_completion_quote_character: Completion Variables.
! 4644: (line 201)
! 4645: * rl_completion_suppress_append: Completion Variables.
! 4646: (line 195)
! 4647: * rl_completion_suppress_quote: Completion Variables.
! 4648: (line 207)
! 4649: * rl_completion_type: Completion Variables.
! 4650: (line 270)
! 4651: * rl_completion_word_break_hook: Completion Variables.
! 4652: (line 152)
! 4653: * rl_copy_keymap: Keymaps. (line 17)
! 4654: * rl_copy_text: Modifying Text. (line 15)
! 4655: * rl_crlf: Redisplay. (line 30)
! 4656: * rl_delete_text: Modifying Text. (line 11)
! 4657: * rl_deprep_term_function: Readline Variables. (line 176)
! 4658: * rl_deprep_terminal: Terminal Management. (line 13)
! 4659: * rl_ding: Utility Functions. (line 36)
! 4660: * rl_directory_completion_hook: Completion Variables.
! 4661: (line 64)
! 4662: * rl_directory_rewrite_hook;: Completion Variables.
! 4663: (line 82)
! 4664: * rl_discard_keymap: Keymaps. (line 26)
! 4665: * rl_dispatching: Readline Variables. (line 41)
! 4666: * rl_display_match_list: Utility Functions. (line 43)
! 4667: * rl_display_prompt: Readline Variables. (line 59)
! 4668: * rl_do_undo: Allowing Undoing. (line 48)
! 4669: * rl_done: Readline Variables. (line 28)
! 4670: * rl_echo_signal_char: Readline Signal Handling.
! 4671: (line 96)
! 4672: * rl_editing_mode: Readline Variables. (line 308)
! 4673: * rl_end: Readline Variables. (line 19)
! 4674: * rl_end_undo_group: Allowing Undoing. (line 35)
! 4675: * rl_erase_empty_line: Readline Variables. (line 47)
! 4676: * rl_event_hook: Readline Variables. (line 124)
! 4677: * rl_execute_next: Character Input. (line 26)
! 4678: * rl_executing_key: Readline Variables. (line 193)
! 4679: * rl_executing_keymap: Readline Variables. (line 182)
! 4680: * rl_executing_keyseq: Readline Variables. (line 197)
! 4681: * rl_executing_macro: Readline Variables. (line 190)
! 4682: * rl_expand_prompt: Redisplay. (line 64)
! 4683: * rl_explicit_arg: Readline Variables. (line 299)
! 4684: * rl_extend_line_buffer: Utility Functions. (line 27)
! 4685: * rl_filename_completion_desired: Completion Variables.
! 4686: (line 235)
! 4687: * rl_filename_completion_function: Completion Functions.
! 4688: (line 59)
! 4689: * rl_filename_dequoting_function: Completion Variables.
! 4690: (line 37)
! 4691: * rl_filename_quote_characters: Completion Variables.
! 4692: (line 167)
! 4693: * rl_filename_quoting_desired: Completion Variables.
! 4694: (line 245)
! 4695: * rl_filename_quoting_function: Completion Variables.
! 4696: (line 24)
! 4697: * rl_filename_rewrite_hook: Completion Variables.
! 4698: (line 110)
! 4699: * rl_filename_stat_hook: Completion Variables.
! 4700: (line 98)
! 4701: * rl_forced_update_display: Redisplay. (line 11)
! 4702: * rl_free: Utility Functions. (line 18)
! 4703: * rl_free_keymap: Keymaps. (line 30)
! 4704: * rl_free_line_state: Readline Signal Handling.
! 4705: (line 79)
! 4706: * rl_free_undo_list: Allowing Undoing. (line 45)
! 4707: * rl_function_dumper: Associating Function Names and Bindings.
! 4708: (line 30)
! 4709: * rl_function_of_keyseq: Associating Function Names and Bindings.
! 4710: (line 15)
! 4711: * rl_funmap_names: Associating Function Names and Bindings.
! 4712: (line 40)
! 4713: * rl_generic_bind: Binding Keys. (line 89)
! 4714: * rl_get_keymap: Keymaps. (line 37)
! 4715: * rl_get_keymap_by_name: Keymaps. (line 43)
! 4716: * rl_get_keymap_name: Keymaps. (line 48)
! 4717: * rl_get_screen_size: Readline Signal Handling.
! 4718: (line 115)
! 4719: * rl_get_termcap: Miscellaneous Functions.
! 4720: (line 42)
! 4721: * rl_getc: Character Input. (line 15)
! 4722: * rl_getc_function: Readline Variables. (line 130)
! 4723: * rl_gnu_readline_p: Readline Variables. (line 83)
! 4724: * rl_ignore_completion_duplicates: Completion Variables.
! 4725: (line 231)
! 4726: * rl_ignore_some_completions_function: Completion Variables.
! 4727: (line 56)
! 4728: * rl_inhibit_completion: Completion Variables.
! 4729: (line 284)
! 4730: * rl_initialize: Utility Functions. (line 31)
! 4731: * rl_input_available_hook: Readline Variables. (line 142)
! 4732: * rl_insert_completions: Completion Functions.
! 4733: (line 32)
! 4734: * rl_insert_text: Modifying Text. (line 7)
! 4735: * rl_instream: Readline Variables. (line 97)
! 4736: * rl_invoking_keyseqs: Associating Function Names and Bindings.
! 4737: (line 21)
! 4738: * rl_invoking_keyseqs_in_map: Associating Function Names and Bindings.
! 4739: (line 26)
! 4740: * rl_key_sequence_length: Readline Variables. (line 201)
! 4741: * rl_kill_text: Modifying Text. (line 19)
! 4742: * rl_last_func: Readline Variables. (line 110)
! 4743: * rl_library_version: Readline Variables. (line 73)
! 4744: * rl_line_buffer: Readline Variables. (line 9)
! 4745: * rl_list_funmap_names: Associating Function Names and Bindings.
! 4746: (line 36)
! 4747: * rl_macro_bind: Miscellaneous Functions.
! 4748: (line 8)
! 4749: * rl_macro_dumper: Miscellaneous Functions.
! 4750: (line 14)
! 4751: * rl_make_bare_keymap: Keymaps. (line 12)
! 4752: * rl_make_keymap: Keymaps. (line 20)
! 4753: * rl_mark: Readline Variables. (line 24)
! 4754: * rl_message: Redisplay. (line 39)
! 4755: * rl_modifying: Allowing Undoing. (line 57)
! 4756: * rl_named_function: Associating Function Names and Bindings.
! 4757: (line 11)
! 4758: * rl_num_chars_to_read: Readline Variables. (line 32)
! 4759: * rl_numeric_arg: Readline Variables. (line 303)
! 4760: * rl_on_new_line: Redisplay. (line 15)
! 4761: * rl_on_new_line_with_prompt: Redisplay. (line 19)
! 4762: * rl_outstream: Readline Variables. (line 101)
! 4763: * rl_parse_and_bind: Binding Keys. (line 96)
! 4764: * rl_pending_input: Readline Variables. (line 37)
! 4765: * rl_point: Readline Variables. (line 15)
! 4766: * rl_possible_completions: Completion Functions.
! 4767: (line 28)
! 4768: * rl_pre_input_hook: Readline Variables. (line 119)
! 4769: * rl_prefer_env_winsize: Readline Variables. (line 105)
! 4770: * rl_prep_term_function: Readline Variables. (line 169)
! 4771: * rl_prep_terminal: Terminal Management. (line 7)
! 4772: * rl_prompt: Readline Variables. (line 53)
! 4773: * rl_push_macro_input: Modifying Text. (line 26)
! 4774: * rl_read_init_file: Binding Keys. (line 101)
! 4775: * rl_read_key: Character Input. (line 7)
! 4776: * rl_readline_name: Readline Variables. (line 92)
! 4777: * rl_readline_state: Readline Variables. (line 204)
! 4778: * rl_readline_version: Readline Variables. (line 76)
! 4779: * rl_redisplay: Redisplay. (line 7)
! 4780: * rl_redisplay_function: Readline Variables. (line 163)
! 4781: * rl_replace_line: Utility Functions. (line 22)
! 4782: * rl_reset_after_signal: Readline Signal Handling.
! 4783: (line 87)
! 4784: * rl_reset_line_state: Redisplay. (line 26)
! 4785: * rl_reset_screen_size: Readline Signal Handling.
! 4786: (line 119)
! 4787: * rl_reset_terminal: Terminal Management. (line 28)
! 4788: * rl_resize_terminal: Readline Signal Handling.
! 4789: (line 102)
! 4790: * rl_restore_prompt: Redisplay. (line 57)
! 4791: * rl_restore_state: Utility Functions. (line 12)
! 4792: * rl_save_prompt: Redisplay. (line 53)
! 4793: * rl_save_state: Utility Functions. (line 7)
! 4794: * rl_set_key: Binding Keys. (line 73)
! 4795: * rl_set_keyboard_input_timeout: Character Input. (line 35)
! 4796: * rl_set_keymap: Keymaps. (line 40)
! 4797: * rl_set_paren_blink_timeout: Miscellaneous Functions.
! 4798: (line 37)
! 4799: * rl_set_prompt: Redisplay. (line 78)
! 4800: * rl_set_screen_size: Readline Signal Handling.
! 4801: (line 106)
! 4802: * rl_set_signals: Readline Signal Handling.
! 4803: (line 126)
! 4804: * rl_show_char: Redisplay. (line 33)
! 4805: * rl_signal_event_hook: Readline Variables. (line 138)
! 4806: * rl_sort_completion_matches: Completion Variables.
! 4807: (line 262)
! 4808: * rl_special_prefixes: Completion Variables.
! 4809: (line 172)
! 4810: * rl_startup_hook: Readline Variables. (line 115)
! 4811: * rl_stuff_char: Character Input. (line 19)
! 4812: * rl_terminal_name: Readline Variables. (line 87)
! 4813: * rl_tty_set_default_bindings: Terminal Management. (line 18)
! 4814: * rl_tty_unset_default_bindings: Terminal Management. (line 23)
! 4815: * rl_unbind_command_in_map: Binding Keys. (line 55)
! 4816: * rl_unbind_function_in_map: Binding Keys. (line 51)
! 4817: * rl_unbind_key: Binding Keys. (line 42)
! 4818: * rl_unbind_key_in_map: Binding Keys. (line 46)
! 4819: * rl_username_completion_function: Completion Functions.
! 4820: (line 66)
! 4821: * rl_variable_bind: Miscellaneous Functions.
! 4822: (line 21)
! 4823: * rl_variable_dumper: Miscellaneous Functions.
! 4824: (line 31)
! 4825: * rl_variable_value: Miscellaneous Functions.
! 4826: (line 26)
! 4827: * self-insert (a, b, A, 1, !, ...): Commands For Text. (line 33)
! 4828: * set-mark (C-@): Miscellaneous Commands.
! 4829: (line 32)
! 4830: * show-all-if-ambiguous: Readline Init File Syntax.
! 4831: (line 236)
! 4832: * show-all-if-unmodified: Readline Init File Syntax.
! 4833: (line 242)
! 4834: * show-mode-in-prompt: Readline Init File Syntax.
! 4835: (line 251)
! 4836: * skip-completed-text: Readline Init File Syntax.
! 4837: (line 256)
! 4838: * skip-csi-sequence (): Miscellaneous Commands.
! 4839: (line 51)
! 4840: * start-kbd-macro (C-x (): Keyboard Macros. (line 6)
! 4841: * transpose-chars (C-t): Commands For Text. (line 36)
! 4842: * transpose-words (M-t): Commands For Text. (line 42)
! 4843: * undo (C-_ or C-x C-u): Miscellaneous Commands.
! 4844: (line 22)
! 4845: * universal-argument (): Numeric Arguments. (line 10)
! 4846: * unix-filename-rubout (): Commands For Killing.
! 4847: (line 32)
! 4848: * unix-line-discard (C-u): Commands For Killing.
! 4849: (line 12)
! 4850: * unix-word-rubout (C-w): Commands For Killing.
! 4851: (line 28)
! 4852: * upcase-word (M-u): Commands For Text. (line 47)
! 4853: * visible-stats: Readline Init File Syntax.
! 4854: (line 269)
! 4855: * yank (C-y): Commands For Killing.
! 4856: (line 59)
! 4857: * yank-last-arg (M-. or M-_): Commands For History.
! 4858: (line 78)
! 4859: * yank-nth-arg (M-C-y): Commands For History.
! 4860: (line 69)
! 4861: * yank-pop (M-y): Commands For Killing.
! 4862: (line 62)
! 4863:
! 4864:
! 4865:
! 4866: Tag Table:
! 4867: Node: Top907
! 4868: Node: Command Line Editing1632
! 4869: Node: Introduction and Notation2284
! 4870: Node: Readline Interaction3907
! 4871: Node: Readline Bare Essentials5099
! 4872: Node: Readline Movement Commands6889
! 4873: Node: Readline Killing Commands7855
! 4874: Node: Readline Arguments9776
! 4875: Node: Searching10821
! 4876: Node: Readline Init File12973
! 4877: Node: Readline Init File Syntax14127
! 4878: Node: Conditional Init Constructs30832
! 4879: Node: Sample Init File33366
! 4880: Node: Bindable Readline Commands36485
! 4881: Node: Commands For Moving37543
! 4882: Node: Commands For History38405
! 4883: Node: Commands For Text42560
! 4884: Node: Commands For Killing45543
! 4885: Node: Numeric Arguments47686
! 4886: Node: Commands For Completion48826
! 4887: Node: Keyboard Macros50796
! 4888: Node: Miscellaneous Commands51485
! 4889: Node: Readline vi Mode55342
! 4890: Node: Programming with GNU Readline57159
! 4891: Node: Basic Behavior58145
! 4892: Node: Custom Functions61562
! 4893: Node: Readline Typedefs63046
! 4894: Node: Function Writing64686
! 4895: Node: Readline Variables65993
! 4896: Node: Readline Convenience Functions78671
! 4897: Node: Function Naming79743
! 4898: Node: Keymaps81005
! 4899: Node: Binding Keys82998
! 4900: Node: Associating Function Names and Bindings87545
! 4901: Node: Allowing Undoing89830
! 4902: Node: Redisplay92380
! 4903: Node: Modifying Text96281
! 4904: Node: Character Input97527
! 4905: Node: Terminal Management99425
! 4906: Node: Utility Functions100861
! 4907: Node: Miscellaneous Functions104189
! 4908: Node: Alternate Interface106778
! 4909: Node: A Readline Example109012
! 4910: Node: Alternate Interface Example110951
! 4911: Node: Readline Signal Handling113724
! 4912: Node: Custom Completers120246
! 4913: Node: How Completing Works120966
! 4914: Node: Completion Functions124280
! 4915: Node: Completion Variables127854
! 4916: Node: A Short Completion Example143502
! 4917: Node: GNU Free Documentation License156281
! 4918: Node: Concept Index181474
! 4919: Node: Function and Variable Index182995
! 4920:
! 4921: End Tag Table
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to readline.info 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