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