28f6ddb84e8de974012766021ee7a72fdee3ee53
[asterisk/asterisk.git] / main / editline / editline.3
1 .\"     $NetBSD: editline.3,v 1.25 2002/01/15 02:46:22 wiz Exp $
2 .\"
3 .\" Copyright (c) 1997-1999 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 FOUNDATION OR CONTRIBUTORS
28 .\" BE 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 .Dd November 12, 1999
37 .Os
38 .Dt EDITLINE 3
39 .Sh NAME
40 .Nm editline ,
41 .Nm el_init ,
42 .Nm el_end ,
43 .Nm el_reset ,
44 .Nm el_gets ,
45 .Nm el_getc ,
46 .Nm el_push ,
47 .Nm el_parse ,
48 .Nm el_set ,
49 .Nm el_source ,
50 .Nm el_resize ,
51 .Nm el_line ,
52 .Nm el_insertstr ,
53 .Nm el_deletestr ,
54 .Nm history_init ,
55 .Nm history_end ,
56 .Nm history
57 .Nd line editor and history functions
58 .Sh LIBRARY
59 .Lb libedit
60 .Sh SYNOPSIS
61 .Fd #include <histedit.h>
62 .Ft EditLine *
63 .Fn el_init "const char *prog" "FILE *fin" "FILE *fout" "FILE *ferr"
64 .Ft void
65 .Fn el_end "EditLine *e"
66 .Ft void
67 .Fn el_reset "EditLine *e"
68 .Ft const char *
69 .Fn el_gets "EditLine *e" "int *count"
70 .Ft int
71 .Fn el_getc "EditLine *e" "char *ch"
72 .Ft void
73 .Fn el_push "EditLine *e" "const char *str"
74 .Ft int
75 .Fn el_parse "EditLine *e" "int argc" "char *argv[]"
76 .Ft int
77 .Fn el_set "EditLine *e" "int op" "..."
78 .Ft int
79 .Fn el_get "EditLine *e" "int op" "void *result"
80 .Ft int
81 .Fn el_source "EditLine *e" "const char *file"
82 .Ft void
83 .Fn el_resize "EditLine *e"
84 .Ft const LineInfo *
85 .Fn el_line "EditLine *e"
86 .Ft int
87 .Fn el_insertstr "EditLine *e" "const char *str"
88 .Ft void
89 .Fn el_deletestr "EditLine *e" "int count"
90 .Ft History *
91 .Fn history_init
92 .Ft void
93 .Fn history_end "History *h"
94 .Ft int
95 .Fn history "History *h" "HistEvent *ev" "int op" "..."
96 .Sh DESCRIPTION
97 The
98 .Nm
99 library provides generic line editing and history functions,
100 similar to those found in
101 .Xr sh 1 .
102 .Pp
103 These functions are available in the
104 .Nm libedit
105 library (which needs the
106 .Nm libtermcap
107 library).
108 Programs should be linked with
109 .Fl ledit ltermcap .
110 .Sh LINE EDITING FUNCTIONS
111 The line editing functions use a common data structure,
112 .Fa EditLine ,
113 which is created by
114 .Fn el_init
115 and freed by
116 .Fn el_end .
117 .Pp
118 The following functions are available:
119 .Bl -tag -width 4n
120 .It Fn el_init
121 Initialise the line editor, and return a data structure
122 to be used by all other line editing functions.
123 .Fa prog
124 is the name of the invoking program, used when reading the
125 .Xr editrc 5
126 file to determine which settings to use.
127 .Fa fin ,
128 .Fa fout
129 and
130 .Fa ferr
131 are the input, output, and error streams (respectively) to use.
132 In this documentation, references to
133 .Dq the tty
134 are actually to this input/output stream combination.
135 .It Fn el_end
136 Clean up and finish with
137 .Fa e ,
138 assumed to have been created with
139 .Fn el_init .
140 .It Fn el_reset
141 Reset the tty and the parser.
142 This should be called after an error which may have upset the tty's
143 state.
144 .It Fn el_gets
145 Read a line from the tty.
146 .Fa count
147 is modified to contain the number of characters read.
148 Returns the line read if successful, or
149 .Dv NULL
150 if no characters were read or if an error occurred.
151 .It Fn el_getc
152 Read a character from the tty.
153 .Fa ch
154 is modified to contain the character read.
155 Returns the number of characters read if successful, -1 otherwise.
156 .It Fn el_push
157 Pushes
158 .Fa str
159 back onto the input stream.
160 This is used by the macro expansion mechanism.
161 Refer to the description of
162 .Ic bind
163 .Fl s
164 in
165 .Xr editrc 5
166 for more information.
167 .It Fn el_parse
168 Parses the
169 .Fa argv
170 array (which is
171 .Fa argc
172 elements in size)
173 to execute builtin
174 .Nm
175 commands.
176 If the command is prefixed with
177 .Dq prog :
178 then
179 .Fn el_parse
180 will only execute the command if
181 .Dq prog
182 matches the
183 .Fa prog
184 argument supplied to
185 .Fn el_init .
186 The return value is
187 -1 if the command is unknown,
188 0 if there was no error or
189 .Dq prog
190 didn't match, or
191 1 if the command returned an error.
192 Refer to
193 .Xr editrc 5
194 for more information.
195 .It Fn el_set
196 Set
197 .Nm
198 parameters.
199 .Fa op
200 determines which parameter to set, and each operation has its
201 own parameter list.
202 .Pp
203 The following values for
204 .Fa op
205 are supported, along with the required argument list:
206 .Bl -tag -width 4n
207 .It Dv EL_PROMPT , Fa "char *(*f)(EditLine *)"
208 Define prompt printing function as
209 .Fa f ,
210 which is to return a string that contains the prompt.
211 .It Dv EL_RPROMPT , Fa "char *(*f)(EditLine *)"
212 Define right side prompt printing function as
213 .Fa f ,
214 which is to return a string that contains the prompt.
215 .It Dv EL_TERMINAL , Fa "const char *type"
216 Define terminal type of the tty to be
217 .Fa type ,
218 or to
219 .Ev TERM
220 if
221 .Fa type
222 is
223 .Dv NULL .
224 .It Dv EL_EDITOR , Fa "const char *mode"
225 Set editing mode to
226 .Fa mode ,
227 which must be one of
228 .Dq emacs
229 or
230 .Dq vi .
231 .It Dv EL_SIGNAL , Fa "int flag"
232 If
233 .Fa flag
234 is non-zero,
235 .Nm
236 will install its own signal handler for the following signals when
237 reading command input:
238 .Dv SIGCONT ,
239 .Dv SIGHUP ,
240 .Dv SIGINT ,
241 .Dv SIGQUIT ,
242 .Dv SIGSTOP ,
243 .Dv SIGTERM ,
244 .Dv SIGTSTP ,
245 and
246 .Dv SIGWINCH .
247 Otherwise, the current signal handlers will be used.
248 .It Dv EL_BIND , Xo
249 .Fa "const char *" ,
250 .Fa "..." ,
251 .Dv NULL
252 .Xc
253 Perform the
254 .Ic bind
255 builtin command.
256 Refer to
257 .Xr editrc 5
258 for more information.
259 .It Dv EL_ECHOTC , Xo
260 .Fa "const char *" ,
261 .Fa "..." ,
262 .Dv NULL
263 .Xc
264 Perform the
265 .Ic echotc
266 builtin command.
267 Refer to
268 .Xr editrc 5
269 for more information.
270 .It Dv EL_SETTC , Xo
271 .Fa "const char *" ,
272 .Fa "..." ,
273 .Dv NULL
274 .Xc
275 Perform the
276 .Ic settc
277 builtin command.
278 Refer to
279 .Xr editrc 5
280 for more information.
281 .It Dv EL_SETTY , Xo
282 .Fa "const char *" ,
283 .Fa "..." ,
284 .Dv NULL
285 .Xc
286 Perform the
287 .Ic setty
288 builtin command.
289 Refer to
290 .Xr editrc 5
291 for more information.
292 .It Dv EL_TELLTC , Xo
293 .Fa "const char *" ,
294 .Fa "..." ,
295 .Dv NULL
296 .Xc
297 Perform the
298 .Ic telltc
299 builtin command.
300 Refer to
301 .Xr editrc 5
302 for more information.
303 .It Dv EL_ADDFN , Xo
304 .Fa "const char *name" ,
305 .Fa "const char *help" ,
306 .Fa "unsigned char (*func)(EditLine *e, int ch)
307 .Xc
308 Add a user defined function,
309 .Fn func ,
310 referred to as
311 .Fa name
312 which is invoked when a key which is bound to
313 .Fa name
314 is entered.
315 .Fa help
316 is a description of
317 .Fa name .
318 At invocation time,
319 .Fa ch
320 is the key which caused the invocation.
321 The return value of
322 .Fn func
323 should be one of:
324 .Bl -tag -width "CC_REDISPLAY"
325 .It Dv CC_NORM
326 Add a normal character.
327 .It Dv CC_NEWLINE
328 End of line was entered.
329 .It Dv CC_EOF
330 EOF was entered.
331 .It Dv CC_ARGHACK
332 Expecting further command input as arguments, do nothing visually.
333 .It Dv CC_REFRESH
334 Refresh display.
335 .It Dv CC_REFRESH_BEEP
336 Refresh display, and beep.
337 .It Dv CC_CURSOR
338 Cursor moved, so update and perform
339 .Dv CC_REFRESH .
340 .It Dv CC_REDISPLAY
341 Redisplay entire input line.
342 This is useful if a key binding outputs extra information.
343 .It Dv CC_ERROR
344 An error occurred.
345 Beep, and flush tty.
346 .It Dv CC_FATAL
347 Fatal error, reset tty to known state.
348 .El
349 .It Dv EL_HIST , Xo
350 .Fa "History *(*func)(History *, int op, ...)" ,
351 .Fa "const char *ptr"
352 .Xc
353 Defines which history function to use, which is usually
354 .Fn history .
355 .Fa ptr
356 should be the value returned by
357 .Fn history_init .
358 .It Dv EL_EDITMODE , Fa "int flag"
359 If
360 .Fa flag
361 is non-zero,
362 editing is enabled (the default).
363 Note that this is only an indication, and does not
364 affect the operation of
365 .Nm "" .
366 At this time, it is the caller's responsibility to
367 check this
368 (using
369 .Fn el_get )
370 to determine if editing should be enabled or not.
371 .It Dv EL_GETCFN , Fa "int (*f)(EditLine *, char *c)"
372 Define the character reading function as
373 .Fa f ,
374 which is to return the number of characters read and store them in
375 .Fa c .
376 This function is called internally by
377 .Fn el_gets
378 and
379 .Fn el_getc .
380 The builtin function can be set or restored with the special function
381 name ``EL_BUILTIN_GETCFN''.
382 .It Dv EL_CLIENTDATA , Fa "void *data"
383 Register
384 .Fa data
385 to be associated with this EditLine structure. It can be retrieved with
386 the corresponding
387 .Fn el_get
388 call.
389 .El
390 .It Fn el_get
391 Get
392 .Nm
393 parameters.
394 .Fa op
395 determines which parameter to retrieve into
396 .Fa result .
397 .Pp
398 The following values for
399 .Fa op
400 are supported, along with actual type of
401 .Fa result :
402 .Bl -tag -width 4n
403 .It Dv EL_PROMPT , Fa "char *(*f)(EditLine *)"
404 Return a pointer to the function that displays the prompt.
405 .It Dv EL_RPROMPT , Fa "char *(*f)(EditLine *)"
406 Return a pointer to the function that displays the rightside prompt.
407 .It Dv EL_EDITOR , Fa "const char *"
408 Return the name of the editor, which will be one of
409 .Dq emacs
410 or
411 .Dq vi .
412 .It Dv EL_SIGNAL , Fa "int *"
413 Return non-zero if
414 .Nm
415 has installed private signal handlers (see
416 .Fn el_get
417 above).
418 .It Dv EL_EDITMODE, Fa "int *"
419 Return non-zero if editing is enabled.
420 .It Dv EL_GETCFN, Fa "int (**f)(EditLine *, char *)"
421 Return a pointer to the function that read characters, which is equal to
422 ``EL_BUILTIN_GETCFN'' in the case of the default builtin function.
423 .It Dv EL_CLIENTDATA , Fa "void **data"
424 Retrieve
425 .Fa data
426 previously registered with the corresponding
427 .Fn el_set
428 call.
429 .El
430 .It Fn el_source
431 Initialise
432 .Nm
433 by reading the contents of
434 .Fa file .
435 .Fn el_parse
436 is called for each line in
437 .Fa file .
438 If
439 .Fa file
440 is
441 .Dv NULL ,
442 try
443 .Pa $PWD/.editrc
444 then
445 .Pa $HOME/.editrc .
446 Refer to
447 .Xr editrc 5
448 for details on the format of
449 .Fa file .
450 .It Fn el_resize
451 Must be called if the terminal size changes.
452 If
453 .Dv EL_SIGNAL
454 has been set with
455 .Fn el_set ,
456 then this is done automatically.
457 Otherwise, it's the responsibility of the application to call
458 .Fn el_resize
459 on the appropriate occasions.
460 .It Fn el_line
461 Return the editing information for the current line in a
462 .Fa LineInfo
463 structure, which is defined as follows:
464 .Bd -literal
465 typedef struct lineinfo {
466     const char *buffer;    /* address of buffer */
467     const char *cursor;    /* address of cursor */
468     const char *lastchar;  /* address of last character */
469 } LineInfo;
470 .Ed
471 .It Fn el_insertstr
472 Insert
473 .Fa str
474 into the line at the cursor.
475 Returns -1 if
476 .Fa str
477 is empty or won't fit, and 0 otherwise.
478 .It Fn el_deletestr
479 Delete
480 .Fa num
481 characters before the cursor.
482 .El
483 .Sh HISTORY LIST FUNCTIONS
484 The history functions use a common data structure,
485 .Fa History ,
486 which is created by
487 .Fn history_init
488 and freed by
489 .Fn history_end .
490 .Pp
491 The following functions are available:
492 .Bl -tag -width 4n
493 .It Fn history_init
494 Initialise the history list, and return a data structure
495 to be used by all other history list functions.
496 .It Fn history_end
497 Clean up and finish with
498 .Fa h ,
499 assumed to have been created with
500 .Fn history_init .
501 .It Fn history
502 Perform operation
503 .Fa op
504 on the history list, with optional arguments as needed by the
505 operation.
506 .Fa ev
507 is changed accordingly to operation.
508 The following values for
509 .Fa op
510 are supported, along with the required argument list:
511 .Bl -tag -width 4n
512 .It Dv H_SETSIZE , Fa "int size"
513 Set size of history to
514 .Fa size
515 elements.
516 .It Dv H_GETSIZE
517 Get number of events currently in history.
518 .It Dv H_END
519 Cleans up and finishes with
520 .Fa h ,
521 assumed to be created with
522 .Fn history_init .
523 .It Dv H_CLEAR
524 Clear the history.
525 .It Dv H_FUNC , Xo
526 .Fa "void *ptr" ,
527 .Fa "history_gfun_t first" ,
528 .Fa "history_gfun_t next" ,
529 .Fa "history_gfun_t last" ,
530 .Fa "history_gfun_t prev" ,
531 .Fa "history_gfun_t curr" ,
532 .Fa "history_sfun_t set" ,
533 .Fa "history_vfun_t clear" ,
534 .Fa "history_efun_t enter" ,
535 .Fa "history_efun_t add"
536 .Xc
537 Define functions to perform various history operations.
538 .Fa ptr
539 is the argument given to a function when it's invoked.
540 .It Dv H_FIRST
541 Return the first element in the history.
542 .It Dv H_LAST
543 Return the last element in the history.
544 .It Dv H_PREV
545 Return the previous element in the history.
546 .It Dv H_NEXT
547 Return the next element in the history.
548 .It Dv H_CURR
549 Return the current element in the history.
550 .It Dv H_SET
551 Set the cursor to point to the requested element.
552 .It Dv H_ADD , Fa "const char *str"
553 Append
554 .Fa str
555 to the current element of the history, or create an element with
556 .It Dv H_APPEND , Fa "const char *str"
557 Append
558 .Fa str
559 to the last new element of the history.
560 .It Dv H_ENTER , Fa "const char *str"
561 Add
562 .Fa str
563 as a new element to the history, and, if necessary,
564 removing the oldest entry to keep the list to the created size.
565 .It Dv H_PREV_STR , Fa "const char *str"
566 Return the closest previous event that starts with
567 .Fa str .
568 .It Dv H_NEXT_STR , Fa "const char *str"
569 Return the closest next event that starts with
570 .Fa str .
571 .It Dv H_PREV_EVENT , Fa "int e"
572 Return the previous event numbered
573 .Fa e .
574 .It Dv H_NEXT_EVENT , Fa "int e"
575 Return the next event numbered
576 .Fa e .
577 .It Dv H_LOAD , Fa "const char *file"
578 Load the history list stored in
579 .Fa file .
580 .It Dv H_SAVE , Fa "const char *file"
581 Save the history list to
582 .Fa file .
583 .El
584 .Pp
585 .Fn history
586 returns 0 if the operation
587 .Fa op
588 succeeds. Otherwise, -1 is returned and
589 .Fa ev
590 is updated to contain more details about the error.
591 .El
592 .\"XXX.Sh EXAMPLES
593 .\"XXX: provide some examples
594 .Sh SEE ALSO
595 .Xr sh 1 ,
596 .Xr signal 3 ,
597 .Xr termcap 3 ,
598 .Xr editrc 5
599 .Sh HISTORY
600 The
601 .Nm
602 library first appeared in
603 .Bx 4.4 .
604 .Dv CC_REDISPLAY
605 appeared in
606 .Nx 1.3 .
607 .Dv CC_REFRESH_BEEP ,
608 .Dv EL_EDITMODE
609 and the readline emulation appeared in
610 .Nx 1.4 .
611 .Dv EL_RPROMPT
612 appeared in
613 .Nx 1.5 .
614 .Sh AUTHORS
615 The
616 .Nm
617 library was written by Christos Zoulas.
618 Luke Mewburn wrote this manual and implemented
619 .Dv CC_REDISPLAY ,
620 .Dv CC_REFRESH_BEEP ,
621 .Dv EL_EDITMODE ,
622 and
623 .Dv EL_RPROMPT .
624 Jaromir Dolecek implemented the readline emulation.
625 .Sh BUGS
626 The tokenization functions are not publicly defined in
627 .Fd <histedit.h> .
628 .Pp
629 At this time, it is the responsibility of the caller to
630 check the result of the
631 .Dv EL_EDITMODE
632 operation of
633 .Fn el_get
634 (after an
635 .Fn el_source
636 or
637 .Fn el_parse )
638 to determine if
639 .Nm
640 should be used for further input.
641 I.e.,
642 .Dv EL_EDITMODE
643 is purely an indication of the result of the most recent
644 .Xr editrc 5
645 .Ic edit
646 command.