OpenCores
URL https://opencores.org/ocsvn/eco32/eco32/trunk

Subversion Repositories eco32

[/] [eco32/] [trunk/] [sim/] [getline/] [getline.3] - Blame information for rev 257

Go to most recent revision | Details | Compare with Previous | View Log

Line No. Rev Author Line
1 8 hellwig
.\" Note that in silly ol' [nt]roff, even trailing white space is
2
.\" significant.  I went through and eliminated it.
3
.\" I adopted a convention of using a bold 'getline' when referring to
4
.\" the whole package, but an italic 'getline' when referring to the
5
.\" specific function.
6
.\" Note that in [nt]roff that "-" is a hyphen, while "\-" is a dash.
7
.\" I adjusted some source text lines to keep them short (I keep line
8
.\" numbers turned on in vi, so I only have 72 cols w/o wrapping).
9
.\" It's too bad that getline() doesn't realloc() the buffer as
10
.\" necessary.  Then it could have an unlimited input line length.
11
.\" Note that .RI et al are limited in how many args they can take.
12
.\" I corrected gl_addhist to gl_histadd, which is what is actually
13
.\" used!  Perhaps it really should be gl_addhist, to preserve the
14
.\" gl_ pattern in the other function names.
15
.\" I tried to rephrase certain sections to avoid the passive voice.
16
.\" I find the active voice much easier to understand, since I can tell
17
.\" more easily what acts on what.
18
.TH GETLINE 3
19
.SH NAME
20
getline \- command-line editing library with history
21
.SH SYNOPSIS
22
.RI "char *gl_getline(char *" prompt );
23
.PP
24
.RI "void gl_histadd(char *" line );
25
.br
26
.RI "void gl_setwidth(int " width );
27
.br
28
.RI "void gl_strwidth(int " (*width_func)() );
29
.PP
30
.RI "extern int (*gl_in_hook)(char *" buf );
31
.br
32
.RI "extern int (*gl_out_hook)(char *" buf );
33
.br
34
.RI "extern int (*gl_tab_hook)(char *" buf ,
35
.RI "int " prompt_width ", int *" cursor_loc );
36
.SH DESCRIPTION
37
The
38
.B getline
39
package is a set of library routines that implement
40
an editable command-line history.
41
.PP
42
.B "Programming Interface"
43
.br
44
.I getline
45
returns a pointer to a line of text read from the user,
46
prompting the user with the specified
47
.IR prompt .
48
The pointer refers to a static buffer allocated by the
49
.B getline
50
package.
51
Clients may assume that the pointer
52
.I getline
53
returns is always the same, and is never NULL.
54
The buffer
55
.I getline
56
returns to the caller contains the terminating newline character,
57
except on end of file,
58
in which case the first character in the buffer is 0
59
.RB ( NUL ).
60
File descriptors 0 and 1 must be connected to the terminal
61
(not redirected),
62
so the caller should check for this condition (using
63
.IR isatty (\|))
64
and call stdio routines if the session is not interactive.
65
.PP
66
.I gl_histadd
67
adds the given
68
.I line
69
to the
70
.B getline
71
history list if the
72
.I line
73
is not empty and if it is different from the last line
74
in the history list
75
(so the caller need not check for these conditions).
76
.I gl_histadd
77
makes its own copies of all the lines it adds to the history list.
78
This is so the caller can reuse the buffer it supplies to
79
.IR gl_histadd .
80
.PP
81
.I gl_setwidth
82
specifies the terminal
83
.I width
84
to use for horizontal scrolling.
85
The default value is 80 columns,
86
and it is important to properly specify the
87
.I width
88
or lines may wrap inadvertently.
89
.PP
90
.I gl_strwidth
91
allows the application program to supply a prompt string width calculation
92
function that returns the number of screen positions used by the argument
93
string.
94
By default strlen is used, but if the prompt contains escape sequences the user
95
can bind a function that returns the actual number of screen postitions
96
used by the argument string, not including the escape characters.
97
.PP
98
In addition to the function call interface,
99
.B getline
100
has three externally accessible function pointers
101
that act as hooks if bound to user-defined functions.
102
.B getline
103
supplies each of the functions with a pointer to the current buffer
104
as the first argument,
105
and expects the return value to be the index
106
of the first change the function made in the buffer
107
(or \-1 if the function did not alter the buffer).
108
After the functions return,
109
.B getline
110
updates the screen as necessary.
111
.\"-------
112
.\" DWS comment --
113
.\"-------
114
Note that the functions may not alter the size of the buffer.
115
Indeed, they do not even know how large the buffer is!
116
.PP
117
.I getline
118
calls
119
.I gl_in_hook
120
(initially NULL)
121
each time it loads a new buffer.
122
More precisely, this is
123
.TP
124
\(bu
125
at the first call to
126
.I getline
127
(with an empty buffer)
128
.TP
129
\(bu
130
each time the user enters a new buffer from the history list (with
131
.B ^P
132
or
133
.BR ^N )
134
.TP
135
\(bu
136
when the user accepts an incremental search string
137
(when the user terminates the search).
138
.PP
139
.I getline
140
calls
141
.I gl_out_hook
142
(initially NULL)
143
when a line has been completed by the user entering a
144
.B NEWLINE
145
.RB (\| ^J \|)
146
or
147
.B RETURN
148
.RB (\| ^M \|).
149
The buffer
150
.I gl_out_hook
151
sees does not yet have the newline appended, and
152
.I gl_out_hook
153
should not add a newline.
154
.PP
155
.I getline
156
calls
157
.I gl_tab_hook
158
whenever the user types a
159
.BR TAB .
160
In addition to the buffer,
161
.I getline
162
supplies the current
163
.I prompt_width
164
(presumably needed for tabbing calculations) and
165
.IR cursor_loc ,
166
a pointer to the cursor location.
167
.RI ( *cursor_loc
168
\(eq 0 corresponds to the first character in the buffer)
169
.I *cursor_loc
170
tells
171
.I gl_tab_hook
172
where the
173
.B TAB
174
was typed.
175
Note that when it redraws the screen,
176
.I getline
177
will honor any change
178
.I gl_tab_hook
179
may make to
180
.IR *cursor_loc .
181
.\"-------
182
.\" DWS comment --
183
.\"-------
184
Note also that
185
.I prompt_width
186
may not correspond to the actual width of
187
.I prompt
188
on the screen if
189
.I prompt
190
contains escape sequences.
191
.I gl_tab_hook
192
is initially bound to the
193
.B getline
194
internal static function
195
.IR gl_tab ,
196
which acts like a normal
197
.B TAB
198
key by inserting spaces.
199
.PP
200
.B "User Interface"
201
.br
202
.\"-------
203
.\" I adapted the prologue to this section from the ksh man page (dws).
204
.\"-------
205
To edit, the user moves the cursor to the point needing correction and
206
then inserts or deletes characters or words as needed.
207
All the editing commands are control characters,
208
which typed by holding the
209
CTRL key down while typing another character.
210
Control characters are indicated below as the caret
211
.RB (\| ^ \|)
212
followed by another character,
213
such as
214
.BR ^A .
215
.PP
216
All edit commands operate from any place on the line,
217
not just at the beginning.
218
.PP
219
These are the
220
.I getline
221
key bindings.
222
.\"-------
223
.\" Tt  - max width of tag
224
.\" Tw  - max width of tag + spacing to the paragraph
225
.\" Tp  - special .TP, with the best indent for the editing command
226
.\"     descriptions.
227
.\"     The first version of Tp prints the tags left-justified.
228
.\"     The second version of Tp prints the tags as follows:
229
.\"     If one argument is given, it is printed right-justified.
230
.\"     If two arguments are given, the first is printed left-justified
231
.\"     and the second is printed right-justified.
232
.\"-------
233
.nr Tt \w'BACKSPACE'
234
.nr Tw \w'BACKSPACE\0\0\0'
235
.\" .de Tp
236
.\" .TP \n(Twu
237
.\" \fB\\$1\fR
238
.\" ..
239
.de Tp
240
.TP \n(Twu
241
.if \\n(.$=1 \h@\n(Ttu-\w'\fB\\$1\fR'u@\fB\\$1\fR
242
.if \\n(.$=2 \fB\\$1\fR\h@\n(Ttu-\w'\fB\\$1\\$2\fR'u@\fB\\$2\fR
243
..
244
.PP
245
.\"-------
246
.\" Set interparagraph spacing to zero so binding descriptions are
247
.\" kept together.
248
.\"-------
249
.PD 0
250
.Tp "^A"
251
Move cursor to beginning of line.
252
.Tp "^B"
253
Move cursor left (back) 1 column.
254
.Tp ESC-B
255
Move cursor back one word.
256
.Tp "^D"
257
Delete the character under the cursor.
258
.Tp "^E"
259
Move cursor to end of line.
260
.Tp "^F"
261
Move cursor right (forward) 1 column.
262
.Tp ESC-F
263
Move cursor forward one word.
264
.Tp "^H"
265
Delete the character left of the cursor.@
266
.Tp "^I"
267
Jump to next tab stop (may be redefined by the program).
268
.Tp "^J"
269
Return the current line.
270
.Tp "^K"
271
Kill from cursor to the end of the line (see
272
.BR "^Y" \|).
273
.Tp "^L"
274
Redisplay current line.
275
.Tp "^M"
276
Return the current line.
277
.Tp "^N"
278
Fetches next line from the history list.
279
.Tp "^O"
280
Toggle overwrite/insert mode, initially in insert mode.
281
.Tp "^P"
282
Fetches previous line from the history list.
283
.Tp "^R"
284
Begin a reverse incremental search through history list.
285
Each printing character typed adds to the search substring
286
(initially empty), and
287
.B getline
288
finds and displays the first matching location.
289
Typing
290
.B ^R
291
again marks the current starting location and begins a new
292
search for the current substring.
293
Typing
294
.B ^H
295
or
296
.B DEL
297
deletes the last character from the search string,
298
and
299
.B getline
300
restarts the search from the last starting location.
301
Repeated
302
.B ^H
303
or
304
.B DEL
305
characters therefore appear to unwind the search to the match nearest
306
the point where the user last typed
307
.B ^R
308
or
309
.BR ^S .
310
Typing
311
.B ^H
312
or
313
.B DEL
314
until the search string is empty causes
315
.B getline
316
to reset the start of the search to the beginning of the history list.
317
Typing
318
.B ESC
319
or any other editing character accepts the current match
320
and terminates the search.
321
.Tp "^S"
322
Begin a forward incremental search through the history list.
323
The behavior is like that of
324
.B ^R
325
but in the opposite direction through the history list.
326
.Tp "^T"
327
Transpose current and previous character.
328
.Tp "^U"
329
Kill the entire line (see
330
.BR "^Y" \|).
331
.Tp "^Y"
332
Yank previously killed text back at current location.
333
.Tp BACKSPACE
334
Delete the character left of the cursor.
335
.Tp DEL
336
Delete the character left of the cursor.
337
.Tp RETURN
338
Return the current line.
339
.Tp TAB
340
Jump to next tab stop (may be redefined by the program).
341
.\"-------
342
.\" Restore default interparagraph spacing.
343
.\"-------
344
.PD
345
.PP
346
.B getline
347
recognizes DOS and ANSI arrow keys.
348
They cause the following actions:
349
.B up
350
is the same as
351
.BR ^P ,
352
.B down
353
is the same as
354
.BR ^N ,
355
.B left
356
is the same as
357
.BR ^P ,
358
and
359
.B right
360
is the same as
361
.BR ^F .
362
.SH AUTHORS
363
.PP
364
Program by
365
Christopher R. Thewalt (thewalt\|@ce.berkeley.edu)
366
.PP
367
Original man page by
368
DaviD W. Sanderson (dws\|@cs.wisc.edu)
369
and Christopher R. Thewalt
370
.SH COPYRIGHT
371
\&
372
.br
373
.if n (C)
374
.if t \s+8\v'+2p'\fB\(co\fR\v'-2p'\s0
375
\s+2Copyright 1992,1993 by Christopher R. Thewalt and DaviD W. Sanderson\s0
376
(but freely redistributable)

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.