From b2e1757903be8a77c03f3fea68179790fc8ee24a Mon Sep 17 00:00:00 2001
From: Eric Norum
+
+[Top]
+[Contents]
+[Index]
+[ ? ]
+GNU History Library
+ +This document describes the GNU History library, a programming tool that +provides a consistent user interface for recalling lines of previously +typed input. +
+ +
++
+ 1. Using History Interactively GNU History User's Manual. + 2. Programming with GNU History GNU History Programmer's Manual. + A. Concept Index Index of concepts described in this manual. + B. Function and Variable Index Index of externally visible functions + and variables.
+ +
[ < ] | +[ > ] | +[ << ] | +[ Up ] | +[ >> ] | +[Top] | +[Contents] | +[Index] | +[ ? ] | +
+ +This chapter describes how to use the GNU History Library interactively, +from a user's standpoint. It should be considered a user's guide. For +information on using the GNU History Library in your own programs, +see section 2. Programming with GNU History. +
+ +
++
+ 1.1 History Expansion What it feels like using History as a user.
[ < ] | +[ > ] | +[ << ] | +[ Up ] | +[ >> ] | +[Top] | +[Contents] | +[Index] | +[ ? ] | +
+
+The History library provides a history expansion feature that is similar
+to the history expansion provided by csh
. This section
+describes the syntax used to manipulate the history information.
+
+ +History expansions introduce words from the history list into +the input stream, making it easy to repeat commands, insert the +arguments to a previous command into the current input line, or +fix errors in previous commands quickly. +
+ +History expansion takes place in two parts. The first is to determine +which line from the history list should be used during substitution. +The second is to select portions of that line for inclusion into the +current one. The line selected from the history is called the +event, and the portions of that line that are acted upon are +called words. Various modifiers are available to manipulate +the selected words. The line is broken into words in the same fashion +that Bash does, so that several words +surrounded by quotes are considered one word. +History expansions are introduced by the appearance of the +history expansion character, which is `!' by default. +
+ +
++
+ 1.1.1 Event Designators How to specify which history line to use. + 1.1.2 Word Designators Specifying which words are of interest. + 1.1.3 Modifiers Modifying the results of substitution.
[ < ] | +[ > ] | +[ << ] | +[ Up ] | +[ >> ] | +[Top] | +[Contents] | +[Index] | +[ ? ] | +
+ +An event designator is a reference to a command line entry in the +history list. + +
+ +
!
++ +
!n
++ +
!-n
++ +
!!
++ +
!string
++ +
!?string[?]
++ +
^string1^string2^
+!!:s/string1/string2/
.
++ +
!#
++ +
[ < ] | +[ > ] | +[ << ] | +[ Up ] | +[ >> ] | +[Top] | +[Contents] | +[Index] | +[ ? ] | +
+ +Word designators are used to select desired words from the event. +A `:' separates the event specification from the word designator. It +may be omitted if the word designator begins with a `^', `$', +`*', `-', or `%'. Words are numbered from the beginning +of the line, with the first word being denoted by 0 (zero). Words are +inserted into the current line separated by single spaces. +
+ +For example, +
+ +
!!
++ +
!!:$
+!$
.
++ +
!fi:2
+fi
.
++ +Here are the word designators: + +
0 (zero)
+0
th word. For many applications, this is the command word.
++ +
n
++ +
^
++ +
$
++ +
%
++ +
x-y
++ +
*
+0
th. This is a synonym for `1-$'.
+It is not an error to use `*' if there is just one word in the event;
+the empty string is returned in that case.
++ +
x*
++ +
x-
++ +
+ +If a word designator is supplied without an event specification, the +previous command is used as the event. +
[ < ] | +[ > ] | +[ << ] | +[ Up ] | +[ >> ] | +[Top] | +[Contents] | +[Index] | +[ ? ] | +
+ +After the optional word designator, you can add a sequence of one or more +of the following modifiers, each preceded by a `:'. +
+ +
h
++ +
t
++ +
r
++ +
e
++ +
p
++ +
s/old/new/
++ +
&
++ +
g
+gs/old/new/
,
+or with `&'.
++ +
[ < ] | +[ > ] | +[ << ] | +[ Up ] | +[ >> ] | +[Top] | +[Contents] | +[Index] | +[ ? ] | +
+ +This chapter describes how to interface programs that you write +with the GNU History Library. +It should be considered a technical guide. +For information on the interactive use of GNU History, see section 1. Using History Interactively. +
+ +
++
+ 2.1 Introduction to History What is the GNU History library for? + 2.2 History Storage How information is stored. + 2.3 History Functions Functions that you can use. + 2.4 History Variables Variables that control behaviour. + 2.5 History Programming Example Example of using the GNU History Library.
[ < ] | +[ > ] | +[ << ] | +[ Up ] | +[ >> ] | +[Top] | +[Contents] | +[Index] | +[ ? ] | +
+ +Many programs read input from the user a line at a time. The GNU +History library is able to keep track of those lines, associate arbitrary +data with each line, and utilize information from previous lines in +composing new ones. +
+ +The programmer using the History library has available functions +for remembering lines on a history list, associating arbitrary data +with a line, removing lines from the list, searching through the list +for a line containing an arbitrary text string, and referencing any line +in the list directly. In addition, a history expansion function +is available which provides for a consistent user interface across +different programs. +
+
+The user using programs written with the History library has the
+benefit of a consistent user interface with a set of well-known
+commands for manipulating the text of previous lines and using that text
+in new commands. The basic history manipulation commands are similar to
+the history substitution provided by csh
.
+
+ +If the programmer desires, he can use the Readline library, which +includes some history manipulation by default, and has the added +advantage of command line editing. +
+
+Before declaring any functions using any functionality the History
+library provides in other code, an application writer should include
+the file <readline/history.h>
in any file that uses the
+History library's features. It supplies extern declarations for all
+of the library's public functions and variables, and declares all of
+the public data structures.
+
[ < ] | +[ > ] | +[ << ] | +[ Up ] | +[ >> ] | +[Top] | +[Contents] | +[Index] | +[ ? ] | +
+ +The history list is an array of history entries. A history entry is +declared as follows: +
+ +
typedef void *histdata_t; + +typedef struct _hist_entry { + char *line; + histdata_t data; +} HIST_ENTRY; + |
+ +The history list itself might therefore be declared as +
+ +
HIST_ENTRY **the_history_list; + |
+ +The state of the History library is encapsulated into a single structure: +
+ +
/* + * A structure used to pass around the current state of the history. + */ +typedef struct _hist_state { + HIST_ENTRY **entries; /* Pointer to the entries themselves. */ + int offset; /* The location pointer within this array. */ + int length; /* Number of elements within this array. */ + int size; /* Number of slots allocated to this array. */ + int flags; +} HISTORY_STATE; + |
+
+If the flags member includes HS_STIFLED
, the history has been
+stifled.
+
[ < ] | +[ > ] | +[ << ] | +[ Up ] | +[ >> ] | +[Top] | +[Contents] | +[Index] | +[ ? ] | +
+ +This section describes the calling sequence for the various functions +exported by the GNU History library. +
+ +
++
+ 2.3.1 Initializing History and State Management Functions to call when you + want to use history in a + program. + 2.3.2 History List Management Functions used to manage the list + of history entries. + 2.3.3 Information About the History List Functions returning information about + the history list. + 2.3.4 Moving Around the History List Functions used to change the position + in the history list. + 2.3.5 Searching the History List Functions to search the history list + for entries containing a string. + 2.3.6 Managing the History File Functions that read and write a file + containing the history list. + 2.3.7 History Expansion Functions to perform csh-like history + expansion.
[ < ] | +[ > ] | +[ << ] | +[ Up ] | +[ >> ] | +[Top] | +[Contents] | +[Index] | +[ ? ] | +
+ +This section describes functions used to initialize and manage +the state of the History library when you want to use the history +functions in your program. +
[ < ] | +[ > ] | +[ << ] | +[ Up ] | +[ >> ] | +[Top] | +[Contents] | +[Index] | +[ ? ] | +
+ +These functions manage individual entries on the history list, or set +parameters managing the list itself. +
NULL
.
+NULL
pointer is returned.
+stifle_history()
).
+The value is positive if the history was
+stifled, negative if it wasn't.
+[ < ] | +[ > ] | +[ << ] | +[ Up ] | +[ >> ] | +[Top] | +[Contents] | +[Index] | +[ ? ] | +
+ +These functions return information about the entire history list or +individual list entries. +
NULL
terminated array of HIST_ENTRY *
which is the
+current input history. Element 0 of this list is the beginning of time.
+If there is no history, return NULL
.
+where_history()
. If there is no entry there, return a NULL
+pointer.
+history_base
(see section 2.4 History Variables).
+If there is no entry there, or if offset
+is greater than the history length, return a NULL
pointer.
+[ < ] | +[ > ] | +[ << ] | +[ Up ] | +[ >> ] | +[Top] | +[Contents] | +[Index] | +[ ? ] | +
+ +These functions allow the current index into the history list to be +set or changed. +
NULL
pointer.
+NULL
pointer.
+[ < ] | +[ > ] | +[ << ] | +[ Up ] | +[ >> ] | +[Top] | +[Contents] | +[Index] | +[ ? ] | +
+ +These functions allow searching of the history list for entries containing +a specific string. Searching may be performed both forward and backward +from the current history position. The search may be anchored, +meaning that the string must match at the beginning of the history entry. + +
[ < ] | +[ > ] | +[ << ] | +[ Up ] | +[ >> ] | +[Top] | +[Contents] | +[Index] | +[ ? ] | +
+ +The History library can read the history from and write it to a file. +This section documents the functions for managing a history file. +
NULL
, then read from `~/.history'.
+Returns 0 if successful, or errno
if not.
+NULL
, then read from `~/.history'. Returns 0 if successful,
+or errno
if not.
+NULL
, then write the history list to
+`~/.history'.
+Returns 0 on success, or errno
on a read or write error.
+NULL
, then append to `~/.history'.
+Returns 0 on success, or errno
on a read or write error.
+NULL
, then `~/.history' is truncated.
+Returns 0 on success, or errno
on failure.
+[ < ] | +[ > ] | +[ << ] | +[ Up ] | +[ >> ] | +[Top] | +[Contents] | +[Index] | +[ ? ] | +
+ +These functions implement history expansion. +
0
+1
+-1
+2
+:p
modifier (see section 1.1.3 Modifiers).
++ +If an error ocurred in expansion, then output contains a descriptive +error message. +
history_tokenize
.
+[ < ] | +[ > ] | +[ << ] | +[ Up ] | +[ >> ] | +[Top] | +[Contents] | +[Index] | +[ ? ] | +
+ +This section describes the externally-visible variables exported by +the GNU History Library. +
stifle_history()
.
+history_tokenize()
.
+The default value is " \t\n()<>;&|"
.
+char *
(string)
+and an int
index into that string (i).
+It should return a non-zero value if the history expansion starting at
+string[i] should not be performed; zero if the expansion should
+be done.
+It is intended for use by applications like Bash that use the history
+expansion character for additional purposes.
+By default, this variable is set to NULL
.
+[ < ] | +[ > ] | +[ << ] | +[ Up ] | +[ >> ] | +[Top] | +[Contents] | +[Index] | +[ ? ] | +
+ +The following program demonstrates simple use of the GNU History Library. +
+ +
#include <stdio.h> +#include <readline/history.h> + +main (argc, argv) + int argc; + char **argv; +{ + char line[1024], *t; + int len, done = 0; + + line[0] = 0; + + using_history (); + while (!done) + { + printf ("history$ "); + fflush (stdout); + t = fgets (line, sizeof (line) - 1, stdin); + if (t && *t) + { + len = strlen (t); + if (t[len - 1] == '\n') + t[len - 1] = '\0'; + } + + if (!t) + strcpy (line, "quit"); + + if (line[0]) + { + char *expansion; + int result; + + result = history_expand (line, &expansion); + if (result) + fprintf (stderr, "%s\n", expansion); + + if (result < 0 || result == 2) + { + free (expansion); + continue; + } + + add_history (expansion); + strncpy (line, expansion, sizeof (line) - 1); + free (expansion); + } + + if (strcmp (line, "quit") == 0) + done = 1; + else if (strcmp (line, "save") == 0) + write_history ("history_file"); + else if (strcmp (line, "read") == 0) + read_history ("history_file"); + else if (strcmp (line, "list") == 0) + { + register HIST_ENTRY **the_list; + register int i; + + the_list = history_list (); + if (the_list) + for (i = 0; the_list[i]; i++) + printf ("%d: %s\n", i + history_base, the_list[i]->line); + } + else if (strncmp (line, "delete", 6) == 0) + { + int which; + if ((sscanf (line + 6, "%d", &which)) == 1) + { + HIST_ENTRY *entry = remove_history (which); + if (!entry) + fprintf (stderr, "No such entry %d\n", which); + else + { + free (entry->line); + free (entry); + } + } + else + { + fprintf (stderr, "non-numeric arg given to `delete'\n"); + } + } + } +} + |
[ < ] | +[ > ] | +[ << ] | +[ Up ] | +[ >> ] | +[Top] | +[Contents] | +[Index] | +[ ? ] | +
Jump to: | A + +E + +H + + |
---|
Jump to: | A + +E + +H + + |
---|
[ < ] | +[ > ] | +[ << ] | +[ Up ] | +[ >> ] | +[Top] | +[Contents] | +[Index] | +[ ? ] | +
Jump to: | A + +C + +G + +H + +N + +P + +R + +S + +U + +W + + |
---|
Jump to: | A + +C + +G + +H + +N + +P + +R + +S + +U + +W + + |
---|
+ +
[Top] | +[Contents] | +[Index] | +[ ? ] | +
[Top] | +[Contents] | +[Index] | +[ ? ] | +
+1. Using History Interactively ++
+2. Programming with GNU History +
+A. Concept Index +
+B. Function and Variable Index +
+ +
[Top] | +[Contents] | +[Index] | +[ ? ] | +
Button | +Name | +Go to | +From 1.2.3 go to | +
---|---|---|---|
+ [ < ] | ++Back + | ++previous section in reading order + | ++1.2.2 + | +
+ [ > ] | ++Forward + | ++next section in reading order + | ++1.2.4 + | +
+ [ << ] | ++FastBack + | ++previous or up-and-previous section + | ++1.1 + | +
+ [ Up ] | ++Up + | ++up section + | ++1.2 + | +
+ [ >> ] | ++FastForward + | ++next or up-and-next section + | ++1.3 + | +
+ [Top] | ++Top + | ++cover (top) of document + | ++ + | +
+ [Contents] | ++Contents + | ++table of contents + | ++ + | +
+ [Index] | ++Index + | ++concept index + | ++ + | +
+ [ ? ] | ++About + | ++this page + | ++ + | +
[Top] | +[Contents] | +[Index] | +[ ? ] | +
+ +This document describes the GNU Readline Library, a utility which aids +in the consistency of user interface across discrete programs that need +to provide a command line interface. +
+ +
++
+ 1. Command Line Editing GNU Readline User's Manual. + 2. Programming with GNU Readline GNU Readline Programmer's Manual. + Concept Index Index of concepts described in this manual. + Function and Variable Index Index of externally visible functions + and variables.
+ +
[ < ] | +[ > ] | +[ << ] | +[ Up ] | +[ >> ] | +[Top] | +[Contents] | +[Index] | +[ ? ] | +
+ +This chapter describes the basic features of the GNU +command line editing interface. +
+ +
++
+ 1.1 Introduction to Line Editing Notation used in this text. + 1.2 Readline Interaction The minimum set of commands for editing a line. + 1.3 Readline Init File Customizing Readline from a user's view. + 1.4 Bindable Readline Commands A description of most of the Readline commands + available for binding + 1.5 Readline vi Mode A short description of how to make Readline + behave like the vi editor.
[ < ] | +[ > ] | +[ << ] | +[ Up ] | +[ >> ] | +[Top] | +[Contents] | +[Index] | +[ ? ] | +
+ +The following paragraphs describe the notation used to represent +keystrokes. +
+ +The text C-k is read as `Control-K' and describes the character +produced when the k key is pressed while the Control key +is depressed. +
+ +The text M-k is read as `Meta-K' and describes the character +produced when the Meta key (if you have one) is depressed, and the k +key is pressed. +The Meta key is labeled ALT on many keyboards. +On keyboards with two keys labeled ALT (usually to either side of +the space bar), the ALT on the left side is generally set to +work as a Meta key. +The ALT key on the right may also be configured to work as a +Meta key or may be configured as some other modifier, such as a +Compose key for typing accented characters. +
+ +If you do not have a Meta or ALT key, or another key working as +a Meta key, the identical keystroke can be generated by typing ESC +first, and then typing k. +Either process is known as metafying the k key. +
+ +The text M-C-k is read as `Meta-Control-k' and describes the +character produced by metafying C-k. +
+ +In addition, several keys have their own names. Specifically, +DEL, ESC, LFD, SPC, RET, and TAB all +stand for themselves when seen in this text, or in an init file +(see section 1.3 Readline Init File). +If your keyboard lacks a LFD key, typing C-j will +produce the desired character. +The RET key may be labeled Return or Enter on +some keyboards. +
[ < ] | +[ > ] | +[ << ] | +[ Up ] | +[ >> ] | +[Top] | +[Contents] | +[Index] | +[ ? ] | +
+ +Often during an interactive session you type in a long line of text, +only to notice that the first word on the line is misspelled. The +Readline library gives you a set of commands for manipulating the text +as you type it in, allowing you to just fix your typo, and not forcing +you to retype the majority of the line. Using these editing commands, +you move the cursor to the place that needs correction, and delete or +insert the text of the corrections. Then, when you are satisfied with +the line, you simply press RET. You do not have to be at the +end of the line to press RET; the entire line is accepted +regardless of the location of the cursor within the line. +
+ +
++
+ 1.2.1 Readline Bare Essentials The least you need to know about Readline. + 1.2.2 Readline Movement Commands Moving about the input line. + 1.2.3 Readline Killing Commands How to delete text, and how to get it back! + 1.2.4 Readline Arguments Giving numeric arguments to commands. + 1.2.5 Searching for Commands in the History Searching through previous lines.
[ < ] | +[ > ] | +[ << ] | +[ Up ] | +[ >> ] | +[Top] | +[Contents] | +[Index] | +[ ? ] | +
+ +In order to enter characters into the line, simply type them. The typed +character appears where the cursor was, and then the cursor moves one +space to the right. If you mistype a character, you can use your +erase character to back up and delete the mistyped character. +
+ +Sometimes you may mistype a character, and +not notice the error until you have typed several other characters. In +that case, you can type C-b to move the cursor to the left, and then +correct your mistake. Afterwards, you can move the cursor to the right +with C-f. +
+ +When you add text in the middle of a line, you will notice that characters +to the right of the cursor are `pushed over' to make room for the text +that you have inserted. Likewise, when you delete text behind the cursor, +characters to the right of the cursor are `pulled back' to fill in the +blank space created by the removal of the text. A list of the bare +essentials for editing the text of an input line follows. +
+ +
+ +(Depending on your configuration, the Backspace key be set to +delete the character to the left of the cursor and the DEL key set +to delete the character underneath the cursor, like C-d, rather +than the character to the left of the cursor.) +
[ < ] | +[ > ] | +[ << ] | +[ Up ] | +[ >> ] | +[Top] | +[Contents] | +[Index] | +[ ? ] | +
+ +The above table describes the most basic keystrokes that you need +in order to do editing of the input line. For your convenience, many +other commands have been added in addition to C-b, C-f, +C-d, and DEL. Here are some commands for moving more rapidly +about the line. +
+ +
+ +Notice how C-f moves forward a character, while M-f moves +forward a word. It is a loose convention that control keystrokes +operate on characters while meta keystrokes operate on words. +
[ < ] | +[ > ] | +[ << ] | +[ Up ] | +[ >> ] | +[Top] | +[Contents] | +[Index] | +[ ? ] | +
+ +Killing text means to delete the text from the line, but to save +it away for later use, usually by yanking (re-inserting) +it back into the line. +(`Cut' and `paste' are more recent jargon for `kill' and `yank'.) +
+ +If the description for a command says that it `kills' text, then you can +be sure that you can get the text back in a different (or the same) +place later. +
+ +When you use a kill command, the text is saved in a kill-ring. +Any number of consecutive kills save all of the killed text together, so +that when you yank it back, you get it all. The kill +ring is not line specific; the text that you killed on a previously +typed line is available to be yanked back later, when you are typing +another line. + +
+ +Here is the list of commands for killing text. +
+ +
+ +
+ +
+ +
+ +
+ +Here is how to yank the text back into the line. Yanking +means to copy the most-recently-killed text from the kill buffer. +
+ +
+ +
[ < ] | +[ > ] | +[ << ] | +[ Up ] | +[ >> ] | +[Top] | +[Contents] | +[Index] | +[ ? ] | +
+ +You can pass numeric arguments to Readline commands. Sometimes the +argument acts as a repeat count, other times it is the sign of the +argument that is significant. If you pass a negative argument to a +command which normally acts in a forward direction, that command will +act in a backward direction. For example, to kill text back to the +start of the line, you might type `M-- C-k'. +
+ +The general way to pass numeric arguments to a command is to type meta +digits before the command. If the first `digit' typed is a minus +sign (`-'), then the sign of the argument will be negative. Once +you have typed one meta digit to get the argument started, you can type +the remainder of the digits, and then the command. For example, to give +the C-d command an argument of 10, you could type `M-1 0 C-d', +which will delete the next ten characters on the input line. +
[ < ] | +[ > ] | +[ << ] | +[ Up ] | +[ >> ] | +[Top] | +[Contents] | +[Index] | +[ ? ] | +
+ +Readline provides commands for searching through the command history +for lines containing a specified string. +There are two search modes: incremental and non-incremental. +
+
+Incremental searches begin before the user has finished typing the
+search string.
+As each character of the search string is typed, Readline displays
+the next entry from the history matching the string typed so far.
+An incremental search requires only as many characters as needed to
+find the desired history entry.
+To search backward in the history for a particular string, type
+C-r. Typing C-s searches forward through the history.
+The characters present in the value of the isearch-terminators
variable
+are used to terminate an incremental search.
+If that variable has not been assigned a value, the ESC and
+C-J characters will terminate an incremental search.
+C-g will abort an incremental search and restore the original line.
+When the search is terminated, the history entry containing the
+search string becomes the current line.
+
+ +To find other matching entries in the history list, type C-r or +C-s as appropriate. +This will search backward or forward in the history for the next +entry matching the search string typed so far. +Any other key sequence bound to a Readline command will terminate +the search and execute that command. +For instance, a RET will terminate the search and accept +the line, thereby executing the command from the history list. +A movement command will terminate the search, make the last line found +the current line, and begin editing. +
+ +Readline remembers the last incremental search string. If two +C-rs are typed without any intervening characters defining a new +search string, any remembered search string is used. +
+ +Non-incremental searches read the entire search string before starting +to search for matching history lines. The search string may be +typed by the user or be part of the contents of the current line. +
[ < ] | +[ > ] | +[ << ] | +[ Up ] | +[ >> ] | +[Top] | +[Contents] | +[Index] | +[ ? ] | +
+
+Although the Readline library comes with a set of Emacs-like
+keybindings installed by default, it is possible to use a different set
+of keybindings.
+Any user can customize programs that use Readline by putting
+commands in an inputrc file, conventionally in his home directory.
+The name of this
+file is taken from the value of the environment variable INPUTRC
. If
+that variable is unset, the default is `~/.inputrc'.
+
+ +When a program which uses the Readline library starts up, the +init file is read, and the key bindings are set. +
+
+In addition, the C-x C-r
command re-reads this init file, thus
+incorporating any changes that you might have made to it.
+
+ +
++
+ ++ 1.3.1 Readline Init File Syntax Syntax for the commands in the inputrc file.
++
+ ++ 1.3.2 Conditional Init Constructs Conditional key bindings in the inputrc file.
++
+ 1.3.3 Sample Init File An example inputrc file.
[ < ] | +[ > ] | +[ << ] | +[ Up ] | +[ >> ] | +[Top] | +[Contents] | +[Index] | +[ ? ] | +
+ +There are only a few basic constructs allowed in the +Readline init file. Blank lines are ignored. +Lines beginning with a `#' are comments. +Lines beginning with a `$' indicate conditional +constructs (see section 1.3.2 Conditional Init Constructs). Other lines +denote variable settings and key bindings. +
+ +
set
command within the init file.
+The syntax is simple:
++ +
set variable value + |
+
+Here, for example, is how to
+change from the default Emacs-like key binding to use
+vi
line editing commands:
+
+ +
set editing-mode vi + |
+ +Variable names and values, where appropriate, are recognized without regard +to case. +
+ +A great deal of run-time behavior is changeable with the following +variables. +
bell-style
++ +
comment-begin
+insert-comment
command is executed. The default value
+is "#"
.
++ +
completion-ignore-case
++ +
completion-query-items
+100
.
++ +
convert-meta
++ +
disable-completion
+self-insert
. The default is `off'.
++ +
editing-mode
+editing-mode
variable controls which default set of
+key bindings is used. By default, Readline starts up in Emacs editing
+mode, where the keystrokes are most similar to Emacs. This variable can be
+set to either `emacs' or `vi'.
++ +
enable-keypad
++ +
expand-tilde
+
+
+
+If set to `on', the history code attempts to place point at the
+same location on each history line retrived with previous-history
+or next-history
.
+
+ +
horizontal-scroll-mode
++ +
input-meta
+meta-flag
is a
+synonym for this variable.
++ +
isearch-terminators
++ +
keymap
+keymap
names are
+emacs
,
+emacs-standard
,
+emacs-meta
,
+emacs-ctlx
,
+vi
,
+vi-move
,
+vi-command
, and
+vi-insert
.
+vi
is equivalent to vi-command
; emacs
is
+equivalent to emacs-standard
. The default value is emacs
.
+The value of the editing-mode
variable also affects the
+default keymap.
++ +
mark-directories
++ +
mark-modified-lines
++ +
mark-symlinked-directories
+mark-directories
).
+The default is `off'.
++ +
match-hidden-files
++ +
output-meta
++ +
page-completions
+more
-like pager
+to display a screenful of possible completions at a time.
+This variable is `on' by default.
++ +
print-completions-horizontally
++ +
show-all-if-ambiguous
++ +
visible-stats
++ +
+ +
+ +Once you know the name of the command, simply place on a line +in the init file the name of the key +you wish to bind the command to, a colon, and then the name of the +command. The name of the key +can be expressed in different ways, depending on what you find most +comfortable. +
+ +In addition to command names, readline allows keys to be bound +to a string that is inserted when the key is pressed (a macro). +
+ +
Control-u: universal-argument +Meta-Rubout: backward-kill-word +Control-o: "> output" + |
+
+In the above example, C-u is bound to the function
+universal-argument
,
+M-DEL is bound to the function backward-kill-word
, and
+C-o is bound to run the macro
+expressed on the right hand side (that is, to insert the text
+`> output' into the line).
+
+ +A number of symbolic character names are recognized while +processing this key binding syntax: +DEL, +ESC, +ESCAPE, +LFD, +NEWLINE, +RET, +RETURN, +RUBOUT, +SPACE, +SPC, +and +TAB. +
+ +
+ +
"\C-u": universal-argument +"\C-x\C-r": re-read-init-file +"\e[11~": "Function Key 1" + |
+
+In the above example, C-u is again bound to the function
+universal-argument
(just as it was in the first example),
+`C-x C-r' is bound to the function re-read-init-file
,
+and `ESC [ 1 1 ~' is bound to insert
+the text `Function Key 1'.
+
+ +
+ +The following GNU Emacs style escape sequences are available when +specifying key sequences: +
+ +
\C-
+\M-
+\e
+\\
+\"
+\'
++ +In addition to the GNU Emacs style escape sequences, a second +set of backslash escapes is available: +
+ +
\a
+\b
+\d
+\f
+\n
+\r
+\t
+\v
+\nnn
+\xHH
++ +When entering the text of a macro, single or double quotes must +be used to indicate a macro definition. +Unquoted text is assumed to be a function name. +In the macro body, the backslash escapes described above are expanded. +Backslash will quote any other character in the macro text, +including `"' and `''. +For example, the following binding will make `C-x \' +insert a single `\' into the line: +
"\C-x\\": "\\" + |
+ +
[ < ] | +[ > ] | +[ << ] | +[ Up ] | +[ >> ] | +[Top] | +[Contents] | +[Index] | +[ ? ] | +
+ +Readline implements a facility similar in spirit to the conditional +compilation features of the C preprocessor which allows key +bindings and variable settings to be performed as the result +of tests. There are four parser directives used. +
+ +
$if
+$if
construct allows bindings to be made based on the
+editing mode, the terminal being used, or the application using
+Readline. The text of the test extends to the end of the line;
+no characters are required to isolate it.
++ +
mode
+mode=
form of the $if
directive is used to test
+whether Readline is in emacs
or vi
mode.
+This may be used in conjunction
+with the `set keymap' command, for instance, to set bindings in
+the emacs-standard
and emacs-ctlx
keymaps only if
+Readline is starting out in emacs
mode.
++ +
term
+term=
form may be used to include terminal-specific
+key bindings, perhaps to bind the key sequences output by the
+terminal's function keys. The word on the right side of the
+`=' is tested against both the full name of the terminal and
+the portion of the terminal name before the first `-'. This
+allows sun
to match both sun
and sun-cmd
,
+for instance.
++ +
application
+$if Bash +# Quote the current or previous word +"\C-xq": "\eb\"\ef\"" +$endif + |
+ +
$endif
+$if
command.
++ +
$else
+$if
directive are executed if
+the test fails.
++ +
$include
+$include /etc/inputrc + |
[ < ] | +[ > ] | +[ << ] | +[ Up ] | +[ >> ] | +[Top] | +[Contents] | +[Index] | +[ ? ] | +
+ +Here is an example of an inputrc file. This illustrates key +binding, variable assignment, and conditional syntax. +
+ +
# This file controls the behaviour of line input editing for +# programs that use the GNU Readline library. Existing +# programs include FTP, Bash, and GDB. +# +# You can re-read the inputrc file with C-x C-r. +# Lines beginning with '#' are comments. +# +# First, include any systemwide bindings and variable +# assignments from /etc/Inputrc +$include /etc/Inputrc + +# +# Set various bindings for emacs mode. + +set editing-mode emacs + +$if mode=emacs + +Meta-Control-h: backward-kill-word Text after the function name is ignored + +# +# Arrow keys in keypad mode +# +#"\M-OD": backward-char +#"\M-OC": forward-char +#"\M-OA": previous-history +#"\M-OB": next-history +# +# Arrow keys in ANSI mode +# +"\M-[D": backward-char +"\M-[C": forward-char +"\M-[A": previous-history +"\M-[B": next-history +# +# Arrow keys in 8 bit keypad mode +# +#"\M-\C-OD": backward-char +#"\M-\C-OC": forward-char +#"\M-\C-OA": previous-history +#"\M-\C-OB": next-history +# +# Arrow keys in 8 bit ANSI mode +# +#"\M-\C-[D": backward-char +#"\M-\C-[C": forward-char +#"\M-\C-[A": previous-history +#"\M-\C-[B": next-history + +C-q: quoted-insert + +$endif + +# An old-style binding. This happens to be the default. +TAB: complete + +# Macros that are convenient for shell interaction +$if Bash +# edit the path +"\C-xp": "PATH=${PATH}\e\C-e\C-a\ef\C-f" +# prepare to type a quoted word -- +# insert open and close double quotes +# and move to just after the open quote +"\C-x\"": "\"\"\C-b" +# insert a backslash (testing backslash escapes +# in sequences and macros) +"\C-x\\": "\\" +# Quote the current or previous word +"\C-xq": "\eb\"\ef\"" +# Add a binding to refresh the line, which is unbound +"\C-xr": redraw-current-line +# Edit variable on current line. +"\M-\C-v": "\C-a\C-k$\C-y\M-\C-e\C-a\C-y=" +$endif + +# use a visible bell if one is available +set bell-style visible + +# don't strip characters to 7 bits when reading +set input-meta on + +# allow iso-latin1 characters to be inserted rather +# than converted to prefix-meta sequences +set convert-meta off + +# display characters with the eighth bit set directly +# rather than as meta-prefixed characters +set output-meta on + +# if there are more than 150 possible completions for +# a word, ask the user if he wants to see all of them +set completion-query-items 150 + +# For FTP +$if Ftp +"\C-xg": "get \M-?" +"\C-xt": "put \M-?" +"\M-.": yank-last-arg +$endif + |
[ < ] | +[ > ] | +[ << ] | +[ Up ] | +[ >> ] | +[Top] | +[Contents] | +[Index] | +[ ? ] | +
+ +
++
+ 1.4.1 Commands For Moving Moving about the line. + 1.4.2 Commands For Manipulating The History Getting at previous lines. + 1.4.3 Commands For Changing Text Commands for changing text. + 1.4.4 Killing And Yanking Commands for killing and yanking. + 1.4.5 Specifying Numeric Arguments Specifying numeric arguments, repeat counts. + 1.4.6 Letting Readline Type For You Getting Readline to do the typing for you. + 1.4.7 Keyboard Macros Saving and re-executing typed characters + 1.4.8 Some Miscellaneous Commands Other miscellaneous commands.
+ +This section describes Readline commands that may be bound to key +sequences. +Command names without an accompanying key sequence are unbound by default. +
+
+In the following descriptions, point refers to the current cursor
+position, and mark refers to a cursor position saved by the
+set-mark
command.
+The text between the point and mark is referred to as the region.
+
[ < ] | +[ > ] | +[ << ] | +[ Up ] | +[ >> ] | +[Top] | +[Contents] | +[Index] | +[ ? ] | +
beginning-of-line (C-a)
+end-of-line (C-e)
+forward-char (C-f)
+backward-char (C-b)
+forward-word (M-f)
+backward-word (M-b)
+clear-screen (C-l)
+redraw-current-line ()
++ +
[ < ] | +[ > ] | +[ << ] | +[ Up ] | +[ >> ] | +[Top] | +[Contents] | +[Index] | +[ ? ] | +
+ +
accept-line (Newline or Return)
+add_history()
.
+If this line is a modified history line, the history line is restored
+to its original state.
+previous-history (C-p)
+next-history (C-n)
+beginning-of-history (M-<)
+end-of-history (M->)
+reverse-search-history (C-r)
+forward-search-history (C-s)
+non-incremental-reverse-search-history (M-p)
+non-incremental-forward-search-history (M-n)
+history-search-forward ()
+history-search-backward ()
+yank-nth-arg (M-C-y)
+yank-last-arg (M-. or M-_)
+yank-nth-arg
.
+Successive calls to yank-last-arg
move back through the history
+list, inserting the last argument of each line in turn.
++ +
[ < ] | +[ > ] | +[ << ] | +[ Up ] | +[ >> ] | +[Top] | +[Contents] | +[Index] | +[ ? ] | +
+ +
delete-char (C-d)
+delete-char
, then
+return EOF.
+backward-delete-char (Rubout)
+forward-backward-delete-char ()
+quoted-insert (C-q or C-v)
+tab-insert (M-TAB)
+self-insert (a, b, A, 1, !, ...)
+transpose-chars (C-t)
+transpose-words (M-t)
+upcase-word (M-u)
+downcase-word (M-l)
+capitalize-word (M-c)
+overwrite-mode ()
+emacs
mode; vi
mode does overwrite differently.
+Each call to readline()
starts in insert mode.
+
+
+In overwrite mode, characters bound to self-insert
replace
+the text at point rather than pushing the text to the right.
+Characters bound to backward-delete-char
replace the character
+before point with a space.
+
+ +By default, this command is unbound. +
+ +
[ < ] | +[ > ] | +[ << ] | +[ Up ] | +[ >> ] | +[Top] | +[Contents] | +[Index] | +[ ? ] | +
+ +
kill-line (C-k)
+backward-kill-line (C-x Rubout)
+unix-line-discard (C-u)
+kill-whole-line ()
+kill-word (M-d)
+forward-word
.
+backward-kill-word (M-DEL)
+backward-word
.
+unix-word-rubout (C-w)
+delete-horizontal-space ()
+kill-region ()
+copy-region-as-kill ()
+copy-backward-word ()
+backward-word
.
+By default, this command is unbound.
+copy-forward-word ()
+forward-word
.
+By default, this command is unbound.
+yank (C-y)
+yank-pop (M-y)
+yank
or yank-pop
.
+[ < ] | +[ > ] | +[ << ] | +[ Up ] | +[ >> ] | +[Top] | +[Contents] | +[Index] | +[ ? ] | +
digit-argument (M-0, M-1, ... M--)
+universal-argument ()
+universal-argument
+again ends the numeric argument, but is otherwise ignored.
+As a special case, if this command is immediately followed by a
+character that is neither a digit or minus sign, the argument count
+for the next command is multiplied by four.
+The argument count is initially one, so executing this function the
+first time makes the argument count four, a second time makes the
+argument count sixteen, and so on.
+By default, this is not bound to a key.
+[ < ] | +[ > ] | +[ << ] | +[ Up ] | +[ >> ] | +[Top] | +[Contents] | +[Index] | +[ ? ] | +
+ +
complete (TAB)
+possible-completions (M-?)
+insert-completions (M-*)
+possible-completions
.
+menu-complete ()
+complete
, but replaces the word to be completed
+with a single match from the list of possible completions.
+Repeated execution of menu-complete
steps through the list
+of possible completions, inserting each match in turn.
+At the end of the list of completions, the bell is rung
+(subject to the setting of bell-style
)
+and the original text is restored.
+An argument of n moves n positions forward in the list
+of matches; a negative argument may be used to move backward
+through the list.
+This command is intended to be bound to TAB, but is unbound
+by default.
+delete-char-or-list ()
+delete-char
).
+If at the end of the line, behaves identically to
+possible-completions
.
+This command is unbound by default.
++ +
[ < ] | +[ > ] | +[ << ] | +[ Up ] | +[ >> ] | +[Top] | +[Contents] | +[Index] | +[ ? ] | +
start-kbd-macro (C-x ()
+end-kbd-macro (C-x ))
+call-last-kbd-macro (C-x e)
++ +
[ < ] | +[ > ] | +[ << ] | +[ Up ] | +[ >> ] | +[Top] | +[Contents] | +[Index] | +[ ? ] | +
re-read-init-file (C-x C-r)
+abort (C-g)
+bell-style
).
+do-uppercase-version (M-a, M-b, M-x, ...)
+prefix-meta (ESC)
+undo (C-_ or C-x C-u)
+revert-line (M-r)
+undo
+command enough times to get back to the beginning.
+tilde-expand (M-~)
+set-mark (C-@)
+exchange-point-and-mark (C-x C-x)
+character-search (C-])
+character-search-backward (M-C-])
+insert-comment (M-#)
+comment-begin
+variable is inserted at the beginning of the current line.
+If a numeric argument is supplied, this command acts as a toggle: if
+the characters at the beginning of the line do not match the value
+of comment-begin
, the value is inserted, otherwise
+the characters in comment-begin
are deleted from the beginning of
+the line.
+In either case, the line is accepted as if a newline had been typed.
+dump-functions ()
+dump-variables ()
+dump-macros ()
+emacs-editing-mode (C-e)
+vi
command mode, this causes a switch to emacs
+editing mode.
+vi-editing-mode (M-C-j)
+emacs
editing mode, this causes a switch to vi
+editing mode.
++ +
[ < ] | +[ > ] | +[ << ] | +[ Up ] | +[ >> ] | +[Top] | +[Contents] | +[Index] | +[ ? ] | +
+
+While the Readline library does not have a full set of vi
+editing functions, it does contain enough to allow simple editing
+of the line. The Readline vi
mode behaves as specified in
+the POSIX 1003.2 standard.
+
+
+In order to switch interactively between emacs
and vi
+editing modes, use the command M-C-j (bound to emacs-editing-mode
+when in vi
mode and to vi-editing-mode in emacs
mode).
+The Readline default is emacs
mode.
+
+
+When you enter a line in vi
mode, you are already placed in
+`insertion' mode, as if you had typed an `i'. Pressing ESC
+switches you into `command' mode, where you can edit the text of the
+line with the standard vi
movement keys, move to previous
+history lines with `k' and subsequent lines with `j', and
+so forth.
+
+ +This document describes the GNU Readline Library, a utility for aiding +in the consitency of user interface across discrete programs that need +to provide a command line interface. +
+ +Copyright (C) 1988-2002 Free Software Foundation, Inc. +
+ +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +pare preserved on all copies. +
+ +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided that the entire +resulting derived work is distributed under the terms of a permission +notice identical to this one. +
+ +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions, +except that this permission notice may be stated in a translation approved +by the Foundation. +
[ < ] | +[ > ] | +[ << ] | +[ Up ] | +[ >> ] | +[Top] | +[Contents] | +[Index] | +[ ? ] | +
+ +This chapter describes the interface between the GNU Readline Library and +other programs. If you are a programmer, and you wish to include the +features found in GNU Readline +such as completion, line editing, and interactive history manipulation +in your own programs, this section is for you. +
+ +
++
+ 2.1 Basic Behavior Using the default behavior of Readline. + 2.2 Custom Functions Adding your own functions to Readline. + 2.3 Readline Variables Variables accessible to custom + functions. + 2.4 Readline Convenience Functions Functions which Readline supplies to + aid in writing your own custom + functions. + 2.5 Readline Signal Handling How Readline behaves when it receives signals. + 2.6 Custom Completers Supplanting or supplementing Readline's + completion functions.
[ < ] | +[ > ] | +[ << ] | +[ Up ] | +[ >> ] | +[Top] | +[Contents] | +[Index] | +[ ? ] | +
+
+Many programs provide a command line interface, such as mail
,
+ftp
, and sh
. For such programs, the default behaviour of
+Readline is sufficient. This section describes how to use Readline in
+the simplest way possible, perhaps to replace calls in your code to
+gets()
or fgets()
.
+
+
+The function readline()
prints a prompt prompt
+and then reads and returns a single line of text from the user.
+If prompt is NULL
or the empty string, no prompt is displayed.
+The line readline
returns is allocated with malloc()
;
+the caller should free()
the line when it has finished with it.
+The declaration for readline
in ANSI C is
+
+ +
|
+ +So, one might say +
|
+
+If readline
encounters an EOF
while reading the line, and the
+line is empty at that point, then (char *)NULL
is returned.
+Otherwise, the line is ended just as if a newline had been typed.
+
+
+If you want the user to be able to get at the line later, (with
+C-p for example), you must call add_history()
to save the
+line away in a history list of such lines.
+
+ +
|
+ +For full details on the GNU History Library, see the associated manual. +
+
+It is preferable to avoid saving empty lines on the history list, since
+users rarely have a burning need to reuse a blank line. Here is
+a function which usefully replaces the standard gets()
library
+function, and has the advantage of no static buffer to overflow:
+
+ +
/* A static variable for holding the line. */ +static char *line_read = (char *)NULL; + +/* Read a string, and return a pointer to it. + Returns NULL on EOF. */ +char * +rl_gets () +{ + /* If the buffer has already been allocated, + return the memory to the free pool. */ + if (line_read) + { + free (line_read); + line_read = (char *)NULL; + } + + /* Get a line from the user. */ + line_read = readline (""); + + /* If the line has any text in it, + save it on the history. */ + if (line_read && *line_read) + add_history (line_read); + + return (line_read); +} + |
+
+This function gives the user the default behaviour of TAB
+completion: completion on file names. If you do not want Readline to
+complete on filenames, you can change the binding of the TAB key
+with rl_bind_key()
.
+
+ +
|
+
+rl_bind_key()
takes two arguments: key is the character that
+you want to bind, and function is the address of the function to
+call when key is pressed. Binding TAB to rl_insert()
+makes TAB insert itself.
+rl_bind_key()
returns non-zero if key is not a valid
+ASCII character code (between 0 and 255).
+
+ +Thus, to disable the default TAB behavior, the following suffices: +
|
+
+This code should be executed once at the start of your program; you
+might write a function called initialize_readline()
which
+performs this and other desired initializations, such as installing
+custom completers (see section 2.6 Custom Completers).
+
[ < ] | +[ > ] | +[ << ] | +[ Up ] | +[ >> ] | +[Top] | +[Contents] | +[Index] | +[ ? ] | +
+ +Readline provides many functions for manipulating the text of +the line, but it isn't possible to anticipate the needs of all +programs. This section describes the various functions and variables +defined within the Readline library which allow a user program to add +customized functionality to Readline. +
+
+Before declaring any functions that customize Readline's behavior, or
+using any functionality Readline provides in other code, an
+application writer should include the file <readline/readline.h>
+in any file that uses Readline's features. Since some of the definitions
+in readline.h
use the stdio
library, the file
+<stdio.h>
should be included before readline.h
.
+
+
+readline.h
defines a C preprocessor variable that should
+be treated as an integer, RL_READLINE_VERSION
, which may
+be used to conditionally compile application code depending on
+the installed Readline version. The value is a hexadecimal
+encoding of the major and minor version numbers of the library,
+of the form 0xMMmm. MM is the two-digit major
+version number; mm is the two-digit minor version number.
+For Readline 4.2, for example, the value of
+RL_READLINE_VERSION
would be 0x0402
.
+
+ +
++
+ 2.2.1 Readline Typedefs C declarations to make code readable. + 2.2.2 Writing a New Function Variables and calling conventions.
[ < ] | +[ > ] | +[ << ] | +[ Up ] | +[ >> ] | +[Top] | +[Contents] | +[Index] | +[ ? ] | +
+ +For readabilty, we declare a number of new object types, all pointers +to functions. +
+ +The reason for declaring these new types is to make it easier to write +code describing pointers to C functions with appropriately prototyped +arguments and return values. +
+
+For instance, say we want to declare a variable func as a pointer
+to a function which takes two int
arguments and returns an
+int
(this is the type of all of the Readline bindable functions).
+Instead of the classic C declaration
+
+
+int (*func)();
+
+ +or the ANSI-C style declaration +
+
+int (*func)(int, int);
+
+ +we may write +
+
+rl_command_func_t *func;
+
+ +The full list of function pointer types available is +
+ +
typedef int rl_command_func_t (int, int);
++ +
typedef char *rl_compentry_func_t (const char *, int);
++ +
typedef char **rl_completion_func_t (const char *, int, int);
++ +
typedef char *rl_quote_func_t (char *, int, char *);
++ +
typedef char *rl_dequote_func_t (char *, int);
++ +
typedef int rl_compignore_func_t (char **);
++ +
typedef void rl_compdisp_func_t (char **, int, int);
++ +
typedef int rl_hook_func_t (void);
++ +
typedef int rl_getc_func_t (FILE *);
++ +
typedef int rl_linebuf_func_t (char *, int);
++ +
typedef int rl_intfunc_t (int);
+#define rl_ivoidfunc_t rl_hook_func_t
+typedef int rl_icpfunc_t (char *);
+typedef int rl_icppfunc_t (char **);
++ +
typedef void rl_voidfunc_t (void);
+typedef void rl_vintfunc_t (int);
+typedef void rl_vcpfunc_t (char *);
+typedef void rl_vcppfunc_t (char **);
++ +
[ < ] | +[ > ] | +[ << ] | +[ Up ] | +[ >> ] | +[Top] | +[Contents] | +[Index] | +[ ? ] | +
+ +In order to write new functions for Readline, you need to know the +calling conventions for keyboard-invoked functions, and the names of the +variables that describe the current state of the line read so far. +
+
+The calling sequence for a command foo
looks like
+
+ +
|
+ +where count is the numeric argument (or 1 if defaulted) and +key is the key that invoked this function. +
+ +It is completely up to the function as to what should be done with the +numeric argument. Some functions use it as a repeat count, some +as a flag, and others to choose alternate behavior (refreshing the current +line as opposed to refreshing the screen, for example). Some choose to +ignore it. In general, if a +function uses the numeric argument as a repeat count, it should be able +to do something useful with both negative and positive arguments. +At the very least, it should be aware that it can be passed a +negative argument. +
+ +A command function should return 0 if its action completes successfully, +and a non-zero value if some error occurs. +
[ < ] | +[ > ] | +[ << ] | +[ Up ] | +[ >> ] | +[Top] | +[Contents] | +[Index] | +[ ? ] | +
+ +These variables are available to function writers. +
rl_extend_line_buffer
is available to increase
+the memory allocated to rl_line_buffer
.
+rl_line_buffer
+(the point).
+rl_line_buffer
. When
+rl_point
is at the end of the line, rl_point
and
+rl_end
are equal.
+readline()
causes
+Readline to return after accepting that many characters, rather
+than reading up to a character bound to accept-line
.
+readline()
, and should not be assigned to directly.
+The rl_set_prompt()
function (see section 2.4.6 Redisplay) may
+be used to modify the prompt string after calling readline()
.
+readline()
is called, it should set
+this variable to a non-zero value after displaying the prompt.
+The prompt must also be passed as the argument to readline()
so
+the redisplay functions can update the display properly.
+The calling application is responsible for managing the value; Readline
+never sets it.
+rl_readline_version
would have the
+value 0x0402.
+TERM
environment variable
+the first time it is called.
+NULL
, Readline defaults to stdin.
+NULL
, Readline defaults to stdout.
+readline
prints the first prompt.
+readline
+starts reading input characters.
+rl_getc
, the default Readline character input function
+(see section 2.4.8 Character Input).
+rl_redisplay
, the default Readline
+redisplay function (see section 2.4.6 Redisplay).
+int
flag that says whether or not to use eight-bit characters.
+By default, this is set to rl_prep_terminal
+(see section 2.4.9 Terminal Management).
+rl_prep_term_function
.
+By default, this is set to rl_deprep_terminal
+(see section 2.4.9 Terminal Management).
+RL_SETSTATE
macro, and unset with the
+RL_UNSETSTATE
macro. Use the RL_ISSTATE
macro to test
+whether a particular state bit is set. Current state bits include:
++ +
RL_STATE_NONE
+RL_STATE_INITIALIZING
+RL_STATE_INITIALIZED
+RL_STATE_TERMPREPPED
+RL_STATE_READCMD
+RL_STATE_METANEXT
+RL_STATE_DISPATCHING
+RL_STATE_MOREINPUT
+RL_STATE_ISEARCH
+RL_STATE_NSEARCH
+RL_STATE_SEARCH
+RL_STATE_NUMERICARG
+RL_STATE_MACROINPUT
+RL_STATE_MACRODEF
+RL_STATE_OVERWRITE
+RL_STATE_COMPLETING
+RL_STATE_SIGHANDLER
+RL_STATE_UNDOING
+RL_STATE_DONE
+accept-line
+and is about to return the line to the caller.
++ +
[ < ] | +[ > ] | +[ << ] | +[ Up ] | +[ >> ] | +[Top] | +[Contents] | +[Index] | +[ ? ] | +
+ +
++
+ 2.4.1 Naming a Function How to give a function you write a name. + 2.4.2 Selecting a Keymap Making keymaps. + 2.4.3 Binding Keys Changing Keymaps. + 2.4.4 Associating Function Names and Bindings Translate function names to + key sequences. + 2.4.5 Allowing Undoing How to make your functions undoable. + 2.4.6 Redisplay Functions to control line display. + 2.4.7 Modifying Text Functions to modify rl_line_buffer
.+ 2.4.8 Character Input Functions to read keyboard input. + 2.4.9 Terminal Management Functions to manage terminal settings. + 2.4.10 Utility Functions Generally useful functions and hooks. + 2.4.11 Miscellaneous Functions Functions that don't fall into any category. + 2.4.12 Alternate Interface Using Readline in a `callback' fashion. + 2.4.13 A Readline Example An example Readline function.
[ < ] | +[ > ] | +[ << ] | +[ Up ] | +[ >> ] | +[Top] | +[Contents] | +[Index] | +[ ? ] | +
+ +The user can dynamically change the bindings of keys while using +Readline. This is done by representing the function with a descriptive +name. The user is able to type the descriptive name when referring to +the function. Thus, in an init file, one might find +
+ +
Meta-Rubout: backward-kill-word + |
+
+This binds the keystroke Meta-Rubout to the function
+descriptively named backward-kill-word
. You, as the
+programmer, should bind the functions you write to descriptive names as
+well. Readline provides a function for doing that:
+
rl_bind_key()
.
++ +Using this function alone is sufficient for most applications. It is +the recommended way to add a few functions to the default functions that +Readline has built in. If you need to do something other +than adding a function to Readline, you may need to use the +underlying functions described below. +
[ < ] | +[ > ] | +[ << ] | +[ Up ] | +[ >> ] | +[Top] | +[Contents] | +[Index] | +[ ? ] | +
+ +Key bindings take place on a keymap. The keymap is the +association between the keys that the user types and the functions that +get run. You can make your own keymaps, copy existing keymaps, and tell +Readline which keymap to use. +
malloc()
; the caller should free it by calling
+rl_discard_keymap()
when done.
++ +Readline has several internal keymaps. These functions allow you to +change which keymap is active. +
set keymap
inputrc line (see section 1.3 Readline Init File).
+set keymap
inputrc line (see section 1.3 Readline Init File).
+[ < ] | +[ > ] | +[ << ] | +[ Up ] | +[ >> ] | +[Top] | +[Contents] | +[Index] | +[ ? ] | +
+
+Key sequences are associate with functions through the keymap.
+Readline has several internal keymaps: emacs_standard_keymap
,
+emacs_meta_keymap
, emacs_ctlx_keymap
,
+vi_movement_keymap
, and vi_insertion_keymap
.
+emacs_standard_keymap
is the default, and the examples in
+this manual assume that.
+
+
+Since readline()
installs a set of default key bindings the first
+time it is called, there is always the danger that a custom binding
+installed before the first call to readline()
will be overridden.
+An alternate mechanism is to install custom key bindings in an
+initialization function assigned to the rl_startup_hook
variable
+(see section 2.3 Readline Variables).
+
+ +These functions manage key bindings. +
ISFUNC
), a macro
+(ISMACR
), or a keymap (ISKMAP
). This makes new keymaps as
+necessary. The initial keymap in which to do bindings is map.
+inputrc
file and
+perform any key bindings and variable assignments found
+(see section 1.3 Readline Init File).
+[ < ] | +[ > ] | +[ << ] | +[ Up ] | +[ >> ] | +[Top] | +[Contents] | +[Index] | +[ ? ] | +
+ +These functions allow you to find out what keys invoke named functions +and the functions invoked by a particular key sequence. You may also +associate a new function name with an arbitrary function. +
NULL
, the current keymap is used. If type is
+not NULL
, the type of the object is returned in the int
variable
+it points to (one of ISFUNC
, ISKMAP
, or ISMACR
).
+rl_outstream
. If readable is non-zero,
+the list is formatted in such a way that it can be made part of an
+inputrc
file and re-read.
+rl_outstream
.
+free()
the array when you are done, but not the pointers.
+[ < ] | +[ > ] | +[ << ] | +[ Up ] | +[ >> ] | +[Top] | +[Contents] | +[Index] | +[ ? ] | +
+ +Supporting the undo command is a painless thing, and makes your +functions much more useful. It is certainly easy to try +something if you know you can undo it. +
+
+If your function simply inserts text once, or deletes text once, and
+uses rl_insert_text()
or rl_delete_text()
to do it, then
+undoing is already done for you automatically.
+
+
+If you do multiple insertions or multiple deletions, or any combination
+of these operations, you should group them together into one operation.
+This is done with rl_begin_undo_group()
and
+rl_end_undo_group()
.
+
+ +The types of events that can be undone are: +
+ +
enum undo_code { UNDO_DELETE, UNDO_INSERT, UNDO_BEGIN, UNDO_END }; + |
+
+Notice that UNDO_DELETE
means to insert some text, and
+UNDO_INSERT
means to delete some text. That is, the undo code
+tells what to undo, not how to undo it. UNDO_BEGIN
and
+UNDO_END
are tags added by rl_begin_undo_group()
and
+rl_end_undo_group()
.
+
rl_insert_text()
and
+rl_delete_text()
, but could be the result of calls to
+rl_add_undo()
.
+rl_begin_undo_group
+()
. There should be one call to rl_end_undo_group()
+for each call to rl_begin_undo_group()
.
+0
if there was
+nothing to undo, non-zero if something was undone.
+
+
+Finally, if you neither insert nor delete text, but directly modify the
+existing text (e.g., change its case), call rl_modifying()
+once, just before you modify the text. You must supply the indices of
+the text range that you are going to modify.
+
[ < ] | +[ > ] | +[ << ] | +[ Up ] | +[ >> ] | +[Top] | +[Contents] | +[Index] | +[ ? ] | +
rl_line_buffer
.
+rl_outstream
.
+If Readline has not been set to display meta characters directly, this
+will convert meta characters to a meta-prefixed key sequence.
+This is intended for use by applications which wish to do their own
+redisplay.
+printf
,
+possibly containing conversion specifications such as `%d', and
+any additional arguments necessary to satisfy the conversion specifications.
+The resulting string is displayed in the echo area. The echo area
+is also used to display numeric arguments and search strings.
+rl_message()
.
+rl_save_prompt
.
+readline()
. It may also be called to
+expand the primary prompt if the rl_on_new_line_with_prompt()
+function or rl_already_prompted
variable is used.
+It returns the number of visible characters on the last line of the
+(possibly multi-line) prompt.
+rl_expand_prompt()
to expand the prompt and sets rl_prompt
+to the result.
+[ < ] | +[ > ] | +[ << ] | +[ Up ] | +[ >> ] | +[Top] | +[Contents] | +[Index] | +[ ? ] | +
rl_insert_text()
instead.
+[ < ] | +[ > ] | +[ << ] | +[ Up ] | +[ >> ] | +[Top] | +[Contents] | +[Index] | +[ ? ] | +
rl_stuff_char()
, macros, and characters read from the keyboard.
+While waiting for input, this function will call any function assigned to
+the rl_event_hook
variable.
+rl_read_key()
. Up to 512 characters may be pushed back.
+rl_stuff_char
returns 1 if the character was successfully inserted;
+0 otherwise.
+rl_read_key()
+is called. This sets rl_pending_input.
+rl_execute_next()
. This works only if the
+pending input has not already been read with rl_read_key()
.
+rl_read_key()
, Readline will
+wait for u microseconds for input before calling any function
+assigned to rl_event_hook
. The default waiting period is
+one-tenth of a second. Returns the old timeout value.
+[ < ] | +[ > ] | +[ << ] | +[ Up ] | +[ >> ] | +[Top] | +[Contents] | +[Index] | +[ ? ] | +
readline()
+can read a single character at a time from the keyboard.
+The meta_flag argument should be non-zero if Readline should
+read eight-bit input.
+rl_prep_terminal()
, leaving the terminal in
+the state in which it was before the most recent call to
+rl_prep_terminal()
.
+stty
) to their Readline equivalents. The bindings are performed
+in kmap.
+vt100
).
+If terminal_name is NULL
, the value of the TERM
+environment variable is used.
+[ < ] | +[ > ] | +[ << ] | +[ Up ] | +[ >> ] | +[Top] | +[Contents] | +[Index] | +[ ? ] | +
rl_line_buffer
with text.
+The point and mark are preserved, if possible.
+If clear_undo is non-zero, the undo list associated with the
+current line is cleared.
+rl_line_buffer
has enough space to hold len
+characters, possibly reallocating it if necessary.
+readline()
calls it before
+reading any input.
+bell-style
.
+matches
is the list
+of strings, in argv format, such as a list of completion matches.
+len
is the number of strings in matches
, and max
+is the length of the longest string in matches
. This function uses
+the setting of print-completions-horizontally
to select how the
+matches are displayed (see section 1.3.1 Readline Init File Syntax).
+
+
+The following are implemented as macros, defined in chardefs.h
.
+Applications should refrain from using them.
+
[ < ] | +[ > ] | +[ << ] | +[ Up ] | +[ >> ] | +[Top] | +[Contents] | +[Index] | +[ ? ] | +
rl_generic_bind()
instead.
+rl_outstream
.
+If readable is non-zero, the list is formatted in such a way
+that it can be made part of an inputrc
file and re-read.
+inputrc
+file (see section 1.3.1 Readline Init File Syntax).
+rl_outstream
.
+If readable is non-zero, the list is formatted in such a way
+that it can be made part of an inputrc
file and re-read.
+blink-matching-paren
has been enabled.
+[ < ] | +[ > ] | +[ << ] | +[ Up ] | +[ >> ] | +[Top] | +[Contents] | +[Index] | +[ ? ] | +
+
+An alternate interface is available to plain readline()
. Some
+applications need to interleave keyboard I/O with file, device, or
+window system I/O, typically by using a main loop to select()
+on various file descriptors. To accomodate this need, readline can
+also be invoked as a `callback' function from an event loop. There
+are functions available to make this easy.
+
rl_callback_read_char()
, which will read the next
+character from the current input source.
+If that character completes the line, rl_callback_read_char
will
+invoke the lhandler function saved by rl_callback_handler_install
+to process the line.
+Before calling the lhandler function, the terminal settings are
+reset to the values they had before calling
+rl_callback_handler_install
.
+If the lhandler function returns,
+the terminal settings are modified for Readline's use again.
+EOF
is indicated by calling lhandler with a
+NULL
line.
+rl_callback_handler_install
+does not exit the program, either this function or the function referred
+to by the value of rl_deprep_term_function
should be called before
+the program exits to reset the terminal settings.
+[ < ] | +[ > ] | +[ << ] | +[ Up ] | +[ >> ] | +[Top] | +[Contents] | +[Index] | +[ ? ] | +
+ +Here is a function which changes lowercase characters to their uppercase +equivalents, and uppercase characters to lowercase. If +this function was bound to `M-c', then typing `M-c' would +change the case of the character under point. Typing `M-1 0 M-c' +would change the case of the following 10 characters, leaving the cursor on +the last character changed. +
+ +
/* Invert the case of the COUNT following characters. */ +int +invert_case_line (count, key) + int count, key; +{ + register int start, end, i; + + start = rl_point; + + if (rl_point >= rl_end) + return (0); + + if (count < 0) + { + direction = -1; + count = -count; + } + else + direction = 1; + + /* Find the end of the range to modify. */ + end = start + (count * direction); + + /* Force it to be within range. */ + if (end > rl_end) + end = rl_end; + else if (end < 0) + end = 0; + + if (start == end) + return (0); + + if (start > end) + { + int temp = start; + start = end; + end = temp; + } + + /* Tell readline that we are modifying the line, + so it will save the undo information. */ + rl_modifying (start, end); + + for (i = start; i != end; i++) + { + if (_rl_uppercase_p (rl_line_buffer[i])) + rl_line_buffer[i] = _rl_to_lower (rl_line_buffer[i]); + else if (_rl_lowercase_p (rl_line_buffer[i])) + rl_line_buffer[i] = _rl_to_upper (rl_line_buffer[i]); + } + /* Move point to on top of the last character changed. */ + rl_point = (direction == 1) ? end - 1 : start; + return (0); +} + |
[ < ] | +[ > ] | +[ << ] | +[ Up ] | +[ >> ] | +[Top] | +[Contents] | +[Index] | +[ ? ] | +
+ +Signals are asynchronous events sent to a process by the Unix kernel, +sometimes on behalf of another process. They are intended to indicate +exceptional events, like a user pressing the interrupt key on his terminal, +or a network connection being broken. There is a class of signals that can +be sent to the process currently reading input from the keyboard. Since +Readline changes the terminal attributes when it is called, it needs to +perform special processing when such a signal is received in order to +restore the terminal to a sane state, or provide application writers with +functions to do so manually. +
+
+Readline contains an internal signal handler that is installed for a
+number of signals (SIGINT
, SIGQUIT
, SIGTERM
,
+SIGALRM
, SIGTSTP
, SIGTTIN
, and SIGTTOU
).
+When one of these signals is received, the signal handler
+will reset the terminal attributes to those that were in effect before
+readline()
was called, reset the signal handling to what it was
+before readline()
was called, and resend the signal to the calling
+application.
+If and when the calling application's signal handler returns, Readline
+will reinitialize the terminal and continue to accept input.
+When a SIGINT
is received, the Readline signal handler performs
+some additional work, which will cause any partially-entered line to be
+aborted (see the description of rl_free_line_state()
below).
+
+
+There is an additional Readline signal handler, for SIGWINCH
, which
+the kernel sends to a process whenever the terminal's size changes (for
+example, if a user resizes an xterm
). The Readline SIGWINCH
+handler updates Readline's internal screen size information, and then calls
+any SIGWINCH
signal handler the calling application has installed.
+Readline calls the application's SIGWINCH
signal handler without
+resetting the terminal to its original state. If the application's signal
+handler does more than update its idea of the terminal size and return (for
+example, a longjmp
back to a main processing loop), it must
+call rl_cleanup_after_signal()
(described below), to restore the
+terminal state.
+
+
+Readline provides two variables that allow application writers to
+control whether or not it will catch certain signals and act on them
+when they are received. It is important that applications change the
+values of these variables only when calling readline()
, not in
+a signal handler, so Readline's internal signal state is not corrupted.
+
SIGINT
, SIGQUIT
, SIGTERM
, SIGALRM
,
+SIGTSTP
, SIGTTIN
, and SIGTTOU
.
+
+
+The default value of rl_catch_signals
is 1.
+
SIGWINCH
.
+
+
+The default value of rl_catch_sigwinch
is 1.
+
+
+If an application does not wish to have Readline catch any signals, or
+to handle signals other than those Readline catches (SIGHUP
,
+for example),
+Readline provides convenience functions to do the necessary terminal
+and internal state cleanup upon receipt of a signal.
+
readline()
was called, and remove the Readline signal handlers for
+all signals, depending on the values of rl_catch_signals
and
+rl_catch_sigwinch
.
+rl_cleanup_after_signal()
. The
+Readline signal handler for SIGINT
calls this to abort the
+current input line.
+rl_catch_signals
and
+rl_catch_sigwinch
.
+
+
+If an application does not wish Readline to catch SIGWINCH
, it may
+call rl_resize_terminal()
or rl_set_screen_size()
to force
+Readline to update its idea of the terminal size when a SIGWINCH
+is received.
+
+
+If an application does not want to install a SIGWINCH
handler, but
+is still interested in the screen dimensions, Readline's idea of the screen
+size may be queried.
+
+ +The following functions install and remove Readline's signal handlers. +
SIGINT
, SIGQUIT
,
+SIGTERM
, SIGALRM
, SIGTSTP
, SIGTTIN
,
+SIGTTOU
, and SIGWINCH
, depending on the values of
+rl_catch_signals
and rl_catch_sigwinch
.
+rl_set_signals()
.
+[ < ] | +[ > ] | +[ << ] | +[ Up ] | +[ >> ] | +[Top] | +[Contents] | +[Index] | +[ ? ] | +
+ +Typically, a program that reads commands from the user has a way of +disambiguating commands and data. If your program is one of these, then +it can provide completion for commands, data, or both. +The following sections describe how your program and Readline +cooperate to provide this service. +
+ +
++
+ 2.6.1 How Completing Works The logic used to do completion. + 2.6.2 Completion Functions Functions provided by Readline. + 2.6.3 Completion Variables Variables which control completion. + 2.6.4 A Short Completion Example An example of writing completer subroutines.
[ < ] | +[ > ] | +[ << ] | +[ Up ] | +[ >> ] | +[Top] | +[Contents] | +[Index] | +[ ? ] | +
+ +In order to complete some text, the full list of possible completions +must be available. That is, it is not possible to accurately +expand a partial word without knowing all of the possible words +which make sense in that context. The Readline library provides +the user interface to completion, and two of the most common +completion functions: filename and username. For completing other types +of text, you must write your own completion function. This section +describes exactly what such functions must do, and provides an example. +
+ +There are three major functions used to perform completion: +
+ +
rl_complete()
. This function is
+called with the same arguments as other bindable Readline functions:
+count and invoking_key.
+It isolates the word to be completed and calls
+rl_completion_matches()
to generate a list of possible completions.
+It then either lists the possible completions, inserts the possible
+completions, or actually performs the
+completion, depending on which behavior is desired.
++ +
rl_completion_matches()
uses an
+application-supplied generator function to generate the list of
+possible matches, and then returns the array of these matches.
+The caller should place the address of its generator function in
+rl_completion_entry_function
.
++ +
rl_completion_matches()
, returning a string each time. The
+arguments to the generator function are text and state.
+text is the partial word to be completed. state is zero the
+first time the function is called, allowing the generator to perform
+any necessary initialization, and a positive non-zero integer for
+each subsequent call. The generator function returns
+(char *)NULL
to inform rl_completion_matches()
that there are
+no more possibilities left. Usually the generator function computes the
+list of possible completions when state is zero, and returns them
+one at a time on subsequent calls. Each string the generator function
+returns as a match must be allocated with malloc()
; Readline
+frees the strings when it has finished with them.
++ +
rl_completion_matches()
). The default is to do filename completion.
+rl_completion_matches()
.
+If the value of rl_completion_entry_function
is
+NULL
then the default filename generator
+function, rl_filename_completion_function()
, is used.
+[ < ] | +[ > ] | +[ << ] | +[ Up ] | +[ >> ] | +[Top] | +[Contents] | +[Index] | +[ ? ] | +
+ +Here is the complete list of callable completion functions present in +Readline. +
rl_completion_matches()
and rl_completion_entry_function
).
+The default is to do filename
+completion. This calls rl_complete_internal()
with an
+argument depending on invoking_key.
+rl_complete
+()
. This calls rl_complete_internal()
with an argument of
+`?'.
+rl_complete()
.
+This calls rl_complete_internal()
with an argument of `*'.
+rl_complete_internal()
+depending on whether cfunc was called twice in succession and
+the value of the show-all-if-ambiguous
variable.
+Application-specific completion functions may use this function to present
+the same interface as rl_complete()
.
+NULL
.
+The first entry in the returned array is the substitution for text.
+The remaining entries are the possible completions. The array is
+terminated with a NULL
pointer.
+
+
+entry_func is a function of two args, and returns a
+char *
. The first argument is text. The second is a
+state argument; it is zero on the first call, and non-zero on subsequent
+calls. entry_func returns a NULL
pointer to the caller
+when there are no more matches.
+
[ < ] | +[ > ] | +[ << ] | +[ Up ] | +[ >> ] | +[Top] | +[Contents] | +[Index] | +[ ? ] | +
rl_completion_matches()
.
+NULL
means to use rl_filename_completion_function()
, the default
+filename completer.
+rl_line_buffer
defining
+the boundaries of text, which is a character string.
+If this function exists and returns NULL
, or if this variable is
+set to NULL
, then rl_complete()
will call the value of
+rl_completion_entry_function
to generate matches, otherwise the
+array of strings returned will be used.
+If this function sets the rl_attempted_completion_over
+variable to a non-zero value, Readline will not perform its default
+completion even if this function returns no matches.
+rl_filename_quote_characters
+appears in a completed filename. The function is called with
+text, match_type, and quote_pointer. The text
+is the filename to be quoted. The match_type is either
+SINGLE_MATCH
, if there is only one completion match, or
+MULT_MATCH
. Some functions use this to decide whether or not to
+insert a closing quote character. The quote_pointer is a pointer
+to any opening quote character the user typed. Some functions choose
+to reset this character.
+rl_completer_word_break_characters
should be
+used to break words for the completer.
+NULL
terminated array of matches.
+The first element (matches[0]
) is the
+maximal substring common to all matches. This function can
+re-arrange the list of matches as required, but each element deleted
+from the array must be freed.
+char **
matches, int
num_matches, int
max_length)
+where matches is the array of matching strings,
+num_matches is the number of strings in that array, and
+max_length is the length of the longest string in that array.
+Readline provides a convenience function, rl_display_match_list
,
+that takes care of doing the display to Readline's output stream. That
+function may be called from this hook.
+" \t\n\"\\'`@$><=;|&{("
.
+rl_complete_internal()
. The default list is the value of
+rl_basic_word_break_characters
.
+rl_completer_word_break_characters
are treated as any other character,
+unless they also appear within this list.
+rl_filename_quote_characters
and rl_filename_quoting_desired
+is set to a non-zero value.
+rl_filename_quote_chars
. This is always non-zero
+on entry, and can only be changed within a completion entry generator
+function. The quoting is effected via a call to the function pointed to
+by rl_filename_quoting_function
.
+rl_attempted_completion_function
sets this variable to a non-zero
+value, Readline will not perform its default filename completion even
+if the application's completion function returns no matches.
+It should be set only by an application's completion function.
+rl_complete_internal()
+(see section 2.6.2 Completion Functions) for the list of characters.
+self-insert
.
+[ < ] | +[ > ] | +[ << ] | +[ Up ] | +[ >> ] | +[Top] | +[Contents] | +[Index] | +[ ? ] | +
+
+Here is a small application demonstrating the use of the GNU Readline
+library. It is called fileman
, and the source code resides in
+`examples/fileman.c'. This sample application provides
+completion of command names, line editing features, and access to the
+history list.
+
+ +
/* fileman.c -- A tiny application which demonstrates how to use the + GNU Readline library. This application interactively allows users + to manipulate files and their modes. */ + +#include <stdio.h> +#include <sys/types.h> +#include <sys/file.h> +#include <sys/stat.h> +#include <sys/errno.h> + +#include <readline/readline.h> +#include <readline/history.h> + +extern char *xmalloc (); + +/* The names of functions that actually do the manipulation. */ +int com_list __P((char *)); +int com_view __P((char *)); +int com_rename __P((char *)); +int com_stat __P((char *)); +int com_pwd __P((char *)); +int com_delete __P((char *)); +int com_help __P((char *)); +int com_cd __P((char *)); +int com_quit __P((char *)); + +/* A structure which contains information on the commands this program + can understand. */ + +typedef struct { + char *name; /* User printable name of the function. */ + rl_icpfunc_t *func; /* Function to call to do the job. */ + char *doc; /* Documentation for this function. */ +} COMMAND; + +COMMAND commands[] = { + { "cd", com_cd, "Change to directory DIR" }, + { "delete", com_delete, "Delete FILE" }, + { "help", com_help, "Display this text" }, + { "?", com_help, "Synonym for `help'" }, + { "list", com_list, "List files in DIR" }, + { "ls", com_list, "Synonym for `list'" }, + { "pwd", com_pwd, "Print the current working directory" }, + { "quit", com_quit, "Quit using Fileman" }, + { "rename", com_rename, "Rename FILE to NEWNAME" }, + { "stat", com_stat, "Print out statistics on FILE" }, + { "view", com_view, "View the contents of FILE" }, + { (char *)NULL, (rl_icpfunc_t *)NULL, (char *)NULL } +}; + +/* Forward declarations. */ +char *stripwhite (); +COMMAND *find_command (); + +/* The name of this program, as taken from argv[0]. */ +char *progname; + +/* When non-zero, this means the user is done using this program. */ +int done; + +char * +dupstr (s) + int s; +{ + char *r; + + r = xmalloc (strlen (s) + 1); + strcpy (r, s); + return (r); +} + +main (argc, argv) + int argc; + char **argv; +{ + char *line, *s; + + progname = argv[0]; + + initialize_readline (); /* Bind our completer. */ + + /* Loop reading and executing lines until the user quits. */ + for ( ; done == 0; ) + { + line = readline ("FileMan: "); + + if (!line) + break; + + /* Remove leading and trailing whitespace from the line. + Then, if there is anything left, add it to the history list + and execute it. */ + s = stripwhite (line); + + if (*s) + { + add_history (s); + execute_line (s); + } + + free (line); + } + exit (0); +} + +/* Execute a command line. */ +int +execute_line (line) + char *line; +{ + register int i; + COMMAND *command; + char *word; + + /* Isolate the command word. */ + i = 0; + while (line[i] && whitespace (line[i])) + i++; + word = line + i; + + while (line[i] && !whitespace (line[i])) + i++; + + if (line[i]) + line[i++] = '\0'; + + command = find_command (word); + + if (!command) + { + fprintf (stderr, "%s: No such command for FileMan.\n", word); + return (-1); + } + + /* Get argument to command, if any. */ + while (whitespace (line[i])) + i++; + + word = line + i; + + /* Call the function. */ + return ((*(command->func)) (word)); +} + +/* Look up NAME as the name of a command, and return a pointer to that + command. Return a NULL pointer if NAME isn't a command name. */ +COMMAND * +find_command (name) + char *name; +{ + register int i; + + for (i = 0; commands[i].name; i++) + if (strcmp (name, commands[i].name) == 0) + return (&commands[i]); + + return ((COMMAND *)NULL); +} + +/* Strip whitespace from the start and end of STRING. Return a pointer + into STRING. */ +char * +stripwhite (string) + char *string; +{ + register char *s, *t; + + for (s = string; whitespace (*s); s++) + ; + + if (*s == 0) + return (s); + + t = s + strlen (s) - 1; + while (t > s && whitespace (*t)) + t--; + *++t = '\0'; + + return s; +} + +/* **************************************************************** */ +/* */ +/* Interface to Readline Completion */ +/* */ +/* **************************************************************** */ + +char *command_generator __P((const char *, int)); +char **fileman_completion __P((const char *, int, int)); + +/* Tell the GNU Readline library how to complete. We want to try to + complete on command names if this is the first word in the line, or + on filenames if not. */ +initialize_readline () +{ + /* Allow conditional parsing of the ~/.inputrc file. */ + rl_readline_name = "FileMan"; + + /* Tell the completer that we want a crack first. */ + rl_attempted_completion_function = fileman_completion; +} + +/* Attempt to complete on the contents of TEXT. START and END + bound the region of rl_line_buffer that contains the word to + complete. TEXT is the word to complete. We can use the entire + contents of rl_line_buffer in case we want to do some simple + parsing. Returnthe array of matches, or NULL if there aren't any. */ +char ** +fileman_completion (text, start, end) + const char *text; + int start, end; +{ + char **matches; + + matches = (char **)NULL; + + /* If this word is at the start of the line, then it is a command + to complete. Otherwise it is the name of a file in the current + directory. */ + if (start == 0) + matches = rl_completion_matches (text, command_generator); + + return (matches); +} + +/* Generator function for command completion. STATE lets us + know whether to start from scratch; without any state + (i.e. STATE == 0), then we start at the top of the list. */ +char * +command_generator (text, state) + const char *text; + int state; +{ + static int list_index, len; + char *name; + + /* If this is a new word to complete, initialize now. This + includes saving the length of TEXT for efficiency, and + initializing the index variable to 0. */ + if (!state) + { + list_index = 0; + len = strlen (text); + } + + /* Return the next name which partially matches from the + command list. */ + while (name = commands[list_index].name) + { + list_index++; + + if (strncmp (name, text, len) == 0) + return (dupstr(name)); + } + + /* If no names matched, then return NULL. */ + return ((char *)NULL); +} + +/* **************************************************************** */ +/* */ +/* FileMan Commands */ +/* */ +/* **************************************************************** */ + +/* String to pass to system (). This is for the LIST, VIEW and RENAME + commands. */ +static char syscom[1024]; + +/* List the file(s) named in arg. */ +com_list (arg) + char *arg; +{ + if (!arg) + arg = ""; + + sprintf (syscom, "ls -FClg %s", arg); + return (system (syscom)); +} + +com_view (arg) + char *arg; +{ + if (!valid_argument ("view", arg)) + return 1; + + sprintf (syscom, "more %s", arg); + return (system (syscom)); +} + +com_rename (arg) + char *arg; +{ + too_dangerous ("rename"); + return (1); +} + +com_stat (arg) + char *arg; +{ + struct stat finfo; + + if (!valid_argument ("stat", arg)) + return (1); + + if (stat (arg, &finfo) == -1) + { + perror (arg); + return (1); + } + + printf ("Statistics for `%s':\n", arg); + + printf ("%s has %d link%s, and is %d byte%s in length.\n", arg, + finfo.st_nlink, + (finfo.st_nlink == 1) ? "" : "s", + finfo.st_size, + (finfo.st_size == 1) ? "" : "s"); + printf ("Inode Last Change at: %s", ctime (&finfo.st_ctime)); + printf (" Last access at: %s", ctime (&finfo.st_atime)); + printf (" Last modified at: %s", ctime (&finfo.st_mtime)); + return (0); +} + +com_delete (arg) + char *arg; +{ + too_dangerous ("delete"); + return (1); +} + +/* Print out help for ARG, or for all of the commands if ARG is + not present. */ +com_help (arg) + char *arg; +{ + register int i; + int printed = 0; + + for (i = 0; commands[i].name; i++) + { + if (!*arg || (strcmp (arg, commands[i].name) == 0)) + { + printf ("%s\t\t%s.\n", commands[i].name, commands[i].doc); + printed++; + } + } + + if (!printed) + { + printf ("No commands match `%s'. Possibilties are:\n", arg); + + for (i = 0; commands[i].name; i++) + { + /* Print in six columns. */ + if (printed == 6) + { + printed = 0; + printf ("\n"); + } + + printf ("%s\t", commands[i].name); + printed++; + } + + if (printed) + printf ("\n"); + } + return (0); +} + +/* Change to the directory ARG. */ +com_cd (arg) + char *arg; +{ + if (chdir (arg) == -1) + { + perror (arg); + return 1; + } + + com_pwd (""); + return (0); +} + +/* Print out the current working directory. */ +com_pwd (ignore) + char *ignore; +{ + char dir[1024], *s; + + s = getcwd (dir, sizeof(dir) - 1); + if (s == 0) + { + printf ("Error getting pwd: %s\n", dir); + return 1; + } + + printf ("Current directory is %s\n", dir); + return 0; +} + +/* The user wishes to quit using this program. Just set DONE + non-zero. */ +com_quit (arg) + char *arg; +{ + done = 1; + return (0); +} + +/* Function which tells you that you can't do this. */ +too_dangerous (caller) + char *caller; +{ + fprintf (stderr, + "%s: Too dangerous for me to distribute.\n" + caller); + fprintf (stderr, "Write it yourself.\n"); +} + +/* Return non-zero if ARG is a valid argument for CALLER, + else print an error message and return zero. */ +int +valid_argument (caller, arg) + char *caller, *arg; +{ + if (!arg || !*arg) + { + fprintf (stderr, "%s: Argument required.\n", caller); + return (0); + } + + return (1); +} + |
[ < ] | +[ > ] | +[ << ] | +[ Up ] | +[ >> ] | +[Top] | +[Contents] | +[Index] | +[ ? ] | +
Jump to: | C + +E + +I + +K + +N + +R + +V + +Y + + |
---|
Jump to: | C + +E + +I + +K + +N + +R + +V + +Y + + |
---|
[ < ] | +[ > ] | +[ << ] | +[ Up ] | +[ >> ] | +[Top] | +[Contents] | +[Index] | +[ ? ] | +
Jump to: | _
+
+ +A + +B + +C + +D + +E + +F + +H + +I + +K + +M + +N + +O + +P + +Q + +R + +S + +T + +U + +V + +Y + + |
---|
Jump to: | _
+
+ +A + +B + +C + +D + +E + +F + +H + +I + +K + +M + +N + +O + +P + +Q + +R + +S + +T + +U + +V + +Y + + |
---|
+ +
[Top] | +[Contents] | +[Index] | +[ ? ] | +
[Top] | +[Contents] | +[Index] | +[ ? ] | +
+1. Command Line Editing ++
+2. Programming with GNU Readline +
+Concept Index +
+Function and Variable Index +
+ +
[Top] | +[Contents] | +[Index] | +[ ? ] | +
Button | +Name | +Go to | +From 1.2.3 go to | +
---|---|---|---|
+ [ < ] | ++Back + | ++previous section in reading order + | ++1.2.2 + | +
+ [ > ] | ++Forward + | ++next section in reading order + | ++1.2.4 + | +
+ [ << ] | ++FastBack + | ++previous or up-and-previous section + | ++1.1 + | +
+ [ Up ] | ++Up + | ++up section + | ++1.2 + | +
+ [ >> ] | ++FastForward + | ++next or up-and-next section + | ++1.3 + | +
+ [Top] | ++Top + | ++cover (top) of document + | ++ + | +
+ [Contents] | ++Contents + | ++table of contents + | ++ + | +
+ [Index] | ++Index + | ++concept index + | ++ + | +
+ [ ? ] | ++About + | ++this page + | ++ + | +