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