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