| blob | 0deef4aa88c5ce57351abf486ae7c3cc898bd35f |
1 .\" $OpenBSD: editline.3,v 1.46 2016/05/22 22:08:42 schwarze Exp $
2 .\" $NetBSD: editline.3,v 1.88 2016/02/25 14:59:22 wiz Exp $
3 .\"
4 .\" Copyright (c) 1997-2003 The NetBSD Foundation, Inc.
5 .\" All rights reserved.
6 .\"
7 .\" This file was contributed to The NetBSD Foundation by Luke Mewburn.
8 .\"
9 .\" Redistribution and use in source and binary forms, with or without
10 .\" modification, are permitted provided that the following conditions
11 .\" are met:
12 .\" 1. Redistributions of source code must retain the above copyright
13 .\" notice, this list of conditions and the following disclaimer.
14 .\" 2. Redistributions in binary form must reproduce the above copyright
15 .\" notice, this list of conditions and the following disclaimer in the
16 .\" documentation and/or other materials provided with the distribution.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
21 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28 .\" POSSIBILITY OF SUCH DAMAGE.
29 .\"
30 .Dd $Mdocdate: May 22 2016 $
31 .Dt EDITLINE 3
32 .Os
33 .Sh NAME
34 .Nm editline ,
35 .Nm el_init ,
36 .Nm el_end ,
37 .Nm el_reset ,
38 .Nm el_gets ,
39 .Nm el_wgets ,
40 .Nm el_getc ,
41 .Nm el_wgetc ,
42 .Nm el_push ,
43 .Nm el_wpush ,
44 .Nm el_parse ,
45 .Nm el_wparse ,
46 .Nm el_set ,
47 .Nm el_wset ,
48 .Nm el_get ,
49 .Nm el_wget ,
50 .Nm el_source ,
51 .Nm el_resize ,
52 .Nm el_line ,
53 .Nm el_wline ,
54 .Nm el_insertstr ,
55 .Nm el_winsertstr ,
56 .Nm el_deletestr ,
57 .Nm el_wdeletestr ,
58 .Nm history_init ,
59 .Nm history_winit ,
60 .Nm history_end ,
61 .Nm history_wend ,
62 .Nm history ,
63 .Nm history_w ,
64 .Nm tok_init ,
65 .Nm tok_winit ,
66 .Nm tok_end ,
67 .Nm tok_wend ,
68 .Nm tok_reset ,
69 .Nm tok_wreset ,
70 .Nm tok_line ,
71 .Nm tok_wline ,
72 .Nm tok_str ,
73 .Nm tok_wstr
74 .Nd line editor, history and tokenization functions
75 .Sh SYNOPSIS
76 .In histedit.h
77 .Ft EditLine *
78 .Fn el_init "const char *prog" "FILE *fin" "FILE *fout" "FILE *ferr"
79 .Ft void
80 .Fn el_end "EditLine *e"
81 .Ft void
82 .Fn el_reset "EditLine *e"
83 .Ft const char *
84 .Fn el_gets "EditLine *e" "int *count"
85 .Ft const wchar_t *
86 .Fn el_wgets "EditLine *e" "int *count"
87 .Ft int
88 .Fn el_getc "EditLine *e" "char *ch"
89 .Ft int
90 .Fn el_wgetc "EditLine *e" "wchar_t *wc"
91 .Ft void
92 .Fn el_push "EditLine *e" "const char *mbs"
93 .Ft void
94 .Fn el_wpush "EditLine *e" "const wchar_t *wcs"
95 .Ft int
96 .Fn el_parse "EditLine *e" "int argc" "const char *argv[]"
97 .Ft int
98 .Fn el_wparse "EditLine *e" "int argc" "const wchar_t *argv[]"
99 .Ft int
100 .Fn el_set "EditLine *e" "int op" "..."
101 .Ft int
102 .Fn el_wset "EditLine *e" "int op" "..."
103 .Ft int
104 .Fn el_get "EditLine *e" "int op" "..."
105 .Ft int
106 .Fn el_wget "EditLine *e" "int op" "..."
107 .Ft int
108 .Fn el_source "EditLine *e" "const char *file"
109 .Ft void
110 .Fn el_resize "EditLine *e"
111 .Ft const LineInfo *
112 .Fn el_line "EditLine *e"
113 .Ft const LineInfoW *
114 .Fn el_wline "EditLine *e"
115 .Ft int
116 .Fn el_insertstr "EditLine *e" "const char *str"
117 .Ft int
118 .Fn el_winsertstr "EditLine *e" "const wchar_t *str"
119 .Ft void
120 .Fn el_deletestr "EditLine *e" "int count"
121 .Ft void
122 .Fn el_wdeletestr "EditLine *e" "int count"
123 .Ft History *
124 .Fn history_init void
125 .Ft HistoryW *
126 .Fn history_winit void
127 .Ft void
128 .Fn history_end "History *h"
129 .Ft void
130 .Fn history_wend "HistoryW *h"
131 .Ft int
132 .Fn history "History *h" "HistEvent *ev" "int op" "..."
133 .Ft int
134 .Fn history_w "HistoryW *h" "HistEventW *ev" "int op" "..."
135 .Ft Tokenizer *
136 .Fn tok_init "const char *IFS"
137 .Ft TokenizerW *
138 .Fn tok_winit "const wchar_t *IFS"
139 .Ft void
140 .Fn tok_end "Tokenizer *t"
141 .Ft void
142 .Fn tok_wend "TokenizerW *t"
143 .Ft void
144 .Fn tok_reset "Tokenizer *t"
145 .Ft void
146 .Fn tok_wreset "TokenizerW *t"
147 .Ft int
148 .Fn tok_line "Tokenizer *t" "const LineInfo *li" "int *argc" "const char **argv[]" "int *cursorc" "int *cursoro"
149 .Ft int
150 .Fn tok_wline "TokenizerW *t" "const LineInfoW *li" "int *argc" "const wchar_t **argv[]" "int *cursorc" "int *cursoro"
151 .Ft int
152 .Fn tok_str "Tokenizer *t" "const char *str" "int *argc" "const char **argv[]"
153 .Ft int
154 .Fn tok_wstr "TokenizerW *t" "const wchar_t *str" "int *argc" "const wchar_t **argv[]"
155 .Sh DESCRIPTION
156 The
157 .Nm
158 library provides generic line editing, history and tokenization functions,
159 similar to those found in
160 .Xr sh 1 .
161 .Pp
162 These functions are available in the
163 .Nm libedit
164 library (which needs the
165 .Nm libcurses
166 library).
167 Programs should be linked with
168 .Fl ledit lcurses .
169 .Pp
170 The
171 .Nm
172 library respects the
173 .Ev LC_CTYPE
174 locale set by the application program and never uses
175 .Xr setlocale 3
176 to change the locale.
177 The only locales supported are UTF-8 and the default C or POSIX locale.
178 If any other locale is set, behaviour is undefined.
179 .Sh LINE EDITING FUNCTIONS
180 The line editing functions use a common data structure,
181 .Fa EditLine ,
182 which is created by
183 .Fn el_init
184 and freed by
185 .Fn el_end .
186 .Pp
187 The wide-character functions behave the same way as their narrow
188 counterparts.
189 .Pp
190 The following functions are available:
191 .Bl -tag -width 4n
192 .It Fn el_init
193 Initialize the line editor, and return a data structure
194 to be used by all other line editing functions, or
195 .Dv NULL
196 on failure.
197 .Fa prog
198 is the name of the invoking program, used when reading the
199 .Xr editrc 5
200 file to determine which settings to use.
201 .Fa fin ,
202 .Fa fout
203 and
204 .Fa ferr
205 are the input, output, and error streams (respectively) to use.
206 In this documentation, references to
207 .Dq the tty
208 are actually to this input/output stream combination.
209 .It Fn el_end
210 Clean up and finish with
211 .Fa e ,
212 assumed to have been created with
213 .Fn el_init .
214 .It Fn el_reset
215 Reset the tty and the parser.
216 This should be called after an error which may have upset the tty's
217 state.
218 .It Fn el_gets
219 Read a line from the tty.
220 .Fa count
221 is modified to contain the number of characters read.
222 Returns the line read if successful, or
223 .Dv NULL
224 if no characters were read or if an error occurred.
225 If an error occurred,
226 .Fa count
227 is set to \-1 and
228 .Dv errno
229 contains the error code that caused it.
230 The return value may not remain valid across calls to
231 .Fn el_gets
232 and must be copied if the data is to be retained.
233 .It Fn el_wgetc
234 Read a wide character from the tty, respecting the current locale,
235 or from the input queue described in
236 .Xr editline 7
237 if that is not empty, and store it in
238 .Fa wc .
239 If an invalid or incomplete character is found, it is discarded,
240 .Va errno
241 is set to
242 .Er EILSEQ ,
243 and the next character is read and stored in
244 .Fa wc .
245 Returns 1 if a valid character was read, 0 on end of file, or \-1 on
246 .Xr read 2
247 failure.
248 In the latter case,
249 .Va errno
250 is set to indicate the error.
251 .It Fn el_getc
252 Read a wide character as described for
253 .Fn el_wgetc
254 and return 0 on end of file or \-1 on failure.
255 If the wide character can be represented as a single-byte character,
256 convert it with
257 .Xr wctob 3 ,
258 store the result in
259 .Fa ch ,
260 and return 1; otherwise, set
261 .Va errno
262 to
263 .Er ERANGE
264 and return \-1.
265 In the C or POSIX locale, this simply reads a byte, but for any other
266 locale, including UTF-8, this is rarely useful.
267 .It Fn el_wpush
268 Push the wide character string
269 .Fa wcs
270 back onto the input queue described in
271 .Xr editline 7 .
272 If the queue overflows, for example due to a recursive macro,
273 or if an error occurs, for example because
274 .Fa wcs
275 is
276 .Dv NULL
277 or memory allocation fails, the function beeps at the user,
278 but does not report the problem to the caller.
279 .It Fn el_push
280 Use the current locale to convert the multibyte string
281 .Fa mbs
282 to a wide character string, and pass the result to
283 .Fn el_wpush .
284 .It Fn el_parse
285 Parses the
286 .Fa argv
287 array (which is
288 .Fa argc
289 elements in size)
290 to execute builtin
291 .Nm
292 commands.
293 If the command is prefixed with
294 .Dq prog :
295 then
296 .Fn el_parse
297 will only execute the command if
298 .Dq prog
299 matches the
300 .Fa prog
301 argument supplied to
302 .Fn el_init .
303 The return value is
304 \-1 if the command is unknown,
305 0 if there was no error or
306 .Dq prog
307 didn't match, or
308 1 if the command returned an error.
309 Refer to
310 .Xr editrc 5
311 for more information.
312 .It Fn el_set
313 Set
314 .Nm
315 parameters.
316 .Fa op
317 determines which parameter to set, and each operation has its
318 own parameter list.
319 Returns 0 on success, \-1 on failure.
320 .Pp
321 The following values for
322 .Fa op
323 are supported, along with the required argument list:
324 .Bl -tag -width 4n
325 .It Dv EL_PROMPT , Fa "char *(*f)(EditLine *)"
326 Define prompt printing function as
327 .Fa f ,
328 which is to return a string that contains the prompt.
329 .It Dv EL_PROMPT_ESC , Fa "char *(*f)(EditLine *)" , Fa "char c"
330 Same as
331 .Dv EL_PROMPT ,
332 but the
333 .Fa c
334 argument indicates the start/stop literal prompt character.
335 .Pp
336 If a start/stop literal character is found in the prompt, the
337 character itself
338 is not printed, but characters after it are printed directly to the
339 terminal without affecting the state of the current line.
340 A subsequent second start/stop literal character ends this behavior.
341 This is typically used to embed literal escape sequences that change the
342 color/style of the terminal in the prompt.
343 .Dv 0
344 unsets it.
345 .It Dv EL_REFRESH
346 Re-display the current line on the next terminal line.
347 .It Dv EL_RPROMPT , Fa "char *(*f)(EditLine *)"
348 Define right side prompt printing function as
349 .Fa f ,
350 which is to return a string that contains the prompt.
351 .It Dv EL_RPROMPT_ESC , Fa "char *(*f)(EditLine *)" , Fa "char c"
352 Define the right prompt printing function but with a literal escape character.
353 .It Dv EL_TERMINAL , Fa "const char *type"
354 Define terminal type of the tty to be
355 .Fa type ,
356 or to
357 .Ev TERM
358 if
359 .Fa type
360 is
361 .Dv NULL .
362 .It Dv EL_EDITOR , Fa "const char *mode"
363 Set editing mode to
364 .Fa mode ,
365 which must be one of
366 .Dq emacs
367 or
368 .Dq vi .
369 .It Dv EL_SIGNAL , Fa "int flag"
370 If
371 .Fa flag
372 is non-zero,
373 .Nm
374 will install its own signal handler for the following signals when
375 reading command input:
376 .Dv SIGCONT ,
377 .Dv SIGHUP ,
378 .Dv SIGINT ,
379 .Dv SIGQUIT ,
380 .Dv SIGSTOP ,
381 .Dv SIGTERM ,
382 .Dv SIGTSTP ,
383 and
384 .Dv SIGWINCH .
385 Otherwise, the current signal handlers will be used.
386 .It Dv EL_BIND , Fa "const char *" , Fa "..." , Dv NULL
387 Perform the
388 .Ic bind
389 builtin command.
390 Refer to
391 .Xr editrc 5
392 for more information.
393 .It Dv EL_ECHOTC , Fa "const char *" , Fa "..." , Dv NULL
394 Perform the
395 .Ic echotc
396 builtin command.
397 Refer to
398 .Xr editrc 5
399 for more information.
400 .It Dv EL_SETTC , Fa "const char *" , Fa "..." , Dv NULL
401 Perform the
402 .Ic settc
403 builtin command.
404 Refer to
405 .Xr editrc 5
406 for more information.
407 .It Dv EL_SETTY , Fa "const char *" , Fa "..." , Dv NULL
408 Perform the
409 .Ic setty
410 builtin command.
411 Refer to
412 .Xr editrc 5
413 for more information.
414 .It Dv EL_TELLTC , Fa "const char *" , Fa "..." , Dv NULL
415 Perform the
416 .Ic telltc
417 builtin command.
418 Refer to
419 .Xr editrc 5
420 for more information.
421 .It Dv EL_ADDFN , Fa "const char *name" , Fa "const char *help" , \
422 Fa "unsigned char (*func)(EditLine *e, int ch)"
423 Add a user defined function,
424 .Fn func ,
425 referred to as
426 .Fa name
427 which is invoked when a key which is bound to
428 .Fa name
429 is entered.
430 .Fa help
431 is a description of
432 .Fa name .
433 At invocation time,
434 .Fa ch
435 is the key which caused the invocation.
436 The return value of
437 .Fn func
438 should be one of:
439 .Bl -tag -width "CC_REDISPLAY"
440 .It Dv CC_NORM
441 Add a normal character.
442 .It Dv CC_NEWLINE
443 End of line was entered.
444 .It Dv CC_EOF
445 EOF was entered.
446 .It Dv CC_ARGHACK
447 Expecting further command input as arguments, do nothing visually.
448 .It Dv CC_REFRESH
449 Refresh display.
450 .It Dv CC_REFRESH_BEEP
451 Refresh display, and beep.
452 .It Dv CC_CURSOR
453 Cursor moved, so update and perform
454 .Dv CC_REFRESH .
455 .It Dv CC_REDISPLAY
456 Redisplay entire input line.
457 This is useful if a key binding outputs extra information.
458 .It Dv CC_ERROR
459 An error occurred.
460 Beep, and flush tty.
461 .It Dv CC_FATAL
462 Fatal error, reset tty to known state.
463 .El
464 .It Dv EL_HIST , Fa "History *(*func)(History *, int op, ...)" , \
465 Fa "const char *ptr"
466 Defines which history function to use, which is usually
467 .Fn history .
468 .Fa ptr
469 should be the value returned by
470 .Fn history_init .
471 .It Dv EL_EDITMODE , Fa "int flag"
472 If
473 .Fa flag
474 is non-zero,
475 editing is enabled (the default).
476 Note that this is only an indication, and does not
477 affect the operation of
478 .Nm .
479 At this time, it is the caller's responsibility to
480 check this
481 (using
482 .Fn el_get )
483 to determine if editing should be enabled or not.
484 .It Dv EL_UNBUFFERED , Fa "int flag"
485 If
486 .Fa flag
487 is zero,
488 unbuffered mode is disabled (the default).
489 In unbuffered mode,
490 .Fn el_gets
491 will return immediately after processing a single character.
492 .It Dv EL_GETCFN , Fa "el_rfunc_t f"
493 Whenever reading a character, use the function
494 .Bd -ragged -offset indent -compact
495 .Ft int
496 .Fo f
497 .Fa "EditLine *e"
498 .Fa "wchar_t *wc"
499 .Fc
500 .Ed
501 which stores the character in
502 .Fa wc
503 and returns 1 on success, 0 on end of file, or \-1 on I/O or encoding
504 errors.
505 Functions internally using it include
506 .Fn el_wgets ,
507 .Fn el_wgetc ,
508 .Fn el_gets ,
509 and
510 .Fn el_getc .
511 Initially, a builtin function is installed, and replacing it
512 is discouraged because writing such a function is very error prone.
513 The builtin function can be restored at any time by passing the
514 special value
515 .Dv EL_BUILTIN_GETCFN
516 instead of a function pointer.
517 .It Dv EL_CLIENTDATA , Fa "void *data"
518 Register
519 .Fa data
520 to be associated with this EditLine structure.
521 It can be retrieved with the corresponding
522 .Fn el_get
523 call.
524 .It Dv EL_SETFP , Fa "int fd" , Fa "FILE *fp"
525 Set the current
526 .Nm editline
527 file pointer for
528 .Dq input
529 .Fa fd
530 =
531 .Dv 0 ,
532 .Dq output
533 .Fa fd
534 =
535 .Dv 1 ,
536 or
537 .Dq error
538 .Fa fd
539 =
540 .Dv 2
541 from
542 .Fa fp .
543 .El
544 .It Fn el_get
545 Get
546 .Nm
547 parameters.
548 .Fa op
549 determines which parameter to retrieve into
550 .Fa result .
551 Returns 0 if successful, \-1 otherwise.
552 .Pp
553 The following values for
554 .Fa op
555 are supported, along with actual type of
556 .Fa result :
557 .Bl -tag -width 4n
558 .It Dv EL_PROMPT , Fa "char *(*f)(EditLine *)" , Fa "char *c"
559 Set
560 .Fa f
561 to a pointer to the function that displays the prompt.
562 If
563 .Fa c
564 is not
565 .Dv NULL ,
566 set it to the start/stop literal prompt character.
567 .It Dv EL_RPROMPT , Fa "char *(*f)(EditLine *)" , Fa "char *c"
568 Set
569 .Fa f
570 to a pointer to the function that displays the prompt.
571 If
572 .Fa c
573 is not
574 .Dv NULL ,
575 set it to the start/stop literal prompt character.
576 .It Dv EL_EDITOR , Fa "const char **n"
577 Set the name of the editor in
578 .Fa n ,
579 which will be one of
580 .Dq emacs
581 or
582 .Dq vi .
583 .It Dv EL_GETTC , Fa "const char *name" , Fa "void *value"
584 If
585 .Fa name
586 is a valid
587 .Xr termcap 5
588 capability set
589 .Fa value
590 to the current value of that capability.
591 .It Dv EL_SIGNAL , Fa "int *s"
592 Set
593 .Fa s
594 to non-zero if
595 .Nm
596 has installed private signal handlers (see
597 .Fn el_get
598 above).
599 .It Dv EL_EDITMODE , Fa "int *c"
600 Set
601 .Fa c
602 to non-zero if editing is enabled.
603 .It Dv EL_GETCFN , Fa "el_rfunc_t *f"
604 Set
605 .Fa f
606 to a pointer to the function that reads characters, or to
607 .Dv EL_BUILTIN_GETCFN
608 if the builtin function is in use.
609 .It Dv EL_CLIENTDATA , Fa "void **data"
610 Set
611 .Fa data
612 to the previously registered client data set by an
613 .Fn el_set
614 call.
615 .It Dv EL_UNBUFFERED , Fa "int *c"
616 Set
617 .Fa c
618 to non-zero if unbuffered mode is enabled.
619 .It Dv EL_PREP_TERM , Fa "int"
620 Sets or clears terminal editing mode.
621 .It Dv EL_GETFP , Fa "int fd", Fa "FILE **fp"
622 Set
623 .Fa fp
624 to the current
625 .Nm editline
626 file pointer for
627 .Dq input
628 .Fa fd
629 =
630 .Dv 0 ,
631 .Dq output
632 .Fa fd
633 =
634 .Dv 1 ,
635 or
636 .Dq error
637 .Fa fd
638 =
639 .Dv 2 .
640 .El
641 .It Fn el_source
642 Initialize
643 .Nm
644 by reading the contents of
645 .Fa file .
646 .Fn el_parse
647 is called for each line in
648 .Fa file .
649 If
650 .Fa file
651 is
652 .Dv NULL ,
653 try
654 .Pa $HOME/.editrc .
655 Refer to
656 .Xr editrc 5
657 for details on the format of
658 .Fa file .
659 .Fn el_source
660 returns 0 on success and \-1 on error.
661 .It Fn el_resize
662 Must be called if the terminal size changes.
663 If
664 .Dv EL_SIGNAL
665 has been set with
666 .Fn el_set ,
667 then this is done automatically.
668 Otherwise, it's the responsibility of the application to call
669 .Fn el_resize
670 on the appropriate occasions.
671 .It Fn el_line
672 Return the editing information for the current line in a
673 .Fa LineInfo
674 structure, which is defined as follows:
675 .Bd -literal
676 typedef struct lineinfo {
677 const char *buffer; /* address of buffer */
678 const char *cursor; /* address of cursor */
679 const char *lastchar; /* address of last character */
680 } LineInfo;
681 .Ed
682 .Pp
683 .Fa buffer
684 is not NUL terminated.
685 This function may be called after
686 .Fn el_gets
687 to obtain the
688 .Fa LineInfo
689 structure pertaining to line returned by that function,
690 and from within user defined functions added with
691 .Dv EL_ADDFN .
692 .It Fn el_insertstr
693 Insert
694 .Fa str
695 into the line at the cursor.
696 Returns \-1 if
697 .Fa str
698 is empty or won't fit, and 0 otherwise.
699 .It Fn el_deletestr
700 Delete
701 .Fa count
702 characters before the cursor.
703 .El
704 .Sh HISTORY LIST FUNCTIONS
705 The history functions use a common data structure,
706 .Fa History ,
707 which is created by
708 .Fn history_init
709 and freed by
710 .Fn history_end .
711 .Pp
712 The following functions are available:
713 .Bl -tag -width 4n
714 .It Fn history_init
715 Initialize the history list, and return a data structure
716 to be used by all other history list functions, or
717 .Dv NULL
718 on failure.
719 .It Fn history_end
720 Clean up and finish with
721 .Fa h ,
722 assumed to have been created with
723 .Fn history_init .
724 .It Fn history
725 Perform operation
726 .Fa op
727 on the history list, with optional arguments as needed by the
728 operation.
729 .Fa ev
730 is changed accordingly to operation.
731 The following values for
732 .Fa op
733 are supported, along with the required argument list:
734 .Bl -tag -width 4n
735 .It Dv H_SETSIZE , Fa "int size"
736 Set size of history to
737 .Fa size
738 elements.
739 .It Dv H_GETSIZE
740 Get number of events currently in history.
741 .It Dv H_END
742 Cleans up and finishes with
743 .Fa h ,
744 assumed to be created with
745 .Fn history_init .
746 .It Dv H_CLEAR
747 Clear the history.
748 .It Dv H_FUNC , Fa "void *ptr" , Fa "history_gfun_t first" , \
749 Fa "history_gfun_t next" , Fa "history_gfun_t last" , \
750 Fa "history_gfun_t prev" , Fa "history_gfun_t curr" , \
751 Fa "history_sfun_t set" , Fa "history_vfun_t clear" , \
752 Fa "history_efun_t enter" , Fa "history_efun_t add"
753 Define functions to perform various history operations.
754 .Fa ptr
755 is the argument given to a function when it's invoked.
756 .It Dv H_FIRST
757 Return the first element in the history.
758 .It Dv H_LAST
759 Return the last element in the history.
760 .It Dv H_PREV
761 Return the previous element in the history.
762 It is newer than the current one.
763 .It Dv H_NEXT
764 Return the next element in the history.
765 It is older than the current one.
766 .It Dv H_CURR
767 Return the current element in the history.
768 .It Dv H_SET
769 Set the cursor to point to the requested element.
770 .It Dv H_ADD , Fa "const char *str"
771 Append
772 .Fa str
773 to the current element of the history, or perform the
774 .Dv H_ENTER
775 operation with argument
776 .Fa str
777 if there is no current element.
778 .It Dv H_APPEND , Fa "const char *str"
779 Append
780 .Fa str
781 to the last new element of the history.
782 .It Dv H_ENTER , Fa "const char *str"
783 Add
784 .Fa str
785 as a new element to the history and, if necessary,
786 removing the oldest entry to keep the list to the created size.
787 If
788 .Dv H_SETUNIQUE
789 has been called with a non-zero argument, the element
790 will not be entered into the history if its contents match
791 the ones of the current history element.
792 If the element is entered
793 .Fn history
794 returns 1; if it is ignored as a duplicate returns 0.
795 Finally
796 .Fn history
797 returns \-1 if an error occurred.
798 .It Dv H_PREV_STR , Fa "const char *str"
799 Return the closest previous event that starts with
800 .Fa str .
801 .It Dv H_NEXT_STR , Fa "const char *str"
802 Return the closest next event that starts with
803 .Fa str .
804 .It Dv H_PREV_EVENT , Fa "int e"
805 Return the previous event numbered
806 .Fa e .
807 .It Dv H_NEXT_EVENT , Fa "int e"
808 Return the next event numbered
809 .Fa e .
810 .It Dv H_LOAD , Fa "const char *file"
811 Load the history list stored in
812 .Fa file .
813 .It Dv H_SAVE , Fa "const char *file"
814 Save the history list to
815 .Fa file .
816 .It Dv H_SAVE_FP , Fa "FILE *fp"
817 Save the history list to the opened
818 .Ft FILE
819 pointer
820 .Fa fp .
821 .It Dv H_SETUNIQUE , Fa "int unique"
822 Set flag that adjacent identical event strings should not be entered
823 into the history.
824 .It Dv H_GETUNIQUE
825 Retrieve the current setting if adjacent identical elements should
826 be entered into the history.
827 .It Dv H_DEL , Fa "int e"
828 Delete the event numbered
829 .Fa e .
830 This function is only provided for
831 .Xr readline 3
832 compatibility.
833 The caller is responsible for free'ing the string in the returned
834 .Fa HistEvent .
835 .El
836 .Pp
837 .Fn history
838 returns \*[Gt]= 0 if the operation
839 .Fa op
840 succeeds.
841 Otherwise, \-1 is returned and
842 .Fa ev
843 is updated to contain more details about the error.
844 .El
845 .Sh TOKENIZATION FUNCTIONS
846 The tokenization functions use a common data structure,
847 .Fa Tokenizer ,
848 which is created by
849 .Fn tok_init
850 and freed by
851 .Fn tok_end .
852 .Pp
853 The following functions are available:
854 .Bl -tag -width 4n
855 .It Fn tok_init
856 Initialize the tokenizer, and return a data structure
857 to be used by all other tokenizer functions.
858 .Fa IFS
859 contains the Input Field Separators, which defaults to
860 .Aq space ,
861 .Aq tab ,
862 and
863 .Aq newline
864 if
865 .Dv NULL .
866 .It Fn tok_end
867 Clean up and finish with
868 .Fa t ,
869 assumed to have been created with
870 .Fn tok_init .
871 .It Fn tok_reset
872 Reset the tokenizer state.
873 Use after a line has been successfully tokenized
874 by
875 .Fn tok_line
876 or
877 .Fn tok_str
878 and before a new line is to be tokenized.
879 .It Fn tok_line
880 Tokenize
881 .Fa li ,
882 If successful, modify:
883 .Fa argv
884 to contain the words,
885 .Fa argc
886 to contain the number of words,
887 .Fa cursorc
888 (if not
889 .Dv NULL )
890 to contain the index of the word containing the cursor,
891 and
892 .Fa cursoro
893 (if not
894 .Dv NULL )
895 to contain the offset within
896 .Fa argv[cursorc]
897 of the cursor.
898 .Pp
899 Returns
900 0 if successful,
901 \-1 for an internal error,
902 1 for an unmatched single quote,
903 2 for an unmatched double quote,
904 and
905 3 for a backslash quoted
906 .Aq newline .
907 A positive exit code indicates that another line should be read
908 and tokenization attempted again.
909 .
910 .It Fn tok_str
911 A simpler form of
912 .Fn tok_line ;
913 .Fa str
914 is a NUL terminated string to tokenize.
915 .El
916 .
917 .\"XXX.Sh EXAMPLES
918 .\"XXX: provide some examples
919 .Sh SEE ALSO
920 .Xr sh 1 ,
921 .Xr curses 3 ,
922 .Xr signal 3 ,
923 .Xr editrc 5 ,
924 .Xr termcap 5 ,
925 .Xr editline 7
926 .Sh HISTORY
927 The
928 .Nm
929 library first appeared in
930 .Bx 4.4 .
931 .Dv CC_REDISPLAY
932 appeared in
933 .Nx 1.3 .
934 .Dv CC_REFRESH_BEEP ,
935 .Dv EL_EDITMODE
936 and the readline emulation appeared in
937 .Nx 1.4 .
938 .Dv EL_RPROMPT
939 appeared in
940 .Nx 1.5 .
941 .Sh AUTHORS
942 .An -nosplit
943 The
944 .Nm
945 library was written by
946 .An Christos Zoulas .
947 .An Luke Mewburn
948 wrote this manual and implemented
949 .Dv CC_REDISPLAY ,
950 .Dv CC_REFRESH_BEEP ,
951 .Dv EL_EDITMODE ,
952 and
953 .Dv EL_RPROMPT .
954 .An Jaromir Dolecek
955 implemented the readline emulation.
956 .An Johny Mattsson
957 implemented wide-character support.
958 .Sh BUGS
959 At this time, it is the responsibility of the caller to
960 check the result of the
961 .Dv EL_EDITMODE
962 operation of
963 .Fn el_get
964 (after an
965 .Fn el_source
966 or
967 .Fn el_parse )
968 to determine if
969 .Nm
970 should be used for further input.
971 I.e.,
972 .Dv EL_EDITMODE
973 is purely an indication of the result of the most recent
974 .Xr editrc 5
975 .Ic edit
976 command.