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