1 |
.TH EDITLINE 3 |
2 |
.SH NAME |
3 |
editline \- command-line editing library with history |
4 |
.SH SYNOPSIS |
5 |
.nf |
6 |
.B "char *" |
7 |
.B "readline(prompt)" |
8 |
.B " char *prompt;" |
9 |
|
10 |
.B "void" |
11 |
.B "add_history(line)" |
12 |
.B " char *line;" |
13 |
.fi |
14 |
.SH DESCRIPTION |
15 |
.I Editline |
16 |
is a library that provides an line-editing interface with text recall. |
17 |
It is intended to be compatible with the |
18 |
.I readline |
19 |
library provided by the Free Software Foundation, but much smaller. |
20 |
The bulk of this manual page describes the user interface. |
21 |
.PP |
22 |
The |
23 |
.I readline |
24 |
routine returns a line of text with the trailing newline removed. |
25 |
The data is returned in a buffer allocated with |
26 |
.IR malloc (3), |
27 |
so the space should be released with |
28 |
.IR free (3) |
29 |
when the calling program is done with it. |
30 |
Before accepting input from the user, the specified |
31 |
.I prompt |
32 |
is displayed on the terminal. |
33 |
.PP |
34 |
The |
35 |
.I add_history |
36 |
routine makes a copy of the specified |
37 |
.I line |
38 |
and adds it to the internal history list. |
39 |
.SS "User Interface" |
40 |
A program that uses this library provides a simple emacs-like editing |
41 |
interface to its users. |
42 |
A line may be edited before it is sent to the calling program by typing either |
43 |
control characters or escape sequences. |
44 |
A control character, shown as a caret followed by a letter, is typed by |
45 |
holding down the ``control'' key while the letter is typed. |
46 |
For example, ``^A'' is a control-A. |
47 |
An escape sequence is entered by typing the ``escape'' key followed by one or |
48 |
more characters. |
49 |
The escape key is abbreviated as ``ESC.'' |
50 |
Note that unlike control keys, case matters in escape sequences; ``ESC\ F'' |
51 |
is not the same as ``ESC\ f''. |
52 |
.PP |
53 |
An editing command may be typed anywhere on the line, not just at the |
54 |
beginning. |
55 |
In addition, a return may also be typed anywhere on the line, not just at |
56 |
the end. |
57 |
.PP |
58 |
Most editing commands may be given a repeat count, |
59 |
.IR n , |
60 |
where |
61 |
.I n |
62 |
is a number. |
63 |
To enter a repeat count, type the escape key, the number, and then |
64 |
the command to execute. |
65 |
For example, ``ESC\ 4\ ^f'' moves forward four characters. |
66 |
If a command may be given a repeat count then the text ``[n]'' is given at the |
67 |
end of its description. |
68 |
.PP |
69 |
The following control characters are accepted: |
70 |
.RS |
71 |
.nf |
72 |
.ta \w'ESC DEL 'u |
73 |
^A Move to the beginning of the line |
74 |
^B Move left (backwards) [n] |
75 |
^D Delete character [n] |
76 |
^E Move to end of line |
77 |
^F Move right (forwards) [n] |
78 |
^G Ring the bell |
79 |
^H Delete character before cursor (backspace key) [n] |
80 |
^I Complete filename (tab key); see below |
81 |
^J Done with line (return key) |
82 |
^K Kill to end of line (or column [n]) |
83 |
^L Redisplay line |
84 |
^M Done with line (alternate return key) |
85 |
^N Get next line from history [n] |
86 |
^P Get previous line from history [n] |
87 |
^R Search backward (forward if [n]) through history for text; |
88 |
\& must start line if text begins with an uparrow |
89 |
^T Transpose characters |
90 |
^V Insert next character, even if it is an edit command |
91 |
^W Wipe to the mark |
92 |
^X^X Exchange current location and mark |
93 |
^Y Yank back last killed text |
94 |
^[ Start an escape sequence (escape key) |
95 |
^]c Move forward to next character ``c'' |
96 |
^? Delete character before cursor (delete key) [n] |
97 |
.fi |
98 |
.RE |
99 |
.PP |
100 |
The following escape sequences are provided. |
101 |
.RS |
102 |
.nf |
103 |
.ta \w'ESC DEL 'u |
104 |
ESC\ ^H Delete previous word (backspace key) [n] |
105 |
ESC\ DEL Delete previous word (delete key) [n] |
106 |
ESC\ SP Set the mark (space key); see ^X^X and ^Y above |
107 |
ESC\ \. Get the last (or [n]'th) word from previous line |
108 |
ESC\ \? Show possible completions; see below |
109 |
ESC\ < Move to start of history |
110 |
ESC\ > Move to end of history |
111 |
ESC\ b Move backward a word [n] |
112 |
ESC\ d Delete word under cursor [n] |
113 |
ESC\ f Move forward a word [n] |
114 |
ESC\ l Make word lowercase [n] |
115 |
ESC\ m Toggle if 8bit chars display normally or with ``M\-'' prefix |
116 |
ESC\ u Make word uppercase [n] |
117 |
ESC\ y Yank back last killed text |
118 |
ESC\ v Show library version |
119 |
ESC\ w Make area up to mark yankable |
120 |
ESC\ nn Set repeat count to the number nn |
121 |
ESC\ C Read from environment variable ``_C_'', where C is |
122 |
\& an uppercase letter |
123 |
.fi |
124 |
.RE |
125 |
.PP |
126 |
The |
127 |
.I editline |
128 |
library has a small macro facility. |
129 |
If you type the escape key followed by an uppercase letter, |
130 |
.IR C , |
131 |
then the contents of the environment variable |
132 |
.I _C_ |
133 |
are read in as if you had typed them at the keyboard. |
134 |
For example, if the variable |
135 |
.I _L_ |
136 |
contains the following: |
137 |
.RS |
138 |
^A^Kecho '^V^[[H^V^[[2J'^M |
139 |
.RE |
140 |
Then typing ``ESC L'' will move to the beginning of the line, kill the |
141 |
entire line, enter the echo command needed to clear the terminal (if your |
142 |
terminal is like a VT-100), and send the line back to the shell. |
143 |
.PP |
144 |
The |
145 |
.I editline |
146 |
library also does filename completion. |
147 |
Suppose the root directory has the following files in it: |
148 |
.RS |
149 |
.nf |
150 |
.ta \w'core 'u |
151 |
bin vmunix |
152 |
core vmunix.old |
153 |
.fi |
154 |
.RE |
155 |
If you type ``rm\ /v'' and then the tab key. |
156 |
.I Editline |
157 |
will then finish off as much of the name as possible by adding ``munix''. |
158 |
Because the name is not unique, it will then beep. |
159 |
If you type the escape key and a question mark, it will display the |
160 |
two choices. |
161 |
If you then type a period and a tab, the library will finish off the filename |
162 |
for you: |
163 |
.RS |
164 |
.nf |
165 |
.RI "rm /v[TAB]" munix .TAB old |
166 |
.fi |
167 |
.RE |
168 |
The tab key is shown by ``[TAB]'' and the automatically-entered text |
169 |
is shown in italics. |
170 |
.SH "BUGS AND LIMITATIONS" |
171 |
Cannot handle lines more than 80 columns. |
172 |
.SH AUTHORS |
173 |
Simmule R. Turner <uunet.uu.net!capitol!sysgo!simmy> |
174 |
and Rich $alz <rsalz@osf.org>. |
175 |
Original manual page by DaviD W. Sanderson <dws@ssec.wisc.edu>. |