1 This is Info file readline.info, produced by Makeinfo version 1.67 from
2 the input file /usr/homes/chet/src/bash/readline-2.2/doc/rlman.texinfo.
4 INFO-DIR-SECTION Libraries
6 * Readline: (readline). The GNU readline library API
9 This document describes the GNU Readline Library, a utility which
10 aids in the consistency of user interface across discrete programs that
11 need to provide a command line interface.
13 Copyright (C) 1988, 1991 Free Software Foundation, Inc.
15 Permission is granted to make and distribute verbatim copies of this
16 manual provided the copyright notice and this permission notice pare
17 preserved on all copies.
19 Permission is granted to copy and distribute modified versions of
20 this manual under the conditions for verbatim copying, provided that
21 the entire resulting derived work is distributed under the terms of a
22 permission notice identical to this one.
24 Permission is granted to copy and distribute translations of this
25 manual into another language, under the above conditions for modified
26 versions, except that this permission notice may be stated in a
27 translation approved by the Foundation.
30 File: readline.info, Node: Top, Next: Command Line Editing, Up: (dir)
35 This document describes the GNU Readline Library, a utility which
36 aids in the consistency of user interface across discrete programs that
37 need to provide a command line interface.
41 * Command Line Editing:: GNU Readline User's Manual.
42 * Programming with GNU Readline:: GNU Readline Programmer's Manual.
43 * Concept Index:: Index of concepts described in this manual.
44 * Function and Variable Index:: Index of externally visible functions
48 File: readline.info, Node: Command Line Editing, Next: Programming with GNU Readline, Prev: Top, Up: Top
53 This chapter describes the basic features of the GNU command line
58 * Introduction and Notation:: Notation used in this text.
59 * Readline Interaction:: The minimum set of commands for editing a line.
60 * Readline Init File:: Customizing Readline from a user's view.
61 * Bindable Readline Commands:: A description of most of the Readline commands
63 * Readline vi Mode:: A short description of how to make Readline
64 behave like the vi editor.
67 File: readline.info, Node: Introduction and Notation, Next: Readline Interaction, Up: Command Line Editing
69 Introduction to Line Editing
70 ============================
72 The following paragraphs describe the notation used to represent
75 The text <C-k> is read as `Control-K' and describes the character
76 produced when the <k> key is pressed while the Control key is depressed.
78 The text <M-k> is read as `Meta-K' and describes the character
79 produced when the meta key (if you have one) is depressed, and the <k>
80 key is pressed. If you do not have a meta key, the identical keystroke
81 can be generated by typing <ESC> first, and then typing <k>. Either
82 process is known as "metafying" the <k> key.
84 The text <M-C-k> is read as `Meta-Control-k' and describes the
85 character produced by "metafying" <C-k>.
87 In addition, several keys have their own names. Specifically,
88 <DEL>, <ESC>, <LFD>, <SPC>, <RET>, and <TAB> all stand for themselves
89 when seen in this text, or in an init file (*note Readline Init
93 File: readline.info, Node: Readline Interaction, Next: Readline Init File, Prev: Introduction and Notation, Up: Command Line Editing
98 Often during an interactive session you type in a long line of text,
99 only to notice that the first word on the line is misspelled. The
100 Readline library gives you a set of commands for manipulating the text
101 as you type it in, allowing you to just fix your typo, and not forcing
102 you to retype the majority of the line. Using these editing commands,
103 you move the cursor to the place that needs correction, and delete or
104 insert the text of the corrections. Then, when you are satisfied with
105 the line, you simply press <RETURN>. You do not have to be at the end
106 of the line to press <RETURN>; the entire line is accepted regardless
107 of the location of the cursor within the line.
111 * Readline Bare Essentials:: The least you need to know about Readline.
112 * Readline Movement Commands:: Moving about the input line.
113 * Readline Killing Commands:: How to delete text, and how to get it back!
114 * Readline Arguments:: Giving numeric arguments to commands.
115 * Searching:: Searching through previous lines.
118 File: readline.info, Node: Readline Bare Essentials, Next: Readline Movement Commands, Up: Readline Interaction
120 Readline Bare Essentials
121 ------------------------
123 In order to enter characters into the line, simply type them. The
124 typed character appears where the cursor was, and then the cursor moves
125 one space to the right. If you mistype a character, you can use your
126 erase character to back up and delete the mistyped character.
128 Sometimes you may miss typing a character that you wanted to type,
129 and not notice your error until you have typed several other
130 characters. In that case, you can type <C-b> to move the cursor to the
131 left, and then correct your mistake. Afterwards, you can move the
132 cursor to the right with <C-f>.
134 When you add text in the middle of a line, you will notice that
135 characters to the right of the cursor are `pushed over' to make room
136 for the text that you have inserted. Likewise, when you delete text
137 behind the cursor, characters to the right of the cursor are `pulled
138 back' to fill in the blank space created by the removal of the text. A
139 list of the basic bare essentials for editing the text of an input line
143 Move back one character.
146 Move forward one character.
149 Delete the character to the left of the cursor.
152 Delete the character underneath the cursor.
155 Insert the character into the line at the cursor.
158 Undo the last editing command. You can undo all the way back to an
162 File: readline.info, Node: Readline Movement Commands, Next: Readline Killing Commands, Prev: Readline Bare Essentials, Up: Readline Interaction
164 Readline Movement Commands
165 --------------------------
167 The above table describes the most basic possible keystrokes that
168 you need in order to do editing of the input line. For your
169 convenience, many other commands have been added in addition to <C-b>,
170 <C-f>, <C-d>, and <DEL>. Here are some commands for moving more rapidly
174 Move to the start of the line.
177 Move to the end of the line.
180 Move forward a word, where a word is composed of letters and
184 Move backward a word.
187 Clear the screen, reprinting the current line at the top.
189 Notice how <C-f> moves forward a character, while <M-f> moves
190 forward a word. It is a loose convention that control keystrokes
191 operate on characters while meta keystrokes operate on words.
194 File: readline.info, Node: Readline Killing Commands, Next: Readline Arguments, Prev: Readline Movement Commands, Up: Readline Interaction
196 Readline Killing Commands
197 -------------------------
199 "Killing" text means to delete the text from the line, but to save
200 it away for later use, usually by "yanking" (re-inserting) it back into
201 the line. If the description for a command says that it `kills' text,
202 then you can be sure that you can get the text back in a different (or
203 the same) place later.
205 When you use a kill command, the text is saved in a "kill-ring".
206 Any number of consecutive kills save all of the killed text together, so
207 that when you yank it back, you get it all. The kill ring is not line
208 specific; the text that you killed on a previously typed line is
209 available to be yanked back later, when you are typing another line.
211 Here is the list of commands for killing text.
214 Kill the text from the current cursor position to the end of the
218 Kill from the cursor to the end of the current word, or if between
219 words, to the end of the next word.
222 Kill from the cursor the start of the previous word, or if between
223 words, to the start of the previous word.
226 Kill from the cursor to the previous whitespace. This is
227 different than <M-DEL> because the word boundaries differ.
229 Here is how to "yank" the text back into the line. Yanking means to
230 copy the most-recently-killed text from the kill buffer.
233 Yank the most recently killed text back into the buffer at the
237 Rotate the kill-ring, and yank the new top. You can only do this
238 if the prior command is <C-y> or <M-y>.
241 File: readline.info, Node: Readline Arguments, Next: Searching, Prev: Readline Killing Commands, Up: Readline Interaction
246 You can pass numeric arguments to Readline commands. Sometimes the
247 argument acts as a repeat count, other times it is the sign of the
248 argument that is significant. If you pass a negative argument to a
249 command which normally acts in a forward direction, that command will
250 act in a backward direction. For example, to kill text back to the
251 start of the line, you might type `M-- C-k'.
253 The general way to pass numeric arguments to a command is to type
254 meta digits before the command. If the first `digit' typed is a minus
255 sign (<->), then the sign of the argument will be negative. Once you
256 have typed one meta digit to get the argument started, you can type the
257 remainder of the digits, and then the command. For example, to give
258 the <C-d> command an argument of 10, you could type `M-1 0 C-d'.
261 File: readline.info, Node: Searching, Prev: Readline Arguments, Up: Readline Interaction
263 Searching for Commands in the History
264 -------------------------------------
266 Readline provides commands for searching through the command history
267 for lines containing a specified string. There are two search modes:
268 INCREMENTAL and NON-INCREMENTAL.
270 Incremental searches begin before the user has finished typing the
271 search string. As each character of the search string is typed,
272 Readline displays the next entry from the history matching the string
273 typed so far. An incremental search requires only as many characters
274 as needed to find the desired history entry. The <ESC> character is
275 used to terminate an incremental search. <C-j> will also terminate the
276 search. <C-g> will abort an incremental search and restore the
277 original line. When the search is terminated, the history entry
278 containing the search string becomes the current line. To find other
279 matching entries in the history list, type <C-s> or <C-r> as
280 appropriate. This will search backward or forward in the history for
281 the next entry matching the search string typed so far. Any other key
282 sequence bound to a Readline command will terminate the search and
283 execute that command. For instance, a <RET> will terminate the search
284 and accept the line, thereby executing the command from the history
287 Non-incremental searches read the entire search string before
288 starting to search for matching history lines. The search string may be
289 typed by the user or be part of the contents of the current line.
292 File: readline.info, Node: Readline Init File, Next: Bindable Readline Commands, Prev: Readline Interaction, Up: Command Line Editing
297 Although the Readline library comes with a set of `emacs'-like
298 keybindings installed by default, it is possible to use a different set
299 of keybindings. Any user can customize programs that use Readline by
300 putting commands in an "inputrc" file in his home directory. The name
301 of this file is taken from the value of the environment variable
302 `INPUTRC'. If that variable is unset, the default is `~/.inputrc'.
304 When a program which uses the Readline library starts up, the init
305 file is read, and the key bindings are set.
307 In addition, the `C-x C-r' command re-reads this init file, thus
308 incorporating any changes that you might have made to it.
312 * Readline Init File Syntax:: Syntax for the commands in the inputrc file.
314 * Conditional Init Constructs:: Conditional key bindings in the inputrc file.
316 * Sample Init File:: An example inputrc file.
319 File: readline.info, Node: Readline Init File Syntax, Next: Conditional Init Constructs, Up: Readline Init File
321 Readline Init File Syntax
322 -------------------------
324 There are only a few basic constructs allowed in the Readline init
325 file. Blank lines are ignored. Lines beginning with a `#' are
326 comments. Lines beginning with a `$' indicate conditional constructs
327 (*note Conditional Init Constructs::.). Other lines denote variable
328 settings and key bindings.
331 You can modify the run-time behavior of Readline by altering the
332 values of variables in Readline using the `set' command within the
333 init file. Here is how to change from the default Emacs-like key
334 binding to use `vi' line editing commands:
338 A great deal of run-time behavior is changeable with the following
342 Controls what happens when Readline wants to ring the
343 terminal bell. If set to `none', Readline never rings the
344 bell. If set to `visible', Readline uses a visible bell if
345 one is available. If set to `audible' (the default),
346 Readline attempts to ring the terminal's bell.
349 The string to insert at the beginning of the line when the
350 `insert-comment' command is executed. The default value is
353 `completion-ignore-case'
354 If set to `on', Readline performs filename matching and
355 completion in a case-insensitive fashion. The default value
358 `completion-query-items'
359 The number of possible completions that determines when the
360 user is asked whether he wants to see the list of
361 possibilities. If the number of possible completions is
362 greater than this value, Readline will ask the user whether
363 or not he wishes to view them; otherwise, they are simply
364 listed. The default limit is `100'.
367 If set to `on', Readline will convert characters with the
368 eighth bit set to an ASCII key sequence by stripping the
369 eighth bit and prepending an <ESC> character, converting them
370 to a meta-prefixed key sequence. The default value is `on'.
373 If set to `On', Readline will inhibit word completion.
374 Completion characters will be inserted into the line as if
375 they had been mapped to `self-insert'. The default is `off'.
378 The `editing-mode' variable controls which default set of key
379 bindings is used. By default, Readline starts up in Emacs
380 editing mode, where the keystrokes are most similar to Emacs.
381 This variable can be set to either `emacs' or `vi'.
384 When set to `on', Readline will try to enable the application
385 keypad when it is called. Some systems need this to enable
386 the arrow keys. The default is `off'.
389 If set to `on', tilde expansion is performed when Readline
390 attempts word completion. The default is `off'.
392 `horizontal-scroll-mode'
393 This variable can be set to either `on' or `off'. Setting it
394 to `on' means that the text of the lines being edited will
395 scroll horizontally on a single screen line when they are
396 longer than the width of the screen, instead of wrapping onto
397 a new screen line. By default, this variable is set to `off'.
400 Sets Readline's idea of the current keymap for key binding
401 commands. Acceptable `keymap' names are `emacs',
402 `emacs-standard', `emacs-meta', `emacs-ctlx', `vi',
403 `vi-command', and `vi-insert'. `vi' is equivalent to
404 `vi-command'; `emacs' is equivalent to `emacs-standard'. The
405 default value is `emacs'. The value of the `editing-mode'
406 variable also affects the default keymap.
409 If set to `on', completed directory names have a slash
410 appended. The default is `on'.
412 `mark-modified-lines'
413 This variable, when set to `on', causes Readline to display an
414 asterisk (`*') at the start of history lines which have been
415 modified. This variable is `off' by default.
418 If set to `on', Readline will enable eight-bit input (it will
419 not strip the eighth bit from the characters it reads),
420 regardless of what the terminal claims it can support. The
421 default value is `off'. The name `meta-flag' is a synonym
425 If set to `on', Readline will display characters with the
426 eighth bit set directly rather than as a meta-prefixed escape
427 sequence. The default is `off'.
429 `print-completions-horizontally'
430 If set to `on', Readline will display completions with matches
431 sorted horizontally in alphabetical order, rather than down
432 the screen. The default is `off'.
434 `show-all-if-ambiguous'
435 This alters the default behavior of the completion functions.
436 If set to `on', words which have more than one possible
437 completion cause the matches to be listed immediately instead
438 of ringing the bell. The default value is `off'.
441 If set to `on', a character denoting a file's type is
442 appended to the filename when listing possible completions.
443 The default is `off'.
446 The syntax for controlling key bindings in the init file is
447 simple. First you have to know the name of the command that you
448 want to change. The following sections contain tables of the
449 command name, the default keybinding, if any, and a short
450 description of what the command does.
452 Once you know the name of the command, simply place the name of
453 the key you wish to bind the command to, a colon, and then the
454 name of the command on a line in the init file. The name of the
455 key can be expressed in different ways, depending on which is most
458 KEYNAME: FUNCTION-NAME or MACRO
459 KEYNAME is the name of a key spelled out in English. For
461 Control-u: universal-argument
462 Meta-Rubout: backward-kill-word
463 Control-o: "> output"
465 In the above example, <C-u> is bound to the function
466 `universal-argument', and <C-o> is bound to run the macro
467 expressed on the right hand side (that is, to insert the text
468 `> output' into the line).
470 "KEYSEQ": FUNCTION-NAME or MACRO
471 KEYSEQ differs from KEYNAME above in that strings denoting an
472 entire key sequence can be specified, by placing the key
473 sequence in double quotes. Some GNU Emacs style key escapes
474 can be used, as in the following example, but the special
475 character names are not recognized.
477 "\C-u": universal-argument
478 "\C-x\C-r": re-read-init-file
479 "\e[11~": "Function Key 1"
481 In the above example, <C-u> is bound to the function
482 `universal-argument' (just as it was in the first example),
483 `<C-x> <C-r>' is bound to the function `re-read-init-file',
484 and `<ESC> <[> <1> <1> <~>' is bound to insert the text
487 The following GNU Emacs style escape sequences are available when
488 specifying key sequences:
508 In addition to the GNU Emacs style escape sequences, a second set
509 of backslash escapes is available:
536 the character whose ASCII code is the octal value NNN (one to
540 the character whose ASCII code is the hexadecimal value NNN
541 (one to three digits)
543 When entering the text of a macro, single or double quotes must be
544 used to indicate a macro definition. Unquoted text is assumed to
545 be a function name. In the macro body, the backslash escapes
546 described above are expanded. Backslash will quote any other
547 character in the macro text, including `"' and `''. For example,
548 the following binding will make `C-x \' insert a single `\' into
553 File: readline.info, Node: Conditional Init Constructs, Next: Sample Init File, Prev: Readline Init File Syntax, Up: Readline Init File
555 Conditional Init Constructs
556 ---------------------------
558 Readline implements a facility similar in spirit to the conditional
559 compilation features of the C preprocessor which allows key bindings
560 and variable settings to be performed as the result of tests. There
561 are four parser directives used.
564 The `$if' construct allows bindings to be made based on the
565 editing mode, the terminal being used, or the application using
566 Readline. The text of the test extends to the end of the line; no
567 characters are required to isolate it.
570 The `mode=' form of the `$if' directive is used to test
571 whether Readline is in `emacs' or `vi' mode. This may be
572 used in conjunction with the `set keymap' command, for
573 instance, to set bindings in the `emacs-standard' and
574 `emacs-ctlx' keymaps only if Readline is starting out in
578 The `term=' form may be used to include terminal-specific key
579 bindings, perhaps to bind the key sequences output by the
580 terminal's function keys. The word on the right side of the
581 `=' is tested against both the full name of the terminal and
582 the portion of the terminal name before the first `-'. This
583 allows `sun' to match both `sun' and `sun-cmd', for instance.
586 The APPLICATION construct is used to include
587 application-specific settings. Each program using the
588 Readline library sets the APPLICATION NAME, and you can test
589 for it. This could be used to bind key sequences to
590 functions useful for a specific program. For instance, the
591 following command adds a key sequence that quotes the current
592 or previous word in Bash:
594 # Quote the current or previous word
595 "\C-xq": "\eb\"\ef\""
599 This command, as seen in the previous example, terminates an `$if'
603 Commands in this branch of the `$if' directive are executed if the
607 This directive takes a single filename as an argument and reads
608 commands and bindings from that file.
609 $include /etc/inputrc
612 File: readline.info, Node: Sample Init File, Prev: Conditional Init Constructs, Up: Readline Init File
617 Here is an example of an inputrc file. This illustrates key
618 binding, variable assignment, and conditional syntax.
621 # This file controls the behaviour of line input editing for
622 # programs that use the Gnu Readline library. Existing programs
623 # include FTP, Bash, and Gdb.
625 # You can re-read the inputrc file with C-x C-r.
626 # Lines beginning with '#' are comments.
628 # First, include any systemwide bindings and variable assignments from
630 $include /etc/Inputrc
633 # Set various bindings for emacs mode.
635 set editing-mode emacs
639 Meta-Control-h: backward-kill-word Text after the function name is ignored
642 # Arrow keys in keypad mode
644 #"\M-OD": backward-char
645 #"\M-OC": forward-char
646 #"\M-OA": previous-history
647 #"\M-OB": next-history
649 # Arrow keys in ANSI mode
651 "\M-[D": backward-char
652 "\M-[C": forward-char
653 "\M-[A": previous-history
654 "\M-[B": next-history
656 # Arrow keys in 8 bit keypad mode
658 #"\M-\C-OD": backward-char
659 #"\M-\C-OC": forward-char
660 #"\M-\C-OA": previous-history
661 #"\M-\C-OB": next-history
663 # Arrow keys in 8 bit ANSI mode
665 #"\M-\C-[D": backward-char
666 #"\M-\C-[C": forward-char
667 #"\M-\C-[A": previous-history
668 #"\M-\C-[B": next-history
674 # An old-style binding. This happens to be the default.
677 # Macros that are convenient for shell interaction
680 "\C-xp": "PATH=${PATH}\e\C-e\C-a\ef\C-f"
681 # prepare to type a quoted word -- insert open and close double quotes
682 # and move to just after the open quote
684 # insert a backslash (testing backslash escapes in sequences and macros)
686 # Quote the current or previous word
687 "\C-xq": "\eb\"\ef\""
688 # Add a binding to refresh the line, which is unbound
689 "\C-xr": redraw-current-line
690 # Edit variable on current line.
691 "\M-\C-v": "\C-a\C-k$\C-y\M-\C-e\C-a\C-y="
694 # use a visible bell if one is available
695 set bell-style visible
697 # don't strip characters to 7 bits when reading
700 # allow iso-latin1 characters to be inserted rather than converted to
701 # prefix-meta sequences
704 # display characters with the eighth bit set directly rather than
705 # as meta-prefixed characters
708 # if there are more than 150 possible completions for a word, ask the
709 # user if he wants to see all of them
710 set completion-query-items 150
716 "\M-.": yank-last-arg
720 File: readline.info, Node: Bindable Readline Commands, Next: Readline vi Mode, Prev: Readline Init File, Up: Command Line Editing
722 Bindable Readline Commands
723 ==========================
727 * Commands For Moving:: Moving about the line.
728 * Commands For History:: Getting at previous lines.
729 * Commands For Text:: Commands for changing text.
730 * Commands For Killing:: Commands for killing and yanking.
731 * Numeric Arguments:: Specifying numeric arguments, repeat counts.
732 * Commands For Completion:: Getting Readline to do the typing for you.
733 * Keyboard Macros:: Saving and re-executing typed characters
734 * Miscellaneous Commands:: Other miscellaneous commands.
736 This section describes Readline commands that may be bound to key
740 File: readline.info, Node: Commands For Moving, Next: Commands For History, Up: Bindable Readline Commands
745 `beginning-of-line (C-a)'
746 Move to the start of the current line.
749 Move to the end of the line.
752 Move forward a character.
754 `backward-char (C-b)'
755 Move back a character.
758 Move forward to the end of the next word. Words are composed of
761 `backward-word (M-b)'
762 Move back to the start of this, or the previous, word. Words are
763 composed of letters and digits.
766 Clear the screen and redraw the current line, leaving the current
767 line at the top of the screen.
769 `redraw-current-line ()'
770 Refresh the current line. By default, this is unbound.
773 File: readline.info, Node: Commands For History, Next: Commands For Text, Prev: Commands For Moving, Up: Bindable Readline Commands
775 Commands For Manipulating The History
776 -------------------------------------
778 `accept-line (Newline, Return)'
779 Accept the line regardless of where the cursor is. If this line is
780 non-empty, add it to the history list. If this line was a history
781 line, then restore the history line to its original state.
783 `previous-history (C-p)'
784 Move `up' through the history list.
787 Move `down' through the history list.
789 `beginning-of-history (M-<)'
790 Move to the first line in the history.
792 `end-of-history (M->)'
793 Move to the end of the input history, i.e., the line currently
796 `reverse-search-history (C-r)'
797 Search backward starting at the current line and moving `up'
798 through the history as necessary. This is an incremental search.
800 `forward-search-history (C-s)'
801 Search forward starting at the current line and moving `down'
802 through the the history as necessary. This is an incremental
805 `non-incremental-reverse-search-history (M-p)'
806 Search backward starting at the current line and moving `up'
807 through the history as necessary using a non-incremental search
808 for a string supplied by the user.
810 `non-incremental-forward-search-history (M-n)'
811 Search forward starting at the current line and moving `down'
812 through the the history as necessary using a non-incremental search
813 for a string supplied by the user.
815 `history-search-forward ()'
816 Search forward through the history for the string of characters
817 between the start of the current line and the current cursor
818 position (the POINT). This is a non-incremental search. By
819 default, this command is unbound.
821 `history-search-backward ()'
822 Search backward through the history for the string of characters
823 between the start of the current line and the point. This is a
824 non-incremental search. By default, this command is unbound.
826 `yank-nth-arg (M-C-y)'
827 Insert the first argument to the previous command (usually the
828 second word on the previous line). With an argument N, insert the
829 Nth word from the previous command (the words in the previous
830 command begin with word 0). A negative argument inserts the Nth
831 word from the end of the previous command.
833 `yank-last-arg (M-., M-_)'
834 Insert last argument to the previous command (the last word of the
835 previous history entry). With an argument, behave exactly like
836 `yank-nth-arg'. Successive calls to `yank-last-arg' move back
837 through the history list, inserting the last argument of each line
841 File: readline.info, Node: Commands For Text, Next: Commands For Killing, Prev: Commands For History, Up: Bindable Readline Commands
843 Commands For Changing Text
844 --------------------------
847 Delete the character under the cursor. If the cursor is at the
848 beginning of the line, there are no characters in the line, and
849 the last character typed was not bound to `delete-char', then
852 `backward-delete-char (Rubout)'
853 Delete the character behind the cursor. A numeric argument means
854 to kill the characters instead of deleting them.
856 `quoted-insert (C-q, C-v)'
857 Add the next character typed to the line verbatim. This is how to
858 insert key sequences like <C-q>, for example.
861 Insert a tab character.
863 `self-insert (a, b, A, 1, !, ...)'
866 `transpose-chars (C-t)'
867 Drag the character before the cursor forward over the character at
868 the cursor, moving the cursor forward as well. If the insertion
869 point is at the end of the line, then this transposes the last two
870 characters of the line. Negative arguments don't work.
872 `transpose-words (M-t)'
873 Drag the word behind the cursor past the word in front of the
874 cursor moving the cursor over that word as well.
877 Uppercase the current (or following) word. With a negative
878 argument, uppercase the previous word, but do not move the cursor.
880 `downcase-word (M-l)'
881 Lowercase the current (or following) word. With a negative
882 argument, lowercase the previous word, but do not move the cursor.
884 `capitalize-word (M-c)'
885 Capitalize the current (or following) word. With a negative
886 argument, capitalize the previous word, but do not move the cursor.
889 File: readline.info, Node: Commands For Killing, Next: Numeric Arguments, Prev: Commands For Text, Up: Bindable Readline Commands
895 Kill the text from the current cursor position to the end of the
898 `backward-kill-line (C-x Rubout)'
899 Kill backward to the beginning of the line.
901 `unix-line-discard (C-u)'
902 Kill backward from the cursor to the beginning of the current line.
903 The killed text is saved on the kill-ring.
906 Kill all characters on the current line, no matter where the
907 cursor is. By default, this is unbound.
910 Kill from the cursor to the end of the current word, or if between
911 words, to the end of the next word. Word boundaries are the same
914 `backward-kill-word (M-DEL)'
915 Kill the word behind the cursor. Word boundaries are the same as
918 `unix-word-rubout (C-w)'
919 Kill the word behind the cursor, using white space as a word
920 boundary. The killed text is saved on the kill-ring.
922 `delete-horizontal-space ()'
923 Delete all spaces and tabs around point. By default, this is
927 Kill the text between the point and the *mark* (saved cursor
928 position). This text is referred to as the REGION. By default,
929 this command is unbound.
931 `copy-region-as-kill ()'
932 Copy the text in the region to the kill buffer, so it can be yanked
933 right away. By default, this command is unbound.
935 `copy-backward-word ()'
936 Copy the word before point to the kill buffer. The word
937 boundaries are the same as `backward-word'. By default, this
940 `copy-forward-word ()'
941 Copy the word following point to the kill buffer. The word
942 boundaries are the same as `forward-word'. By default, this
946 Yank the top of the kill ring into the buffer at the current
950 Rotate the kill-ring, and yank the new top. You can only do this
951 if the prior command is yank or yank-pop.
954 File: readline.info, Node: Numeric Arguments, Next: Commands For Completion, Prev: Commands For Killing, Up: Bindable Readline Commands
956 Specifying Numeric Arguments
957 ----------------------------
959 `digit-argument (M-0, M-1, ... M--)'
960 Add this digit to the argument already accumulating, or start a new
961 argument. <M-> starts a negative argument.
963 `universal-argument ()'
964 This is another way to specify an argument. If this command is
965 followed by one or more digits, optionally with a leading minus
966 sign, those digits define the argument. If the command is
967 followed by digits, executing `universal-argument' again ends the
968 numeric argument, but is otherwise ignored. As a special case, if
969 this command is immediately followed by a character that is
970 neither a digit or minus sign, the argument count for the next
971 command is multiplied by four. The argument count is initially
972 one, so executing this function the first time makes the argument
973 count four, a second time makes the argument count sixteen, and so
974 on. By default, this is not bound to a key.
977 File: readline.info, Node: Commands For Completion, Next: Keyboard Macros, Prev: Numeric Arguments, Up: Bindable Readline Commands
979 Letting Readline Type For You
980 -----------------------------
983 Attempt to do completion on the text before the cursor. This is
984 application-specific. Generally, if you are typing a filename
985 argument, you can do filename completion; if you are typing a
986 command, you can do command completion; if you are typing in a
987 symbol to GDB, you can do symbol name completion; if you are
988 typing in a variable to Bash, you can do variable name completion,
991 `possible-completions (M-?)'
992 List the possible completions of the text before the cursor.
994 `insert-completions (M-*)'
995 Insert all completions of the text before point that would have
996 been generated by `possible-completions'.
999 Similar to `complete', but replaces the word to be completed with
1000 a single match from the list of possible completions. Repeated
1001 execution of `menu-complete' steps through the list of possible
1002 completions, inserting each match in turn. At the end of the list
1003 of completions, the bell is rung and the original text is restored.
1004 An argument of N moves N positions forward in the list of matches;
1005 a negative argument may be used to move backward through the list.
1006 This command is intended to be bound to `TAB', but is unbound by
1010 File: readline.info, Node: Keyboard Macros, Next: Miscellaneous Commands, Prev: Commands For Completion, Up: Bindable Readline Commands
1015 `start-kbd-macro (C-x ()'
1016 Begin saving the characters typed into the current keyboard macro.
1018 `end-kbd-macro (C-x ))'
1019 Stop saving the characters typed into the current keyboard macro
1020 and save the definition.
1022 `call-last-kbd-macro (C-x e)'
1023 Re-execute the last keyboard macro defined, by making the
1024 characters in the macro appear as if typed at the keyboard.
1027 File: readline.info, Node: Miscellaneous Commands, Prev: Keyboard Macros, Up: Bindable Readline Commands
1029 Some Miscellaneous Commands
1030 ---------------------------
1032 `re-read-init-file (C-x C-r)'
1033 Read in the contents of the inputrc file, and incorporate any
1034 bindings or variable assignments found there.
1037 Abort the current editing command and ring the terminal's bell
1038 (subject to the setting of `bell-style').
1040 `do-uppercase-version (M-a, M-b, M-X, ...)'
1041 If the metafied character X is lowercase, run the command that is
1042 bound to the corresponding uppercase character.
1045 Make the next character typed be metafied. This is for keyboards
1046 without a meta key. Typing `ESC f' is equivalent to typing `M-f'.
1048 `undo (C-_, C-x C-u)'
1049 Incremental undo, separately remembered for each line.
1052 Undo all changes made to this line. This is like executing the
1053 `undo' command enough times to get back to the beginning.
1055 `tilde-expand (M-~)'
1056 Perform tilde expansion on the current word.
1059 Set the mark to the current point. If a numeric argument is
1060 supplied, the mark is set to that position.
1062 `exchange-point-and-mark (C-x C-x)'
1063 Swap the point with the mark. The current cursor position is set
1064 to the saved position, and the old cursor position is saved as the
1067 `character-search (C-])'
1068 A character is read and point is moved to the next occurrence of
1069 that character. A negative count searches for previous
1072 `character-search-backward (M-C-])'
1073 A character is read and point is moved to the previous occurrence
1074 of that character. A negative count searches for subsequent
1077 `insert-comment (M-#)'
1078 The value of the `comment-begin' variable is inserted at the
1079 beginning of the current line, and the line is accepted as if a
1080 newline had been typed.
1083 Print all of the functions and their key bindings to the Readline
1084 output stream. If a numeric argument is supplied, the output is
1085 formatted in such a way that it can be made part of an INPUTRC
1086 file. This command is unbound by default.
1089 Print all of the settable variables and their values to the
1090 Readline output stream. If a numeric argument is supplied, the
1091 output is formatted in such a way that it can be made part of an
1092 INPUTRC file. This command is unbound by default.
1095 Print all of the Readline key sequences bound to macros and the
1096 strings they ouput. If a numeric argument is supplied, the output
1097 is formatted in such a way that it can be made part of an INPUTRC
1098 file. This command is unbound by default.
1101 File: readline.info, Node: Readline vi Mode, Prev: Bindable Readline Commands, Up: Command Line Editing
1106 While the Readline library does not have a full set of `vi' editing
1107 functions, it does contain enough to allow simple editing of the line.
1108 The Readline `vi' mode behaves as specified in the POSIX 1003.2
1111 In order to switch interactively between `emacs' and `vi' editing
1112 modes, use the command M-C-j (toggle-editing-mode). The Readline
1113 default is `emacs' mode.
1115 When you enter a line in `vi' mode, you are already placed in
1116 `insertion' mode, as if you had typed an `i'. Pressing <ESC> switches
1117 you into `command' mode, where you can edit the text of the line with
1118 the standard `vi' movement keys, move to previous history lines with
1119 `k' and subsequent lines with `j', and so forth.
1121 This document describes the GNU Readline Library, a utility for
1122 aiding in the consitency of user interface across discrete programs
1123 that need to provide a command line interface.
1125 Copyright (C) 1988, 1994, 1996 Free Software Foundation, Inc.
1127 Permission is granted to make and distribute verbatim copies of this
1128 manual provided the copyright notice and this permission notice pare
1129 preserved on all copies.
1131 Permission is granted to copy and distribute modified versions of
1132 this manual under the conditions for verbatim copying, provided that
1133 the entire resulting derived work is distributed under the terms of a
1134 permission notice identical to this one.
1136 Permission is granted to copy and distribute translations of this
1137 manual into another language, under the above conditions for modified
1138 versions, except that this permission notice may be stated in a
1139 translation approved by the Foundation.
1142 File: readline.info, Node: Programming with GNU Readline, Next: Concept Index, Prev: Command Line Editing, Up: Top
1144 Programming with GNU Readline
1145 *****************************
1147 This chapter describes the interface between the GNU Readline
1148 Library and other programs. If you are a programmer, and you wish to
1149 include the features found in GNU Readline such as completion, line
1150 editing, and interactive history manipulation in your own programs,
1151 this section is for you.
1155 * Basic Behavior:: Using the default behavior of Readline.
1156 * Custom Functions:: Adding your own functions to Readline.
1157 * Readline Variables:: Variables accessible to custom
1159 * Readline Convenience Functions:: Functions which Readline supplies to
1160 aid in writing your own
1161 * Custom Completers:: Supplanting or supplementing Readline's
1162 completion functions.
1165 File: readline.info, Node: Basic Behavior, Next: Custom Functions, Up: Programming with GNU Readline
1170 Many programs provide a command line interface, such as `mail',
1171 `ftp', and `sh'. For such programs, the default behaviour of Readline
1172 is sufficient. This section describes how to use Readline in the
1173 simplest way possible, perhaps to replace calls in your code to
1174 `gets()' or `fgets ()'.
1176 The function `readline ()' prints a prompt and then reads and returns
1177 a single line of text from the user. The line `readline' returns is
1178 allocated with `malloc ()'; you should `free ()' the line when you are
1179 done with it. The declaration for `readline' in ANSI C is
1181 `char *readline (char *PROMPT);'
1184 `char *line = readline ("Enter a line: ");'
1186 in order to read a line of text from the user. The line returned has
1187 the final newline removed, so only the text remains.
1189 If `readline' encounters an `EOF' while reading the line, and the
1190 line is empty at that point, then `(char *)NULL' is returned.
1191 Otherwise, the line is ended just as if a newline had been typed.
1193 If you want the user to be able to get at the line later, (with
1194 <C-p> for example), you must call `add_history ()' to save the line
1195 away in a "history" list of such lines.
1197 `add_history (line)';
1199 For full details on the GNU History Library, see the associated manual.
1201 It is preferable to avoid saving empty lines on the history list,
1202 since users rarely have a burning need to reuse a blank line. Here is
1203 a function which usefully replaces the standard `gets ()' library
1204 function, and has the advantage of no static buffer to overflow:
1206 /* A static variable for holding the line. */
1207 static char *line_read = (char *)NULL;
1209 /* Read a string, and return a pointer to it. Returns NULL on EOF. */
1213 /* If the buffer has already been allocated, return the memory
1214 to the free pool. */
1218 line_read = (char *)NULL;
1221 /* Get a line from the user. */
1222 line_read = readline ("");
1224 /* If the line has any text in it, save it on the history. */
1225 if (line_read && *line_read)
1226 add_history (line_read);
1231 This function gives the user the default behaviour of <TAB>
1232 completion: completion on file names. If you do not want Readline to
1233 complete on filenames, you can change the binding of the <TAB> key with
1236 `int rl_bind_key (int KEY, int (*FUNCTION)());'
1238 `rl_bind_key ()' takes two arguments: KEY is the character that you
1239 want to bind, and FUNCTION is the address of the function to call when
1240 KEY is pressed. Binding <TAB> to `rl_insert ()' makes <TAB> insert
1241 itself. `rl_bind_key ()' returns non-zero if KEY is not a valid ASCII
1242 character code (between 0 and 255).
1244 Thus, to disable the default <TAB> behavior, the following suffices:
1245 `rl_bind_key ('\t', rl_insert);'
1247 This code should be executed once at the start of your program; you
1248 might write a function called `initialize_readline ()' which performs
1249 this and other desired initializations, such as installing custom
1250 completers (*note Custom Completers::.).
1253 File: readline.info, Node: Custom Functions, Next: Readline Variables, Prev: Basic Behavior, Up: Programming with GNU Readline
1258 Readline provides many functions for manipulating the text of the
1259 line, but it isn't possible to anticipate the needs of all programs.
1260 This section describes the various functions and variables defined
1261 within the Readline library which allow a user program to add
1262 customized functionality to Readline.
1266 * The Function Type:: C declarations to make code readable.
1267 * Function Writing:: Variables and calling conventions.
1270 File: readline.info, Node: The Function Type, Next: Function Writing, Up: Custom Functions
1275 For readabilty, we declare a new type of object, called "Function".
1276 A `Function' is a C function which returns an `int'. The type
1277 declaration for `Function' is:
1279 `typedef int Function ();'
1281 The reason for declaring this new type is to make it easier to write
1282 code describing pointers to C functions. Let us say we had a variable
1283 called FUNC which was a pointer to a function. Instead of the classic
1292 Similarly, there are
1294 typedef void VFunction ();
1295 typedef char *CPFunction (); and
1296 typedef char **CPPFunction ();
1298 for functions returning no value, `pointer to char', and `pointer to
1299 pointer to char', respectively.
1302 File: readline.info, Node: Function Writing, Prev: The Function Type, Up: Custom Functions
1304 Writing a New Function
1305 ----------------------
1307 In order to write new functions for Readline, you need to know the
1308 calling conventions for keyboard-invoked functions, and the names of the
1309 variables that describe the current state of the line read so far.
1311 The calling sequence for a command `foo' looks like
1313 `foo (int count, int key)'
1315 where COUNT is the numeric argument (or 1 if defaulted) and KEY is the
1316 key that invoked this function.
1318 It is completely up to the function as to what should be done with
1319 the numeric argument. Some functions use it as a repeat count, some as
1320 a flag, and others to choose alternate behavior (refreshing the current
1321 line as opposed to refreshing the screen, for example). Some choose to
1322 ignore it. In general, if a function uses the numeric argument as a
1323 repeat count, it should be able to do something useful with both
1324 negative and positive arguments. At the very least, it should be aware
1325 that it can be passed a negative argument.
1328 File: readline.info, Node: Readline Variables, Next: Readline Convenience Functions, Prev: Custom Functions, Up: Programming with GNU Readline
1333 These variables are available to function writers.
1335 - Variable: char * rl_line_buffer
1336 This is the line gathered so far. You are welcome to modify the
1337 contents of the line, but see *Note Allowing Undoing::.
1339 - Variable: int rl_point
1340 The offset of the current cursor position in `rl_line_buffer' (the
1343 - Variable: int rl_end
1344 The number of characters present in `rl_line_buffer'. When
1345 `rl_point' is at the end of the line, `rl_point' and `rl_end' are
1348 - Variable: int rl_mark
1349 The mark (saved position) in the current line. If set, the mark
1350 and point define a *region*.
1352 - Variable: int rl_done
1353 Setting this to a non-zero value causes Readline to return the
1354 current line immediately.
1356 - Variable: int rl_pending_input
1357 Setting this to a value makes it the next keystroke read. This is
1358 a way to stuff a single character into the input stream.
1360 - Variable: char * rl_prompt
1361 The prompt Readline uses. This is set from the argument to
1362 `readline ()', and should not be assigned to directly.
1364 - Variable: char * rl_library_version
1365 The version number of this revision of the library.
1367 - Variable: char * rl_terminal_name
1368 The terminal type, used for initialization.
1370 - Variable: char * rl_readline_name
1371 This variable is set to a unique name by each application using
1372 Readline. The value allows conditional parsing of the inputrc file
1373 (*note Conditional Init Constructs::.).
1375 - Variable: FILE * rl_instream
1376 The stdio stream from which Readline reads input.
1378 - Variable: FILE * rl_outstream
1379 The stdio stream to which Readline performs output.
1381 - Variable: Function * rl_startup_hook
1382 If non-zero, this is the address of a function to call just before
1383 `readline' prints the first prompt.
1385 - Variable: Function * rl_event_hook
1386 If non-zero, this is the address of a function to call periodically
1387 when readline is waiting for terminal input.
1389 - Variable: Function * rl_getc_function
1390 If non-zero, `readline' will call indirectly through this pointer
1391 to get a character from the input stream. By default, it is set to
1392 `rl_getc', the default `readline' character input function (*note
1393 Utility Functions::.).
1395 - Variable: VFunction * rl_redisplay_function
1396 If non-zero, `readline' will call indirectly through this pointer
1397 to update the display with the current contents of the editing
1398 buffer. By default, it is set to `rl_redisplay', the default
1399 `readline' redisplay function (*note Redisplay::.).
1401 - Variable: Keymap rl_executing_keymap
1402 This variable is set to the keymap (*note Keymaps::.) in which the
1403 currently executing readline function was found.
1405 - Variable: Keymap rl_binding_keymap
1406 This variable is set to the keymap (*note Keymaps::.) in which the
1407 last key binding occurred.
1410 File: readline.info, Node: Readline Convenience Functions, Next: Custom Completers, Prev: Readline Variables, Up: Programming with GNU Readline
1412 Readline Convenience Functions
1413 ==============================
1417 * Function Naming:: How to give a function you write a name.
1418 * Keymaps:: Making keymaps.
1419 * Binding Keys:: Changing Keymaps.
1420 * Associating Function Names and Bindings:: Translate function names to
1422 * Allowing Undoing:: How to make your functions undoable.
1423 * Redisplay:: Functions to control line display.
1424 * Modifying Text:: Functions to modify `rl_line_buffer'.
1425 * Utility Functions:: Generally useful functions and hooks.
1426 * Alternate Interface:: Using Readline in a `callback' fashion.
1429 File: readline.info, Node: Function Naming, Next: Keymaps, Up: Readline Convenience Functions
1434 The user can dynamically change the bindings of keys while using
1435 Readline. This is done by representing the function with a descriptive
1436 name. The user is able to type the descriptive name when referring to
1437 the function. Thus, in an init file, one might find
1439 Meta-Rubout: backward-kill-word
1441 This binds the keystroke <Meta-Rubout> to the function
1442 *descriptively* named `backward-kill-word'. You, as the programmer,
1443 should bind the functions you write to descriptive names as well.
1444 Readline provides a function for doing that:
1446 - Function: int rl_add_defun (char *name, Function *function, int key)
1447 Add NAME to the list of named functions. Make FUNCTION be the
1448 function that gets called. If KEY is not -1, then bind it to
1449 FUNCTION using `rl_bind_key ()'.
1451 Using this function alone is sufficient for most applications. It is
1452 the recommended way to add a few functions to the default functions that
1453 Readline has built in. If you need to do something other than adding a
1454 function to Readline, you may need to use the underlying functions
1458 File: readline.info, Node: Keymaps, Next: Binding Keys, Prev: Function Naming, Up: Readline Convenience Functions
1463 Key bindings take place on a "keymap". The keymap is the
1464 association between the keys that the user types and the functions that
1465 get run. You can make your own keymaps, copy existing keymaps, and tell
1466 Readline which keymap to use.
1468 - Function: Keymap rl_make_bare_keymap ()
1469 Returns a new, empty keymap. The space for the keymap is
1470 allocated with `malloc ()'; you should `free ()' it when you are
1473 - Function: Keymap rl_copy_keymap (Keymap map)
1474 Return a new keymap which is a copy of MAP.
1476 - Function: Keymap rl_make_keymap ()
1477 Return a new keymap with the printing characters bound to
1478 rl_insert, the lowercase Meta characters bound to run their
1479 equivalents, and the Meta digits bound to produce numeric
1482 - Function: void rl_discard_keymap (Keymap keymap)
1483 Free the storage associated with KEYMAP.
1485 Readline has several internal keymaps. These functions allow you to
1486 change which keymap is active.
1488 - Function: Keymap rl_get_keymap ()
1489 Returns the currently active keymap.
1491 - Function: void rl_set_keymap (Keymap keymap)
1492 Makes KEYMAP the currently active keymap.
1494 - Function: Keymap rl_get_keymap_by_name (char *name)
1495 Return the keymap matching NAME. NAME is one which would be
1496 supplied in a `set keymap' inputrc line (*note Readline Init
1499 - Function: char * rl_get_keymap_name (Keymap keymap)
1500 Return the name matching KEYMAP. NAME is one which would be
1501 supplied in a `set keymap' inputrc line (*note Readline Init
1505 File: readline.info, Node: Binding Keys, Next: Associating Function Names and Bindings, Prev: Keymaps, Up: Readline Convenience Functions
1510 You associate keys with functions through the keymap. Readline has
1511 several internal keymaps: `emacs_standard_keymap', `emacs_meta_keymap',
1512 `emacs_ctlx_keymap', `vi_movement_keymap', and `vi_insertion_keymap'.
1513 `emacs_standard_keymap' is the default, and the examples in this manual
1516 These functions manage key bindings.
1518 - Function: int rl_bind_key (int key, Function *function)
1519 Binds KEY to FUNCTION in the currently active keymap. Returns
1520 non-zero in the case of an invalid KEY.
1522 - Function: int rl_bind_key_in_map (int key, Function *function,
1524 Bind KEY to FUNCTION in MAP. Returns non-zero in the case of an
1527 - Function: int rl_unbind_key (int key)
1528 Bind KEY to the null function in the currently active keymap.
1529 Returns non-zero in case of error.
1531 - Function: int rl_unbind_key_in_map (int key, Keymap map)
1532 Bind KEY to the null function in MAP. Returns non-zero in case of
1535 - Function: int rl_unbind_function_in_map (Function *function, Keymap
1537 Unbind all keys that execute FUNCTION in MAP.
1539 - Function: int rl_unbind_command_in_map (char *command, Keymap map)
1540 Unbind all keys that are bound to COMMAND in MAP.
1542 - Function: int rl_generic_bind (int type, char *keyseq, char *data,
1544 Bind the key sequence represented by the string KEYSEQ to the
1545 arbitrary pointer DATA. TYPE says what kind of data is pointed to
1546 by DATA; this can be a function (`ISFUNC'), a macro (`ISMACR'), or
1547 a keymap (`ISKMAP'). This makes new keymaps as necessary. The
1548 initial keymap in which to do bindings is MAP.
1550 - Function: int rl_parse_and_bind (char *line)
1551 Parse LINE as if it had been read from the `inputrc' file and
1552 perform any key bindings and variable assignments found (*note
1553 Readline Init File::.).
1555 - Function: int rl_read_init_file (char *filename)
1556 Read keybindings and variable assignments from FILENAME (*note
1557 Readline Init File::.).
1560 File: readline.info, Node: Associating Function Names and Bindings, Next: Allowing Undoing, Prev: Binding Keys, Up: Readline Convenience Functions
1562 Associating Function Names and Bindings
1563 ---------------------------------------
1565 These functions allow you to find out what keys invoke named
1566 functions and the functions invoked by a particular key sequence.
1568 - Function: Function * rl_named_function (char *name)
1569 Return the function with name NAME.
1571 - Function: Function * rl_function_of_keyseq (char *keyseq, Keymap
1573 Return the function invoked by KEYSEQ in keymap MAP. If MAP is
1574 NULL, the current keymap is used. If TYPE is not NULL, the type
1575 of the object is returned in it (one of `ISFUNC', `ISKMAP', or
1578 - Function: char ** rl_invoking_keyseqs (Function *function)
1579 Return an array of strings representing the key sequences used to
1580 invoke FUNCTION in the current keymap.
1582 - Function: char ** rl_invoking_keyseqs_in_map (Function *function,
1584 Return an array of strings representing the key sequences used to
1585 invoke FUNCTION in the keymap MAP.
1587 - Function: void rl_function_dumper (int readable)
1588 Print the readline function names and the key sequences currently
1589 bound to them to `rl_outstream'. If READABLE is non-zero, the
1590 list is formatted in such a way that it can be made part of an
1591 `inputrc' file and re-read.
1593 - Function: void rl_list_funmap_names ()
1594 Print the names of all bindable Readline functions to
1598 File: readline.info, Node: Allowing Undoing, Next: Redisplay, Prev: Associating Function Names and Bindings, Up: Readline Convenience Functions
1603 Supporting the undo command is a painless thing, and makes your
1604 functions much more useful. It is certainly easy to try something if
1605 you know you can undo it. I could use an undo function for the stock
1608 If your function simply inserts text once, or deletes text once, and
1609 uses `rl_insert_text ()' or `rl_delete_text ()' to do it, then undoing
1610 is already done for you automatically.
1612 If you do multiple insertions or multiple deletions, or any
1613 combination of these operations, you should group them together into
1614 one operation. This is done with `rl_begin_undo_group ()' and
1615 `rl_end_undo_group ()'.
1617 The types of events that can be undone are:
1619 enum undo_code { UNDO_DELETE, UNDO_INSERT, UNDO_BEGIN, UNDO_END };
1621 Notice that `UNDO_DELETE' means to insert some text, and
1622 `UNDO_INSERT' means to delete some text. That is, the undo code tells
1623 undo what to undo, not how to undo it. `UNDO_BEGIN' and `UNDO_END' are
1624 tags added by `rl_begin_undo_group ()' and `rl_end_undo_group ()'.
1626 - Function: int rl_begin_undo_group ()
1627 Begins saving undo information in a group construct. The undo
1628 information usually comes from calls to `rl_insert_text ()' and
1629 `rl_delete_text ()', but could be the result of calls to
1632 - Function: int rl_end_undo_group ()
1633 Closes the current undo group started with `rl_begin_undo_group
1634 ()'. There should be one call to `rl_end_undo_group ()' for each
1635 call to `rl_begin_undo_group ()'.
1637 - Function: void rl_add_undo (enum undo_code what, int start, int end,
1639 Remember how to undo an event (according to WHAT). The affected
1640 text runs from START to END, and encompasses TEXT.
1642 - Function: void free_undo_list ()
1643 Free the existing undo list.
1645 - Function: int rl_do_undo ()
1646 Undo the first thing on the undo list. Returns `0' if there was
1647 nothing to undo, non-zero if something was undone.
1649 Finally, if you neither insert nor delete text, but directly modify
1650 the existing text (e.g., change its case), call `rl_modifying ()' once,
1651 just before you modify the text. You must supply the indices of the
1652 text range that you are going to modify.
1654 - Function: int rl_modifying (int start, int end)
1655 Tell Readline to save the text between START and END as a single
1656 undo unit. It is assumed that you will subsequently modify that
1660 File: readline.info, Node: Redisplay, Next: Modifying Text, Prev: Allowing Undoing, Up: Readline Convenience Functions
1665 - Function: void rl_redisplay ()
1666 Change what's displayed on the screen to reflect the current
1667 contents of `rl_line_buffer'.
1669 - Function: int rl_forced_update_display ()
1670 Force the line to be updated and redisplayed, whether or not
1671 Readline thinks the screen display is correct.
1673 - Function: int rl_on_new_line ()
1674 Tell the update routines that we have moved onto a new (empty)
1675 line, usually after ouputting a newline.
1677 - Function: int rl_reset_line_state ()
1678 Reset the display state to a clean state and redisplay the current
1679 line starting on a new line.
1681 - Function: int rl_message (va_alist)
1682 The arguments are a string as would be supplied to `printf'. The
1683 resulting string is displayed in the "echo area". The echo area
1684 is also used to display numeric arguments and search strings.
1686 - Function: int rl_clear_message ()
1687 Clear the message in the echo area.
1690 File: readline.info, Node: Modifying Text, Next: Utility Functions, Prev: Redisplay, Up: Readline Convenience Functions
1695 - Function: int rl_insert_text (char *text)
1696 Insert TEXT into the line at the current cursor position.
1698 - Function: int rl_delete_text (int start, int end)
1699 Delete the text between START and END in the current line.
1701 - Function: char * rl_copy_text (int start, int end)
1702 Return a copy of the text between START and END in the current
1705 - Function: int rl_kill_text (int start, int end)
1706 Copy the text between START and END in the current line to the
1707 kill ring, appending or prepending to the last kill if the last
1708 command was a kill command. The text is deleted. If START is
1709 less than END, the text is appended, otherwise prepended. If the
1710 last command was not a kill, a new kill ring slot is used.
1713 File: readline.info, Node: Utility Functions, Next: Alternate Interface, Prev: Modifying Text, Up: Readline Convenience Functions
1718 - Function: int rl_read_key ()
1719 Return the next character available. This handles input inserted
1720 into the input stream via PENDING INPUT (*note Readline
1721 Variables::.) and `rl_stuff_char ()', macros, and characters read
1724 - Function: int rl_getc (FILE *)
1725 Return the next character available from the keyboard.
1727 - Function: int rl_stuff_char (int c)
1728 Insert C into the Readline input stream. It will be "read" before
1729 Readline attempts to read characters from the terminal with
1732 - Function: rl_extend_line_buffer (int len)
1733 Ensure that `rl_line_buffer' has enough space to hold LEN
1734 characters, possibly reallocating it if necessary.
1736 - Function: int rl_initialize ()
1737 Initialize or re-initialize Readline's internal state.
1739 - Function: int rl_reset_terminal (char *terminal_name)
1740 Reinitialize Readline's idea of the terminal settings using
1741 TERMINAL_NAME as the terminal type (e.g., `vt100').
1743 - Function: int alphabetic (int c)
1744 Return 1 if C is an alphabetic character.
1746 - Function: int numeric (int c)
1747 Return 1 if C is a numeric character.
1749 - Function: int ding ()
1750 Ring the terminal bell, obeying the setting of `bell-style'.
1752 The following are implemented as macros, defined in `chartypes.h'.
1754 - Function: int uppercase_p (int c)
1755 Return 1 if C is an uppercase alphabetic character.
1757 - Function: int lowercase_p (int c)
1758 Return 1 if C is a lowercase alphabetic character.
1760 - Function: int digit_p (int c)
1761 Return 1 if C is a numeric character.
1763 - Function: int to_upper (int c)
1764 If C is a lowercase alphabetic character, return the corresponding
1765 uppercase character.
1767 - Function: int to_lower (int c)
1768 If C is an uppercase alphabetic character, return the corresponding
1769 lowercase character.
1771 - Function: int digit_value (int c)
1772 If C is a number, return the value it represents.
1775 File: readline.info, Node: Alternate Interface, Prev: Utility Functions, Up: Readline Convenience Functions
1780 An alternate interface is available to plain `readline()'. Some
1781 applications need to interleave keyboard I/O with file, device, or
1782 window system I/O, typically by using a main loop to `select()' on
1783 various file descriptors. To accomodate this need, readline can also
1784 be invoked as a `callback' function from an event loop. There are
1785 functions available to make this easy.
1787 - Function: void rl_callback_handler_install (char *prompt, Vfunction
1789 Set up the terminal for readline I/O and display the initial
1790 expanded value of PROMPT. Save the value of LHANDLER to use as a
1791 callback when a complete line of input has been entered.
1793 - Function: void rl_callback_read_char ()
1794 Whenever an application determines that keyboard input is
1795 available, it should call `rl_callback_read_char()', which will
1796 read the next character from the current input source. If that
1797 character completes the line, `rl_callback_read_char' will invoke
1798 the LHANDLER function saved by `rl_callback_handler_install' to
1799 process the line. `EOF' is indicated by calling LHANDLER with a
1802 - Function: void rl_callback_handler_remove ()
1803 Restore the terminal to its initial state and remove the line
1804 handler. This may be called from within a callback as well as
1810 Here is a function which changes lowercase characters to their
1811 uppercase equivalents, and uppercase characters to lowercase. If this
1812 function was bound to `M-c', then typing `M-c' would change the case of
1813 the character under point. Typing `M-1 0 M-c' would change the case of
1814 the following 10 characters, leaving the cursor on the last character
1817 /* Invert the case of the COUNT following characters. */
1819 invert_case_line (count, key)
1822 register int start, end, i;
1826 if (rl_point >= rl_end)
1837 /* Find the end of the range to modify. */
1838 end = start + (count * direction);
1840 /* Force it to be within range. */
1856 /* Tell readline that we are modifying the line, so it will save
1857 the undo information. */
1858 rl_modifying (start, end);
1860 for (i = start; i != end; i++)
1862 if (uppercase_p (rl_line_buffer[i]))
1863 rl_line_buffer[i] = to_lower (rl_line_buffer[i]);
1864 else if (lowercase_p (rl_line_buffer[i]))
1865 rl_line_buffer[i] = to_upper (rl_line_buffer[i]);
1867 /* Move point to on top of the last character changed. */
1868 rl_point = (direction == 1) ? end - 1 : start;
1873 File: readline.info, Node: Custom Completers, Prev: Readline Convenience Functions, Up: Programming with GNU Readline
1878 Typically, a program that reads commands from the user has a way of
1879 disambiguating commands and data. If your program is one of these, then
1880 it can provide completion for commands, data, or both. The following
1881 sections describe how your program and Readline cooperate to provide
1886 * How Completing Works:: The logic used to do completion.
1887 * Completion Functions:: Functions provided by Readline.
1888 * Completion Variables:: Variables which control completion.
1889 * A Short Completion Example:: An example of writing completer subroutines.
1892 File: readline.info, Node: How Completing Works, Next: Completion Functions, Up: Custom Completers
1894 How Completing Works
1895 --------------------
1897 In order to complete some text, the full list of possible completions
1898 must be available. That is, it is not possible to accurately expand a
1899 partial word without knowing all of the possible words which make sense
1900 in that context. The Readline library provides the user interface to
1901 completion, and two of the most common completion functions: filename
1902 and username. For completing other types of text, you must write your
1903 own completion function. This section describes exactly what such
1904 functions must do, and provides an example.
1906 There are three major functions used to perform completion:
1908 1. The user-interface function `rl_complete ()'. This function is
1909 called with the same arguments as other Readline functions
1910 intended for interactive use: COUNT and INVOKING_KEY. It
1911 isolates the word to be completed and calls `completion_matches
1912 ()' to generate a list of possible completions. It then either
1913 lists the possible completions, inserts the possible completions,
1914 or actually performs the completion, depending on which behavior
1917 2. The internal function `completion_matches ()' uses your
1918 "generator" function to generate the list of possible matches, and
1919 then returns the array of these matches. You should place the
1920 address of your generator function in
1921 `rl_completion_entry_function'.
1923 3. The generator function is called repeatedly from
1924 `completion_matches ()', returning a string each time. The
1925 arguments to the generator function are TEXT and STATE. TEXT is
1926 the partial word to be completed. STATE is zero the first time
1927 the function is called, allowing the generator to perform any
1928 necessary initialization, and a positive non-zero integer for each
1929 subsequent call. When the generator function returns `(char
1930 *)NULL' this signals `completion_matches ()' that there are no
1931 more possibilities left. Usually the generator function computes
1932 the list of possible completions when STATE is zero, and returns
1933 them one at a time on subsequent calls. Each string the generator
1934 function returns as a match must be allocated with `malloc()';
1935 Readline frees the strings when it has finished with them.
1938 - Function: int rl_complete (int ignore, int invoking_key)
1939 Complete the word at or before point. You have supplied the
1940 function that does the initial simple matching selection algorithm
1941 (see `completion_matches ()'). The default is to do filename
1944 - Variable: Function * rl_completion_entry_function
1945 This is a pointer to the generator function for `completion_matches
1946 ()'. If the value of `rl_completion_entry_function' is `(Function
1947 *)NULL' then the default filename generator function,
1948 `filename_completion_function ()', is used.
1951 File: readline.info, Node: Completion Functions, Next: Completion Variables, Prev: How Completing Works, Up: Custom Completers
1953 Completion Functions
1954 --------------------
1956 Here is the complete list of callable completion functions present in
1959 - Function: int rl_complete_internal (int what_to_do)
1960 Complete the word at or before point. WHAT_TO_DO says what to do
1961 with the completion. A value of `?' means list the possible
1962 completions. `TAB' means do standard completion. `*' means
1963 insert all of the possible completions. `!' means to display all
1964 of the possible completions, if there is more than one, as well as
1965 performing partial completion.
1967 - Function: int rl_complete (int ignore, int invoking_key)
1968 Complete the word at or before point. You have supplied the
1969 function that does the initial simple matching selection algorithm
1970 (see `completion_matches ()' and `rl_completion_entry_function').
1971 The default is to do filename completion. This calls
1972 `rl_complete_internal ()' with an argument depending on
1975 - Function: int rl_possible_completions (int count, int invoking_key))
1976 List the possible completions. See description of `rl_complete
1977 ()'. This calls `rl_complete_internal ()' with an argument of `?'.
1979 - Function: int rl_insert_completions (int count, int invoking_key))
1980 Insert the list of possible completions into the line, deleting the
1981 partially-completed word. See description of `rl_complete ()'.
1982 This calls `rl_complete_internal ()' with an argument of `*'.
1984 - Function: char ** completion_matches (char *text, CPFunction
1986 Returns an array of `(char *)' which is a list of completions for
1987 TEXT. If there are no completions, returns `(char **)NULL'. The
1988 first entry in the returned array is the substitution for TEXT.
1989 The remaining entries are the possible completions. The array is
1990 terminated with a `NULL' pointer.
1992 ENTRY_FUNC is a function of two args, and returns a `(char *)'.
1993 The first argument is TEXT. The second is a state argument; it is
1994 zero on the first call, and non-zero on subsequent calls.
1995 ENTRY_FUNC returns a `NULL' pointer to the caller when there are
1998 - Function: char * filename_completion_function (char *text, int state)
1999 A generator function for filename completion in the general case.
2000 Note that completion in Bash is a little different because of all
2001 the pathnames that must be followed when looking up completions
2002 for a command. The Bash source is a useful reference for writing
2003 custom completion functions.
2005 - Function: char * username_completion_function (char *text, int state)
2006 A completion generator for usernames. TEXT contains a partial
2007 username preceded by a random character (usually `~'). As with all
2008 completion generators, STATE is zero on the first call and non-zero
2009 for subsequent calls.
2012 File: readline.info, Node: Completion Variables, Next: A Short Completion Example, Prev: Completion Functions, Up: Custom Completers
2014 Completion Variables
2015 --------------------
2017 - Variable: Function * rl_completion_entry_function
2018 A pointer to the generator function for `completion_matches ()'.
2019 `NULL' means to use `filename_entry_function ()', the default
2022 - Variable: CPPFunction * rl_attempted_completion_function
2023 A pointer to an alternative function to create matches. The
2024 function is called with TEXT, START, and END. START and END are
2025 indices in `rl_line_buffer' saying what the boundaries of TEXT
2026 are. If this function exists and returns `NULL', or if this
2027 variable is set to `NULL', then `rl_complete ()' will call the
2028 value of `rl_completion_entry_function' to generate matches,
2029 otherwise the array of strings returned will be used.
2031 - Variable: CPFunction * rl_filename_quoting_function
2032 A pointer to a function that will quote a filename in an
2033 application- specific fashion. This is called if filename
2034 completion is being attempted and one of the characters in
2035 `rl_filename_quote_characters' appears in a completed filename.
2036 The function is called with TEXT, MATCH_TYPE, and QUOTE_POINTER.
2037 The TEXT is the filename to be quoted. The MATCH_TYPE is either
2038 `SINGLE_MATCH', if there is only one completion match, or
2039 `MULT_MATCH'. Some functions use this to decide whether or not to
2040 insert a closing quote character. The QUOTE_POINTER is a pointer
2041 to any opening quote character the user typed. Some functions
2042 choose to reset this character.
2044 - Variable: CPFunction * rl_filename_dequoting_function
2045 A pointer to a function that will remove application-specific
2046 quoting characters from a filename before completion is attempted,
2047 so those characters do not interfere with matching the text
2048 against names in the filesystem. It is called with TEXT, the text
2049 of the word to be dequoted, and QUOTE_CHAR, which is the quoting
2050 character that delimits the filename (usually `'' or `"'). If
2051 QUOTE_CHAR is zero, the filename was not in an embedded string.
2053 - Variable: Function * rl_char_is_quoted_p
2054 A pointer to a function to call that determines whether or not a
2055 specific character in the line buffer is quoted, according to
2056 whatever quoting mechanism the program calling readline uses. The
2057 function is called with two arguments: TEXT, the text of the line,
2058 and INDEX, the index of the character in the line. It is used to
2059 decide whether a character found in
2060 `rl_completer_word_break_characters' should be used to break words
2063 - Variable: int rl_completion_query_items
2064 Up to this many items will be displayed in response to a
2065 possible-completions call. After that, we ask the user if she is
2066 sure she wants to see them all. The default value is 100.
2068 - Variable: char * rl_basic_word_break_characters
2069 The basic list of characters that signal a break between words for
2070 the completer routine. The default value of this variable is the
2071 characters which break words for completion in Bash, i.e., `"
2072 \t\n\"\\'`@$><=;|&{("'.
2074 - Variable: char * rl_basic_quote_characters
2075 List of quote characters which can cause a word break.
2077 - Variable: char * rl_completer_word_break_characters
2078 The list of characters that signal a break between words for
2079 `rl_complete_internal ()'. The default list is the value of
2080 `rl_basic_word_break_characters'.
2082 - Variable: char * rl_completer_quote_characters
2083 List of characters which can be used to quote a substring of the
2084 line. Completion occurs on the entire substring, and within the
2085 substring `rl_completer_word_break_characters' are treated as any
2086 other character, unless they also appear within this list.
2088 - Variable: char * rl_filename_quote_characters
2089 A list of characters that cause a filename to be quoted by the
2090 completer when they appear in a completed filename. The default
2093 - Variable: char * rl_special_prefixes
2094 The list of characters that are word break characters, but should
2095 be left in TEXT when it is passed to the completion function.
2096 Programs can use this to help determine what kind of completing to
2097 do. For instance, Bash sets this variable to "$@" so that it can
2098 complete shell variables and hostnames.
2100 - Variable: int rl_completion_append_character
2101 When a single completion alternative matches at the end of the
2102 command line, this character is appended to the inserted
2103 completion text. The default is a space character (` '). Setting
2104 this to the null character (`\0') prevents anything being appended
2105 automatically. This can be changed in custom completion functions
2106 to provide the "most sensible word separator character" according
2107 to an application-specific command line syntax specification.
2109 - Variable: int rl_ignore_completion_duplicates
2110 If non-zero, then disallow duplicates in the matches. Default is
2113 - Variable: int rl_filename_completion_desired
2114 Non-zero means that the results of the matches are to be treated as
2115 filenames. This is *always* zero on entry, and can only be changed
2116 within a completion entry generator function. If it is set to a
2117 non-zero value, directory names have a slash appended and Readline
2118 attempts to quote completed filenames if they contain any embedded
2119 word break characters.
2121 - Variable: int rl_filename_quoting_desired
2122 Non-zero means that the results of the matches are to be quoted
2123 using double quotes (or an application-specific quoting mechanism)
2124 if the completed filename contains any characters in
2125 `rl_filename_quote_chars'. This is *always* non-zero on entry,
2126 and can only be changed within a completion entry generator
2127 function. The quoting is effected via a call to the function
2128 pointed to by `rl_filename_quoting_function'.
2130 - Variable: int rl_inhibit_completion
2131 If this variable is non-zero, completion is inhibit<ed. The
2132 completion character will be inserted as any other bound to
2135 - Variable: Function * rl_ignore_some_completions_function
2136 This function, if defined, is called by the completer when real
2137 filename completion is done, after all the matching names have
2138 been generated. It is passed a `NULL' terminated array of matches.
2139 The first element (`matches[0]') is the maximal substring common
2140 to all matches. This function can re-arrange the list of matches
2141 as required, but each element deleted from the array must be freed.
2143 - Variable: Function * rl_directory_completion_hook
2144 This function, if defined, is allowed to modify the directory
2145 portion of filenames Readline completes. It is called with the
2146 address of a string (the current directory name) as an argument.
2147 It could be used to expand symbolic links or shell variables in
2151 File: readline.info, Node: A Short Completion Example, Prev: Completion Variables, Up: Custom Completers
2153 A Short Completion Example
2154 --------------------------
2156 Here is a small application demonstrating the use of the GNU Readline
2157 library. It is called `fileman', and the source code resides in
2158 `examples/fileman.c'. This sample application provides completion of
2159 command names, line editing features, and access to the history list.
2161 /* fileman.c -- A tiny application which demonstrates how to use the
2162 GNU Readline library. This application interactively allows users
2163 to manipulate files and their modes. */
2166 #include <sys/types.h>
2167 #include <sys/file.h>
2168 #include <sys/stat.h>
2169 #include <sys/errno.h>
2171 #include <readline/readline.h>
2172 #include <readline/history.h>
2174 extern char *getwd ();
2175 extern char *xmalloc ();
2177 /* The names of functions that actually do the manipulation. */
2178 int com_list (), com_view (), com_rename (), com_stat (), com_pwd ();
2179 int com_delete (), com_help (), com_cd (), com_quit ();
2181 /* A structure which contains information on the commands this program
2185 char *name; /* User printable name of the function. */
2186 Function *func; /* Function to call to do the job. */
2187 char *doc; /* Documentation for this function. */
2190 COMMAND commands[] = {
2191 { "cd", com_cd, "Change to directory DIR" },
2192 { "delete", com_delete, "Delete FILE" },
2193 { "help", com_help, "Display this text" },
2194 { "?", com_help, "Synonym for `help'" },
2195 { "list", com_list, "List files in DIR" },
2196 { "ls", com_list, "Synonym for `list'" },
2197 { "pwd", com_pwd, "Print the current working directory" },
2198 { "quit", com_quit, "Quit using Fileman" },
2199 { "rename", com_rename, "Rename FILE to NEWNAME" },
2200 { "stat", com_stat, "Print out statistics on FILE" },
2201 { "view", com_view, "View the contents of FILE" },
2202 { (char *)NULL, (Function *)NULL, (char *)NULL }
2205 /* Forward declarations. */
2206 char *stripwhite ();
2207 COMMAND *find_command ();
2209 /* The name of this program, as taken from argv[0]. */
2212 /* When non-zero, this global means the user is done using this program. */
2221 r = xmalloc (strlen (s) + 1);
2234 initialize_readline (); /* Bind our completer. */
2236 /* Loop reading and executing lines until the user quits. */
2237 for ( ; done == 0; )
2239 line = readline ("FileMan: ");
2244 /* Remove leading and trailing whitespace from the line.
2245 Then, if there is anything left, add it to the history list
2247 s = stripwhite (line);
2260 /* Execute a command line. */
2269 /* Isolate the command word. */
2271 while (line[i] && whitespace (line[i]))
2275 while (line[i] && !whitespace (line[i]))
2281 command = find_command (word);
2285 fprintf (stderr, "%s: No such command for FileMan.\n", word);
2289 /* Get argument to command, if any. */
2290 while (whitespace (line[i]))
2295 /* Call the function. */
2296 return ((*(command->func)) (word));
2299 /* Look up NAME as the name of a command, and return a pointer to that
2300 command. Return a NULL pointer if NAME isn't a command name. */
2307 for (i = 0; commands[i].name; i++)
2308 if (strcmp (name, commands[i].name) == 0)
2309 return (&commands[i]);
2311 return ((COMMAND *)NULL);
2314 /* Strip whitespace from the start and end of STRING. Return a pointer
2320 register char *s, *t;
2322 for (s = string; whitespace (*s); s++)
2328 t = s + strlen (s) - 1;
2329 while (t > s && whitespace (*t))
2336 /* **************************************************************** */
2338 /* Interface to Readline Completion */
2340 /* **************************************************************** */
2342 char *command_generator ();
2343 char **fileman_completion ();
2345 /* Tell the GNU Readline library how to complete. We want to try to complete
2346 on command names if this is the first word in the line, or on filenames
2348 initialize_readline ()
2350 /* Allow conditional parsing of the ~/.inputrc file. */
2351 rl_readline_name = "FileMan";
2353 /* Tell the completer that we want a crack first. */
2354 rl_attempted_completion_function = (CPPFunction *)fileman_completion;
2357 /* Attempt to complete on the contents of TEXT. START and END bound the
2358 region of rl_line_buffer that contains the word to complete. TEXT is
2359 the word to complete. We can use the entire contents of rl_line_buffer
2360 in case we want to do some simple parsing. Return the array of matches,
2361 or NULL if there aren't any. */
2363 fileman_completion (text, start, end)
2369 matches = (char **)NULL;
2371 /* If this word is at the start of the line, then it is a command
2372 to complete. Otherwise it is the name of a file in the current
2375 matches = completion_matches (text, command_generator);
2380 /* Generator function for command completion. STATE lets us know whether
2381 to start from scratch; without any state (i.e. STATE == 0), then we
2382 start at the top of the list. */
2384 command_generator (text, state)
2388 static int list_index, len;
2391 /* If this is a new word to complete, initialize now. This includes
2392 saving the length of TEXT for efficiency, and initializing the index
2397 len = strlen (text);
2400 /* Return the next name which partially matches from the command list. */
2401 while (name = commands[list_index].name)
2405 if (strncmp (name, text, len) == 0)
2406 return (dupstr(name));
2409 /* If no names matched, then return NULL. */
2410 return ((char *)NULL);
2413 /* **************************************************************** */
2415 /* FileMan Commands */
2417 /* **************************************************************** */
2419 /* String to pass to system (). This is for the LIST, VIEW and RENAME
2421 static char syscom[1024];
2423 /* List the file(s) named in arg. */
2430 sprintf (syscom, "ls -FClg %s", arg);
2431 return (system (syscom));
2437 if (!valid_argument ("view", arg))
2440 sprintf (syscom, "more %s", arg);
2441 return (system (syscom));
2447 too_dangerous ("rename");
2456 if (!valid_argument ("stat", arg))
2459 if (stat (arg, &finfo) == -1)
2465 printf ("Statistics for `%s':\n", arg);
2467 printf ("%s has %d link%s, and is %d byte%s in length.\n", arg,
2469 (finfo.st_nlink == 1) ? "" : "s",
2471 (finfo.st_size == 1) ? "" : "s");
2472 printf ("Inode Last Change at: %s", ctime (&finfo.st_ctime));
2473 printf (" Last access at: %s", ctime (&finfo.st_atime));
2474 printf (" Last modified at: %s", ctime (&finfo.st_mtime));
2481 too_dangerous ("delete");
2485 /* Print out help for ARG, or for all of the commands if ARG is
2493 for (i = 0; commands[i].name; i++)
2495 if (!*arg || (strcmp (arg, commands[i].name) == 0))
2497 printf ("%s\t\t%s.\n", commands[i].name, commands[i].doc);
2504 printf ("No commands match `%s'. Possibilties are:\n", arg);
2506 for (i = 0; commands[i].name; i++)
2508 /* Print in six columns. */
2515 printf ("%s\t", commands[i].name);
2525 /* Change to the directory ARG. */
2529 if (chdir (arg) == -1)
2539 /* Print out the current working directory. */
2548 printf ("Error getting pwd: %s\n", dir);
2552 printf ("Current directory is %s\n", dir);
2556 /* The user wishes to quit using this program. Just set DONE non-zero. */
2564 /* Function which tells you that you can't do this. */
2565 too_dangerous (caller)
2569 "%s: Too dangerous for me to distribute. Write it yourself.\n",
2573 /* Return non-zero if ARG is a valid argument for CALLER, else print
2574 an error message and return zero. */
2576 valid_argument (caller, arg)
2581 fprintf (stderr, "%s: Argument required.\n", caller);
2589 File: readline.info, Node: Concept Index, Next: Function and Variable Index, Prev: Programming with GNU Readline, Up: Top
2596 * command editing: Readline Bare Essentials.
2597 * editing command lines: Readline Bare Essentials.
2598 * initialization file, readline: Readline Init File.
2599 * interaction, readline: Readline Interaction.
2600 * kill ring: Readline Killing Commands.
2601 * killing text: Readline Killing Commands.
2602 * notation, readline: Readline Bare Essentials.
2603 * readline, function: Basic Behavior.
2604 * yanking text: Readline Killing Commands.
2607 File: readline.info, Node: Function and Variable Index, Prev: Concept Index, Up: Top
2609 Function and Variable Index
2610 ***************************
2614 * (: Utility Functions.
2615 * abort (C-g): Miscellaneous Commands.
2616 * accept-line (Newline, Return): Commands For History.
2617 * alphabetic: Utility Functions.
2618 * backward-char (C-b): Commands For Moving.
2619 * backward-delete-char (Rubout): Commands For Text.
2620 * backward-kill-line (C-x Rubout): Commands For Killing.
2621 * backward-kill-word (M-DEL): Commands For Killing.
2622 * backward-word (M-b): Commands For Moving.
2623 * beginning-of-history (M-<): Commands For History.
2624 * beginning-of-line (C-a): Commands For Moving.
2625 * bell-style: Readline Init File Syntax.
2626 * call-last-kbd-macro (C-x e): Keyboard Macros.
2627 * capitalize-word (M-c): Commands For Text.
2628 * character-search (C-]): Miscellaneous Commands.
2629 * character-search-backward (M-C-]): Miscellaneous Commands.
2630 * clear-screen (C-l): Commands For Moving.
2631 * comment-begin: Readline Init File Syntax.
2632 * complete (TAB): Commands For Completion.
2633 * completion-query-items: Readline Init File Syntax.
2634 * completion_matches: Completion Functions.
2635 * convert-meta: Readline Init File Syntax.
2636 * copy-backward-word (): Commands For Killing.
2637 * copy-forward-word (): Commands For Killing.
2638 * copy-region-as-kill (): Commands For Killing.
2639 * delete-char (C-d): Commands For Text.
2640 * delete-horizontal-space (): Commands For Killing.
2641 * digit-argument (M-0, M-1, ... M--): Numeric Arguments.
2642 * digit_p: Utility Functions.
2643 * digit_value: Utility Functions.
2644 * ding: Utility Functions.
2645 * disable-completion: Readline Init File Syntax.
2646 * do-uppercase-version (M-a, M-b, M-X, ...): Miscellaneous Commands.
2647 * downcase-word (M-l): Commands For Text.
2648 * dump-functions (): Miscellaneous Commands.
2649 * dump-macros (): Miscellaneous Commands.
2650 * dump-variables (): Miscellaneous Commands.
2651 * editing-mode: Readline Init File Syntax.
2652 * enable-keypad: Readline Init File Syntax.
2653 * end-kbd-macro (C-x )): Keyboard Macros.
2654 * end-of-history (M->): Commands For History.
2655 * end-of-line (C-e): Commands For Moving.
2656 * exchange-point-and-mark (C-x C-x): Miscellaneous Commands.
2657 * expand-tilde: Readline Init File Syntax.
2658 * filename_completion_function: Completion Functions.
2659 * forward-char (C-f): Commands For Moving.
2660 * forward-search-history (C-s): Commands For History.
2661 * forward-word (M-f): Commands For Moving.
2662 * free_undo_list: Allowing Undoing.
2663 * history-search-backward (): Commands For History.
2664 * history-search-forward (): Commands For History.
2665 * horizontal-scroll-mode: Readline Init File Syntax.
2666 * input-meta: Readline Init File Syntax.
2667 * insert-comment (M-#): Miscellaneous Commands.
2668 * insert-completions (M-*): Commands For Completion.
2669 * keymap: Readline Init File Syntax.
2670 * kill-line (C-k): Commands For Killing.
2671 * kill-region (): Commands For Killing.
2672 * kill-whole-line (): Commands For Killing.
2673 * kill-word (M-d): Commands For Killing.
2674 * lowercase_p: Utility Functions.
2675 * mark-modified-lines: Readline Init File Syntax.
2676 * menu-complete (): Commands For Completion.
2677 * meta-flag: Readline Init File Syntax.
2678 * next-history (C-n): Commands For History.
2679 * non-incremental-forward-search-history (M-n): Commands For History.
2680 * non-incremental-reverse-search-history (M-p): Commands For History.
2681 * numeric: Utility Functions.
2682 * output-meta: Readline Init File Syntax.
2683 * possible-completions (M-?): Commands For Completion.
2684 * prefix-meta (ESC): Miscellaneous Commands.
2685 * previous-history (C-p): Commands For History.
2686 * quoted-insert (C-q, C-v): Commands For Text.
2687 * re-read-init-file (C-x C-r): Miscellaneous Commands.
2688 * readline: Basic Behavior.
2689 * redraw-current-line (): Commands For Moving.
2690 * reverse-search-history (C-r): Commands For History.
2691 * revert-line (M-r): Miscellaneous Commands.
2692 * rl_add_defun: Function Naming.
2693 * rl_add_undo: Allowing Undoing.
2694 * rl_attempted_completion_function: Completion Variables.
2695 * rl_basic_quote_characters: Completion Variables.
2696 * rl_basic_word_break_characters: Completion Variables.
2697 * rl_begin_undo_group: Allowing Undoing.
2698 * rl_bind_key: Binding Keys.
2699 * rl_bind_key_in_map: Binding Keys.
2700 * rl_binding_keymap: Readline Variables.
2701 * rl_callback_handler_install: Alternate Interface.
2702 * rl_callback_handler_remove: Alternate Interface.
2703 * rl_callback_read_char: Alternate Interface.
2704 * rl_char_is_quoted_p: Completion Variables.
2705 * rl_clear_message: Redisplay.
2706 * rl_complete <1>: How Completing Works.
2707 * rl_complete: Completion Functions.
2708 * rl_complete_internal: Completion Functions.
2709 * rl_completer_quote_characters: Completion Variables.
2710 * rl_completer_word_break_characters: Completion Variables.
2711 * rl_completion_append_character: Completion Variables.
2712 * rl_completion_entry_function <1>: How Completing Works.
2713 * rl_completion_entry_function: Completion Variables.
2714 * rl_completion_query_items: Completion Variables.
2715 * rl_copy_keymap: Keymaps.
2716 * rl_copy_text: Modifying Text.
2717 * rl_delete_text: Modifying Text.
2718 * rl_directory_completion_hook: Completion Variables.
2719 * rl_discard_keymap: Keymaps.
2720 * rl_do_undo: Allowing Undoing.
2721 * rl_done: Readline Variables.
2722 * rl_end: Readline Variables.
2723 * rl_end_undo_group: Allowing Undoing.
2724 * rl_event_hook: Readline Variables.
2725 * rl_executing_keymap: Readline Variables.
2726 * rl_filename_completion_desired: Completion Variables.
2727 * rl_filename_dequoting_function: Completion Variables.
2728 * rl_filename_quote_characters: Completion Variables.
2729 * rl_filename_quoting_desired: Completion Variables.
2730 * rl_filename_quoting_function: Completion Variables.
2731 * rl_forced_update_display: Redisplay.
2732 * rl_function_dumper: Associating Function Names and Bindings.
2733 * rl_function_of_keyseq: Associating Function Names and Bindings.
2734 * rl_generic_bind: Binding Keys.
2735 * rl_get_keymap: Keymaps.
2736 * rl_get_keymap_by_name: Keymaps.
2737 * rl_get_keymap_name: Keymaps.
2738 * rl_getc: Utility Functions.
2739 * rl_getc_function: Readline Variables.
2740 * rl_ignore_completion_duplicates: Completion Variables.
2741 * rl_ignore_some_completions_function: Completion Variables.
2742 * rl_inhibit_completion: Completion Variables.
2743 * rl_initialize: Utility Functions.
2744 * rl_insert_completions: Completion Functions.
2745 * rl_insert_text: Modifying Text.
2746 * rl_instream: Readline Variables.
2747 * rl_invoking_keyseqs: Associating Function Names and Bindings.
2748 * rl_invoking_keyseqs_in_map: Associating Function Names and Bindings.
2749 * rl_kill_text: Modifying Text.
2750 * rl_library_version: Readline Variables.
2751 * rl_line_buffer: Readline Variables.
2752 * rl_list_funmap_names: Associating Function Names and Bindings.
2753 * rl_make_bare_keymap: Keymaps.
2754 * rl_make_keymap: Keymaps.
2755 * rl_mark: Readline Variables.
2756 * rl_message: Redisplay.
2757 * rl_modifying: Allowing Undoing.
2758 * rl_named_function: Associating Function Names and Bindings.
2759 * rl_on_new_line: Redisplay.
2760 * rl_outstream: Readline Variables.
2761 * rl_parse_and_bind: Binding Keys.
2762 * rl_pending_input: Readline Variables.
2763 * rl_point: Readline Variables.
2764 * rl_possible_completions: Completion Functions.
2765 * rl_prompt: Readline Variables.
2766 * rl_read_init_file: Binding Keys.
2767 * rl_read_key: Utility Functions.
2768 * rl_readline_name: Readline Variables.
2769 * rl_redisplay: Redisplay.
2770 * rl_redisplay_function: Readline Variables.
2771 * rl_reset_line_state: Redisplay.
2772 * rl_reset_terminal: Utility Functions.
2773 * rl_set_keymap: Keymaps.
2774 * rl_special_prefixes: Completion Variables.
2775 * rl_startup_hook: Readline Variables.
2776 * rl_stuff_char: Utility Functions.
2777 * rl_terminal_name: Readline Variables.
2778 * rl_unbind_command_in_map: Binding Keys.
2779 * rl_unbind_function_in_map: Binding Keys.
2780 * rl_unbind_key: Binding Keys.
2781 * rl_unbind_key_in_map: Binding Keys.
2782 * self-insert (a, b, A, 1, !, ...): Commands For Text.
2783 * set-mark (C-@): Miscellaneous Commands.
2784 * show-all-if-ambiguous: Readline Init File Syntax.
2785 * start-kbd-macro (C-x (): Keyboard Macros.
2786 * tilde-expand (M-~): Miscellaneous Commands.
2787 * to_lower: Utility Functions.
2788 * to_upper: Utility Functions.
2789 * transpose-chars (C-t): Commands For Text.
2790 * transpose-words (M-t): Commands For Text.
2791 * undo (C-_, C-x C-u): Miscellaneous Commands.
2792 * universal-argument (): Numeric Arguments.
2793 * unix-line-discard (C-u): Commands For Killing.
2794 * unix-word-rubout (C-w): Commands For Killing.
2795 * upcase-word (M-u): Commands For Text.
2796 * uppercase_p: Utility Functions.
2797 * username_completion_function: Completion Functions.
2798 * visible-stats: Readline Init File Syntax.
2799 * yank (C-y): Commands For Killing.
2800 * yank-last-arg (M-., M-_): Commands For History.
2801 * yank-nth-arg (M-C-y): Commands For History.
2802 * yank-pop (M-y): Commands For Killing.
2808 Node: Command Line Editing
\7f1776
2809 Node: Introduction and Notation
\7f2427
2810 Node: Readline Interaction
\7f3466
2811 Node: Readline Bare Essentials
\7f4659
2812 Node: Readline Movement Commands
\7f6200
2813 Node: Readline Killing Commands
\7f7166
2814 Node: Readline Arguments
\7f8882
2815 Node: Searching
\7f9857
2816 Node: Readline Init File
\7f11440
2817 Node: Readline Init File Syntax
\7f12487
2818 Node: Conditional Init Constructs
\7f21353
2819 Node: Sample Init File
\7f23792
2820 Node: Bindable Readline Commands
\7f26962
2821 Node: Commands For Moving
\7f27713
2822 Node: Commands For History
\7f28561
2823 Node: Commands For Text
\7f31313
2824 Node: Commands For Killing
\7f33099
2825 Node: Numeric Arguments
\7f35249
2826 Node: Commands For Completion
\7f36376
2827 Node: Keyboard Macros
\7f37862
2828 Node: Miscellaneous Commands
\7f38421
2829 Node: Readline vi Mode
\7f41225
2830 Node: Programming with GNU Readline
\7f42983
2831 Node: Basic Behavior
\7f43852
2832 Node: Custom Functions
\7f47178
2833 Node: The Function Type
\7f47779
2834 Node: Function Writing
\7f48624
2835 Node: Readline Variables
\7f49708
2836 Node: Readline Convenience Functions
\7f52796
2837 Node: Function Naming
\7f53527
2838 Node: Keymaps
\7f54755
2839 Node: Binding Keys
\7f56469
2840 Node: Associating Function Names and Bindings
\7f58677
2841 Node: Allowing Undoing
\7f60255
2842 Node: Redisplay
\7f62840
2843 Node: Modifying Text
\7f63911
2844 Node: Utility Functions
\7f64822
2845 Node: Alternate Interface
\7f66941
2846 Node: Custom Completers
\7f70235
2847 Node: How Completing Works
\7f70956
2848 Node: Completion Functions
\7f73952
2849 Node: Completion Variables
\7f76967
2850 Node: A Short Completion Example
\7f84119
2851 Node: Concept Index
\7f96425
2852 Node: Function and Variable Index
\7f97179