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