1689b278aa5e918df4d1d58df6947bf6a33ee987
[dragonfly.git] / lib / libedit / editline.3
1 .\"     $NetBSD: editline.3,v 1.4 1997/01/14 04:17:23 lukem Exp $
2 .\"
3 .\" Copyright (c) 1997 The NetBSD Foundation, Inc.
4 .\" All rights reserved.
5 .\"
6 .\" This file was contributed to The NetBSD Foundation by Luke Mewburn.
7 .\"
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
10 .\" are met:
11 .\" 1. Redistributions of source code must retain the above copyright
12 .\"    notice, this list of conditions and the following disclaimer.
13 .\" 2. Redistributions in binary form must reproduce the above copyright
14 .\"    notice, this list of conditions and the following disclaimer in the
15 .\"    documentation and/or other materials provided with the distribution.
16 .\" 3. All advertising materials mentioning features or use of this software
17 .\"    must display the following acknowledgement:
18 .\"        This product includes software developed by the NetBSD
19 .\"        Foundation, Inc. and its contributors.
20 .\" 4. Neither the name of The NetBSD Foundation nor the names of its
21 .\"    contributors may be used to endorse or promote products derived
22 .\"    from this software without specific prior written permission.
23 .\"
24 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
25 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
26 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
27 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE
28 .\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
29 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
30 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
31 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
32 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
33 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
34 .\" POSSIBILITY OF SUCH DAMAGE.
35 .\"
36 .\" $FreeBSD: src/lib/libedit/editline.3,v 1.8.2.7 2001/12/17 10:08:30 ru Exp $
37 .\" $DragonFly: src/lib/libedit/editline.3,v 1.2 2003/06/17 04:26:49 dillon Exp $
38 .\"
39 .Dd January 11, 1997
40 .Os
41 .Dt EDITLINE 3
42 .Sh NAME
43 .Nm editline ,
44 .Nm el_init ,
45 .Nm el_end ,
46 .Nm el_reset ,
47 .Nm el_gets ,
48 .Nm el_getc ,
49 .Nm el_push ,
50 .Nm el_parse ,
51 .Nm el_set ,
52 .Nm el_source ,
53 .Nm el_resize ,
54 .Nm el_line ,
55 .Nm el_insertstr ,
56 .Nm el_deletestr ,
57 .Nm el_data_set ,
58 .Nm el_data_get ,
59 .Nm history_init ,
60 .Nm history_end ,
61 .Nm history
62 .Nd line editor and history functions
63 .Sh LIBRARY
64 .Lb libedit
65 .Sh SYNOPSIS
66 .In histedit.h
67 .Ft EditLine *
68 .Fn el_init "const char *prog" "FILE *fin" "FILE *fout"
69 .Ft void
70 .Fn el_end "EditLine *e"
71 .Ft void
72 .Fn el_reset "EditLine *e"
73 .Ft const char *
74 .Fn el_gets "EditLine *e" "int *count"
75 .Ft int
76 .Fn el_getc "EditLine *e" "char *ch"
77 .Ft void
78 .Fn el_push "EditLine *e" "const char *str"
79 .Ft int
80 .Fn el_parse "EditLine *e" "int argc" "char *argv[]"
81 .Ft int
82 .Fn el_set "EditLine *e" "int op" "..."
83 .Ft int
84 .Fn el_source "EditLine *e" "const char *file"
85 .Ft void
86 .Fn el_resize "EditLine *e"
87 .Ft const LineInfo *
88 .Fn el_line "EditLine *e"
89 .Ft int
90 .Fn el_insertstr "EditLine *e" "char *str"
91 .Ft void
92 .Fn el_deletestr "EditLine *e" "int count"
93 .Ft void
94 .Fn el_data_set "EditLine *e" "void *data"
95 .Ft void *
96 .Fn el_data_get "EditLine *e"
97 .Ft History *
98 .Fn history_init
99 .Ft void
100 .Fn history_end "History *h"
101 .Ft const HistEvent *
102 .Fn history "History *h" "int op" "..."
103 .Sh DESCRIPTION
104 The
105 .Nm
106 library provides generic line editing and history functions,
107 similar to those found in
108 .Xr sh 1 .
109 .Pp
110 These functions are available in the
111 .Nm libedit
112 library (which needs the
113 .Nm libtermcap
114 library).
115 Programs should be linked with
116 .Fl ledit ltermcap .
117 .Sh LINE EDITING FUNCTIONS
118 The line editing functions use a common data structure,
119 .Fa EditLine ,
120 which is created by
121 .Fn el_init
122 and freed by
123 .Fn el_end .
124 .Pp
125 The following functions are available:
126 .Bl -tag -width 4n
127 .It Fn el_init
128 Initialise the line editor, and return a data structure
129 to be used by all other line editing functions.
130 .Fa prog
131 is the name of the invoking program, used when reading the
132 .Xr editrc 5
133 file to determine which settings to use.
134 .Fa fin
135 and
136 .Fa fout
137 are the input and output streams (respectively) to use.
138 In this documentation, references to
139 .Dq the tty
140 are actually to this input/output stream combination.
141 .It Fn el_end
142 Clean up and finish with
143 .Fa e ,
144 assumed to have been created with
145 .Fn el_init .
146 .It Fn el_reset
147 Reset the tty and the parser.
148 This should be called after an error which may have upset the tty's
149 state.
150 .It Fn el_gets
151 Read a line from the tty.
152 .Fa count
153 is modified to contain the number of characters read.
154 Returns the line read if successful, or
155 .Dv NULL
156 if no characters were read or if an error occurred.
157 .It Fn el_getc
158 Read a character from the tty.
159 .Fa ch
160 is modified to contain the character read.
161 Returns the number of characters read if successful, -1 otherwise.
162 .It Fn el_push
163 Pushes
164 .Fa str
165 back onto the input stream.
166 This is used by the macro expansion mechanism.
167 Refer to the description of
168 .Ic bind
169 .Fl s
170 in
171 .Xr editrc 5
172 for more information.
173 .It Fn el_parse
174 Parses the
175 .Fa argv
176 array (which is
177 .Fa argc
178 elements in size)
179 to execute builtin
180 .Nm
181 commands.
182 If the command is prefixed with
183 .Dq prog:
184 then
185 .Fn el_parse
186 will only execute the command if
187 .Dq prog
188 matches the
189 .Fa prog
190 argument supplied to
191 .Fn el_init .
192 The return value is
193 -1 if the command is unknown,
194 0 if there was no error or
195 .Dq prog
196 didn't match, or
197 1 if the command returned an error.
198 Refer to
199 .Xr editrc 5
200 for more information.
201 .Pp
202 .Em NOTE :
203 .Va argv[0]
204 may be modified by
205 .Fn el_parse .
206 The colon between
207 .Dq prog
208 and the command,
209 .Ar command ,
210 will be replaced with a NUL
211 .Pq Dq \e0 .
212 .It Fn el_set
213 Set
214 .Nm
215 parameters.
216 .Fa op
217 determines which parameter to set, and each operation has its
218 own parameter list.
219 .Pp
220 The following values for
221 .Fa op
222 are supported, along with the required argument list:
223 .Bl -tag -width 4n
224 .It Dv EL_PROMPT , Fa "char *(*f)(EditLine *)"
225 Define prompt printing function as
226 .Fa f ,
227 which is to return a string that contains the prompt.
228 .It Dv EL_TERMINAL , Fa "const char *type"
229 Define terminal type of the tty to be
230 .Fa type ,
231 or to
232 .Ev TERM
233 if
234 .Fa type
235 is
236 .Dv NULL .
237 .It Dv EL_EDITOR , Fa "const char *mode"
238 Set editing mode to
239 .Fa mode ,
240 which must be one of
241 .Dq emacs
242 or
243 .Dq vi .
244 .It Dv EL_SIGNAL , Fa "int flag"
245 If
246 .Fa flag
247 is non-zero,
248 .Nm
249 will install its own signal handler for the following signals when
250 reading command input:
251 .Dv SIGCONT ,
252 .Dv SIGHUP ,
253 .Dv SIGINT ,
254 .Dv SIGQUIT ,
255 .Dv SIGSTOP ,
256 .Dv SIGTERM ,
257 .Dv SIGTSTP ,
258 and
259 .Dv SIGWINCH .
260 Otherwise, the current signal handlers will be used.
261 .It Dv EL_BIND , Xo
262 .Fa "const char *" ,
263 .Fa "..." ,
264 .Dv NULL
265 .Xc
266 Perform the
267 .Ic bind
268 builtin command.
269 Refer to
270 .Xr editrc 5
271 for more information.
272 .It Dv EL_ECHOTC , Xo
273 .Fa "const char *" ,
274 .Fa "..." ,
275 .Dv NULL
276 .Xc
277 Perform the
278 .Ic echotc
279 builtin command.
280 Refer to
281 .Xr editrc 5
282 for more information.
283 .It Dv EL_SETTC , Xo
284 .Fa "const char *" ,
285 .Fa "..." ,
286 .Dv NULL
287 .Xc
288 Perform the
289 .Ic settc
290 builtin command.
291 Refer to
292 .Xr editrc 5
293 for more information.
294 .It Dv EL_SETTY , Xo
295 .Fa "const char *" ,
296 .Fa "..." ,
297 .Dv NULL
298 .Xc
299 Perform the
300 .Ic setty
301 builtin command.
302 Refer to
303 .Xr editrc 5
304 for more information.
305 .It Dv EL_TELLTC , Xo
306 .Fa "const char *" ,
307 .Fa "..." ,
308 .Dv NULL
309 .Xc
310 Perform the
311 .Ic telltc
312 builtin command.
313 Refer to
314 .Xr editrc 5
315 for more information.
316 .It Dv EL_ADDFN , Xo
317 .Fa "const char *name" ,
318 .Fa "const char *help" ,
319 .Fa "unsigned char (*func)(EditLine *e, int ch)
320 .Xc
321 Add a user defined function,
322 .Fn func ,
323 referred to as
324 .Fa name
325 which is invoked when a key which is bound to
326 .Fa name
327 is entered.
328 .Fa help
329 is a description of
330 .Fa name .
331 At invocation time,
332 .Fa ch
333 is the key which caused the invocation.
334 The return value of
335 .Fn func
336 should be one of:
337 .Bl -tag -width "CC_REDISPLAY"
338 .It Dv CC_NORM
339 Add a normal character.
340 .It Dv CC_NEWLINE
341 End of line was entered.
342 .It Dv CC_EOF
343 EOF was entered.
344 .It Dv CC_ARGHACK
345 Expecting further command input as arguments, do nothing visually.
346 .It Dv CC_REFRESH
347 Refresh display.
348 .It Dv CC_CURSOR
349 Cursor moved, so update and perform
350 .Dv CC_REFRESH .
351 .It Dv CC_REDISPLAY
352 Redisplay entire input line.
353 This is useful if a key binding outputs extra information.
354 .It Dv CC_ERROR
355 An error occurred.
356 Beep, and flush tty.
357 .It Dv CC_FATAL
358 Fatal error, reset tty to known state.
359 .El
360 .It Dv EL_HIST , Xo
361 .Fa "History *(*func)(History *, int op, ...)" ,
362 .Fa "const char *ptr"
363 .Xc
364 Defines which history function to use, which is usually
365 .Fn history .
366 .Fa ptr
367 should be the value returned by
368 .Fn history_init .
369 .El
370 .It Fn el_source
371 Initialise
372 .Nm
373 by reading the contents of
374 .Fa file .
375 .Fn el_parse
376 is called for each line in
377 .Fa file .
378 If
379 .Fa file
380 is
381 .Dv NULL ,
382 try
383 .Pa $HOME/.editrc .
384 Refer to
385 .Xr editrc 5
386 for details on the format of
387 .Fa file .
388 .It Fn el_resize
389 Must be called if the terminal size changes.
390 If
391 .Dv EL_SIGNAL
392 has been set with
393 .Fn el_set ,
394 then this is done automatically.
395 Otherwise, it's the responsibility of the application to call
396 .Fn el_resize
397 on the appropriate occasions.
398 .It Fn el_line
399 Return the editing information for the current line in a
400 .Fa LineInfo
401 structure, which is defined as follows:
402 .Bd -literal
403 typedef struct lineinfo {
404     const char *buffer;    /* address of buffer */
405     const char *cursor;    /* address of cursor */
406     const char *lastchar;  /* address of last character */
407 } LineInfo;
408 .Ed
409 .It Fn el_insertstr
410 Insert
411 .Fa str
412 into the line at the cursor.
413 Returns -1 if
414 .Fa str
415 is empty or won't fit, and 0 otherwise.
416 .It Fn el_deletestr
417 Delete
418 .Fa num
419 characters before the cursor.
420 .It Fn el_data_set
421 Set the user data to
422 .Fa data .
423 .It Fn el_data_get
424 Get the user data.
425 .El
426 .Sh HISTORY LIST FUNCTIONS
427 The history functions use a common data structure,
428 .Fa History ,
429 which is created by
430 .Fn history_init
431 and freed by
432 .Fn history_end .
433 .Pp
434 The following functions are available:
435 .Bl -tag -width 4n
436 .It Fn history_init
437 Initialise the history list, and return a data structure
438 to be used by all other history list functions.
439 .It Fn history_end
440 Clean up and finish with
441 .Fa h ,
442 assumed to have been created with
443 .Fn history_init .
444 .It Fn history
445 Perform operation
446 .Fa op
447 on the history list, with optional arguments as needed by the
448 operation.
449 The following values for
450 .Fa op
451 are supported, along with the required argument list:
452 .Bl -tag -width 4n
453 .It Dv H_EVENT , Fa "int size"
454 Set size of history to
455 .Fa size
456 elements.
457 .It Dv H_END
458 Cleans up and finishes with
459 .Fa h ,
460 assumed to be created with
461 .Fn history_init .
462 .It Dv H_CLEAR
463 Clear the history.
464 .It Dv H_FUNC , Xo
465 .Fa "void *ptr" ,
466 .Fa "history_gfun_t first" ,
467 .Fa "history_gfun_t next" ,
468 .Fa "history_gfun_t last" ,
469 .Fa "history_gfun_t prev" ,
470 .Fa "history_gfun_t curr" ,
471 .Fa "history_vfun_t clear" ,
472 .Fa "history_efun_t enter" ,
473 .Fa "history_efun_t add"
474 .Xc
475 Define functions to perform various history operations.
476 .Fa ptr
477 is the argument given to a function when it's invoked.
478 .It Dv H_FIRST
479 Return the first element in the history.
480 .It Dv H_LAST
481 Return the last element in the history.
482 .It Dv H_PREV
483 Return the previous element in the history.
484 .It Dv H_NEXT
485 Return the next element in the history.
486 .It Dv H_CURR
487 Return the current element in the history.
488 .It Dv H_ADD , Fa "const char *str"
489 Append
490 .Fa str
491 to the current element of the history, or create an element with
492 .Dv H_ENTER
493 if there isn't one.
494 .It Dv H_ENTER , Fa "const char *str"
495 Add
496 .Fa str
497 as a new element to the history, and, if necessary,
498 removing the oldest entry to keep the list to the created size.
499 .It Dv H_PREV_STR , Fa "const char *str"
500 Return the closest previous event that starts with
501 .Fa str .
502 .It Dv H_NEXT_STR , Fa "const char *str"
503 Return the closest next event that starts with
504 .Fa str .
505 .It Dv H_PREV_EVENT , Fa "int e"
506 Return the previous event numbered
507 .Fa e .
508 .It Dv H_NEXT_EVENT , Fa "int e"
509 Return the next event numbered
510 .Fa e .
511 .It Dv H_LOAD , Fa "const char *file"
512 Load the history list stored in
513 .Fa file .
514 .It Dv H_SAVE , Fa "const char *file"
515 Save the history list to
516 .Fa file .
517 .El
518 .El
519 .\"XXX.Sh EXAMPLES
520 .\"XXX: provide some examples
521 .Sh SEE ALSO
522 .Xr sh 1 ,
523 .Xr signal 3 ,
524 .Xr termcap 3 ,
525 .Xr editrc 5
526 .Sh HISTORY
527 The
528 .Nm
529 library first appeared in
530 .Bx 4.4 .
531 .Sh AUTHORS
532 .An -nosplit
533 The
534 .Nm
535 library was written by
536 .An Christos Zoulas ,
537 and this manual was written by
538 .An Luke Mewburn .
539 .Sh BUGS
540 This documentation is probably incomplete.
541 .Pp
542 .Fn el_parse
543 should not modify the supplied
544 .Va argv[0] .
545 .Pp
546 The tokenization functions are not publicly defined in
547 .Li <histedit.h> .