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