1EDITLINE(3) Library Functions Manual EDITLINE(3)
2
6 editline, el_init, el_init_fd, el_end, el_reset, el_gets, el_wgets,
7 el_getc, el_wgetc, el_push, el_wpush, el_parse, el_wparse, el_set,
8 el_wset, el_get, el_wget, el_source, el_resize, el_cursor, el_line,
9 el_wline, el_insertstr, el_winsertstr, el_deletestr, el_wdeletestr,
10 history_init, history_winit, history_end, history_wend, history, his‐
11 tory_w, tok_init, tok_winit, tok_end, tok_wend, tok_reset, tok_wreset,
12 tok_line, tok_wline, tok_str, tok_wstr - line editor, history and tok‐
13 enization functions
14
16 Command Line Editor Library (libedit, -ledit)
17
19 #include <histedit.h>
20 EditLine *
22 el_init(const char *prog, FILE *fin, FILE *fout, FILE *ferr);
23 EditLine *
25 el_init_fd(const char *prog, FILE *fin, FILE *fout, FILE *ferr, int
26 fdin, int fdout, int fderr);
27 void
29 el_end(EditLine *e);
30 void
32 el_reset(EditLine *e);
33 const char *
35 el_gets(EditLine *e, int *count);
36 const wchar_t *
38 el_wgets(EditLine *e, int *count);
39 int
41 el_getc(EditLine *e, char *ch);
42 int
44 el_wgetc(EditLine *e, wchar_t *wc);
45 void
47 el_push(EditLine *e, const char *mbs);
48 void
50 el_wpush(EditLine *e, const wchar_t *wcs);
51 int
53 el_parse(EditLine *e, int argc, const char *argv[]);
54 int
56 el_wparse(EditLine *e, int argc, const wchar_t *argv[]);
57 int
59 el_set(EditLine *e, int op, ...);
60 int
62 el_wset(EditLine *e, int op, ...);
63 int
65 el_get(EditLine *e, int op, ...);
66 int
68 el_wget(EditLine *e, int op, ...);
69 int
71 el_source(EditLine *e, const char *file);
72 void
74 el_resize(EditLine *e);
75 int
77 el_cursor(EditLine *e, int count);
78 const LineInfo *
80 el_line(EditLine *e);
81 const LineInfoW *
83 el_wline(EditLine *e);
84 int
86 el_insertstr(EditLine *e, const char *str);
87 int
89 el_winsertstr(EditLine *e, const wchar_t *str);
90 void
92 el_deletestr(EditLine *e, int count);
93 void
95 el_wdeletestr(EditLine *e, int count);
96 History *
98 history_init(void );
99 HistoryW *
101 history_winit(void );
102 void
104 history_end(History *h);
105 void
107 history_wend(HistoryW *h);
108 int
110 history(History *h, HistEvent *ev, int op, ...);
111 int
113 history_w(HistoryW *h, HistEventW *ev, int op, ...);
114 Tokenizer *
116 tok_init(const char *IFS);
117 TokenizerW *
119 tok_winit(const wchar_t *IFS);
120 void
122 tok_end(Tokenizer *t);
123 void
125 tok_wend(TokenizerW *t);
126 void
128 tok_reset(Tokenizer *t);
129 void
131 tok_wreset(TokenizerW *t);
132 int
134 tok_line(Tokenizer *t, const LineInfo *li, int *argc, const char
135 **argv[], int *cursorc, int *cursoro);
136 int
138 tok_wline(TokenizerW *t, const LineInfoW *li, int *argc, const wchar_t
139 **argv[], int *cursorc, int *cursoro);
140 int
142 tok_str(Tokenizer *t, const char *str, int *argc, const char **argv[]);
143 int
145 tok_wstr(TokenizerW *t, const wchar_t *str, int *argc, const wchar_t
146 **argv[]);
147
149 The editline library provides generic line editing, history and tok‐
150 enization functions, similar to those found in sh(1).
151 These functions are available in the libedit library (which needs the
153 libtermcap library). Programs should be linked with -ledit ltermcap .
154 The editline library respects the LC_CTYPE locale set by the applica‐
156 tion program and never uses setlocale(3) to change the locale. The
157 only locales supported are UTF-8 and the default C or POSIX locale. If
158 any other locale is set, behaviour is undefined.
159
161 The line editing functions use a common data structure, EditLine, which
162 is created by el_init() or el_init_fd() and freed by el_end().
163 The wide-character functions behave the same way as their narrow coun‐
165 terparts.
166 The following functions are available:
168 el_init()
170 Initialize the line editor, and return a data structure to be
171 used by all other line editing functions, or NULL on failure.
172 prog is the name of the invoking program, used when reading the
173 editrc(5) file to determine which settings to use. fin, fout
174 and ferr are the input, output, and error streams (respectively)
175 to use. In this documentation, references to ``the tty'' are
176 actually to this input/output stream combination.
177 el_init_fd()
179 Like el_init() but allows specifying file descriptors for the
180 stdio(3) corresponding streams, in case those were created with
181 funopen(3).
182 el_end()
184 Clean up and finish with e, assumed to have been created with
185 el_init() or el_init_fd().
186 el_reset()
188 Reset the tty and the parser. This should be called after an
189 error which may have upset the tty's state.
190 el_gets()
192 Read a line from the tty. count is modified to contain the num‐
193 ber of characters read. Returns the line read if successful, or
194 NULL if no characters were read or if an error occurred. If an
195 error occurred, count is set to -1 and errno contains the error
196 code that caused it. The return value may not remain valid
197 across calls to el_gets() and must be copied if the data is to
198 be retained.
199 el_wgetc()
201 Read a wide character from the tty, respecting the current
202 locale, or from the input queue described in editline(7) if that
203 is not empty, and store it in wc. If an invalid or incomplete
204 character is found, it is discarded, errno is set to Er EILSEQ ,
205 and the next character is read and stored in wc. Returns 1 if a
206 valid character was read, 0 on end of file, or -1 on read(2)
207 failure. In the latter case, errno is set to indicate the
208 error.
209 el_getc()
211 Read a wide character as described for el_wgetc() and return 0
212 on end of file or -1 on failure. If the wide character can be
213 represented as a single-byte character, convert it with
214 wctob(3), store the result in ch, and return 1; otherwise, set
215 errno to Er ERANGE and return -1. In the C or POSIX locale,
216 this simply reads a byte, but for any other locale, including
217 UTF-8, this is rarely useful.
218 el_wpush()
220 Push the wide character string wcs back onto the input queue
221 described in editline(7). If the queue overflows, for example
222 due to a recursive macro, or if an error occurs, for example
223 because wcs is NULL or memory allocation fails, the function
224 beeps at the user, but does not report the problem to the call‐
225 er.
226 el_push()
228 Use the current locale to convert the multibyte string mbs to a
229 wide character string, and pass the result to el_wpush().
230 el_parse()
232 Parses the argv array (which is argc elements in size) to exe‐
233 cute builtin editline commands. If the command is prefixed with
234 ``prog :'' then el_parse() will only execute the command if
235 ``prog'' matches the prog argument supplied to el_init(). The
236 return value is -1 if the command is unknown, 0 if there was no
237 error or ``prog'' didn't match, or 1 if the command returned an
238 error. Refer to editrc(5) for more information.
239 el_set()
241 Set editline parameters. op determines which parameter to set,
242 and each operation has its own parameter list. Returns 0 on
243 success, -1 on failure.
244 The following values for op are supported, along with the
246 required argument list:
247 EL_PROMPT , char *(*f)(EditLine *)
249 Define prompt printing function as f, which is to return
250 a string that contains the prompt.
251 EL_PROMPT_ESC , char *(*f)(EditLine *), Fa char c
253 Same as EL_PROMPT , but the c argument indicates the
254 start/stop literal prompt character.
255 If a start/stop literal character is found in the prompt,
257 the character itself is not printed, but characters after
258 it are printed directly to the terminal without affecting
259 the state of the current line. A subsequent second
260 start/stop literal character ends this behavior. This is
261 typically used to embed literal escape sequences that
262 change the color/style of the terminal in the prompt. 0
263 unsets it.
264 EL_REFRESH
266 Re-display the current line on the next terminal line.
267 EL_RPROMPT , char *(*f)(EditLine *)
269 Define right side prompt printing function as f, which is
270 to return a string that contains the prompt.
271 EL_RPROMPT_ESC , char *(*f)(EditLine *), Fa char c
273 Define the right prompt printing function but with a lit‐
274 eral escape character.
275 EL_TERMINAL , const char *type
277 Define terminal type of the tty to be type, or to TERM if
278 type is NULL .
279 EL_EDITOR , const char *mode
281 Set editing mode to mode, which must be one of ``emacs''
282 or ``vi''.
283 EL_SIGNAL , int flag
285 If flag is non-zero, editline will install its own signal
286 handler for the following signals when reading command
287 input: SIGCONT , SIGHUP , SIGINT , SIGQUIT , SIGSTOP ,
288 SIGTERM , SIGTSTP , and SIGWINCH . Otherwise, the cur‐
289 rent signal handlers will be used.
290 EL_BIND , const char *, Fa ..., Dv NULL
292 Perform the bind builtin command. Refer to editrc(5) for
293 more information.
294 EL_ECHOTC , const char *, Fa ..., Dv NULL
296 Perform the echotc builtin command. Refer to editrc(5)
297 for more information.
298 EL_SETTC , const char *, Fa ..., Dv NULL
300 Perform the settc builtin command. Refer to editrc(5)
301 for more information.
302 EL_SETTY , const char *, Fa ..., Dv NULL
304 Perform the setty builtin command. Refer to editrc(5)
305 for more information.
306 EL_TELLTC , const char *, Fa ..., Dv NULL
308 Perform the telltc builtin command. Refer to editrc(5)
309 for more information.
310 EL_ADDFN , const char *name, Fa const char *help,
312 Fa "unsigned char (*func)(EditLine *e, int ch)" Add a
313 user defined function, func(), referred to as name which
314 is invoked when a key which is bound to name is entered.
315 help is a description of name. At invocation time, ch is
316 the key which caused the invocation. The return value of
317 func() should be one of:
318 CC_NORM
320 Add a normal character.
321 CC_NEWLINE
323 End of line was entered.
324 CC_EOF EOF was entered.
326 CC_ARGHACK
328 Expecting further command input as arguments, do
329 nothing visually.
330 CC_REFRESH
332 Refresh display.
333 CC_REFRESH_BEEP
335 Refresh display, and beep.
336 CC_CURSOR
338 Cursor moved, so update and perform CC_REFRESH .
339 CC_REDISPLAY
341 Redisplay entire input line. This is useful if a
342 key binding outputs extra information.
343 CC_ERROR
345 An error occurred. Beep, and flush tty.
346 CC_FATAL
348 Fatal error, reset tty to known state.
349 EL_HIST , History *(*func)(History *, int op, ...),
351 Fa "const char *ptr" Defines which history function to
352 use, which is usually history(). ptr should be the value
353 returned by history_init().
354 EL_EDITMODE , int flag
356 If flag is non-zero, editing is enabled (the default).
357 Note that this is only an indication, and does not affect
358 the operation of . At this time, it is the caller's
359 responsibility to check this (using el_get() ) to deter‐
360 mine if editing should be enabled or not.
361 EL_UNBUFFERED , int flag
363 If flag is zero, unbuffered mode is disabled (the
364 default). In unbuffered mode, el_gets() will return
365 immediately after processing a single character.
366 EL_GETCFN , el_rfunc_t f
368 Whenever reading a character, use the function -ragged
369 -offset indent -compact
370 int
372 Fo f EditLine *e wchar_t *wc Fc which stores the character in wc
373 and returns 1 on success, 0 on end of file, or -1 on I/O or
374 encoding errors. Functions internally using it include
375 el_wgets(), el_wgetc(), el_gets(), and el_getc(). Initially, a
376 builtin function is installed, and replacing it is discouraged
377 because writing such a function is very error prone. The
378 builtin function can be restored at any time by passing the spe‐
379 cial value EL_BUILTIN_GETCFN instead of a function pointer.
380 EL_CLIENTDATA , void *data
382 Register data to be associated with this EditLine struc‐
383 ture. It can be retrieved with the corresponding
384 el_get(); call.
385 EL_SETFP , int fd, Fa FILE *fp
387 Set the current editline file pointer for ``input'' fd =
388 0 , ``output'' fd = 1 , or ``error'' fd = 2 from fp.
389 el_get()
391 Get editline parameters. op determines which parameter to
392 retrieve into result. Returns 0 if successful, -1 otherwise.
393 The following values for op are supported, along with actual
395 type of result :
396 EL_PROMPT , char *(*f)(EditLine *), Fa char *c
398 Set f to a pointer to the function that displays the
399 prompt. If c is not NULL , set it to the start/stop lit‐
400 eral prompt character.
401 EL_RPROMPT , char *(*f)(EditLine *), Fa char *c
403 Set f to a pointer to the function that displays the
404 prompt. If c is not NULL , set it to the start/stop lit‐
405 eral prompt character.
406 EL_EDITOR , const char **n
408 Set the name of the editor in n, which will be one of
409 ``emacs'' or ``vi''.
410 EL_GETTC , const char *name, Fa void *value
412 If name is a valid termcap(5) capability set value to the
413 current value of that capability.
414 EL_SIGNAL , int *s
416 Set s to non-zero if editline has installed private sig‐
417 nal handlers (see el_get() above).
418 EL_EDITMODE , int *c
420 Set c to non-zero if editing is enabled.
421 EL_GETCFN , el_rfunc_t *f
423 Set f to a pointer to the function that reads characters,
424 or to EL_BUILTIN_GETCFN if the builtin function is in
425 use.
426 EL_CLIENTDATA , void **data
428 Set data to the previously registered client data set by
429 an el_set() call.
430 EL_UNBUFFERED , int *c
432 Set c to non-zero if unbuffered mode is enabled.
433 EL_GETFP , int fd", Fa FILE **fp
435 Set fp to the current editline file pointer for ``input''
436 fd = 0 , ``output'' fd = 1 , or ``error'' fd = 2 .
437 el_source()
439 Initialize editline by reading the contents of file. el_parse()
440 is called for each line in file. If file is NULL , try
441 $HOME/.editrc. Refer to editrc(5) for details on the format of
442 file. el_source() returns 0 on success and -1 on error.
443 el_resize()
445 Must be called if the terminal size changes. If EL_SIGNAL has
446 been set with el_set(), then this is done automatically. Other‐
447 wise, it's the responsibility of the application to call
448 el_resize() on the appropriate occasions.
449 el_cursor()
451 Move the cursor to the right (if positive) or to the left (if
452 negative) count characters. Returns the resulting offset of the
453 cursor from the beginning of the line.
454 el_line()
456 Return the editing information for the current line in a Line‐
457 Info structure, which is defined as follows:
458 typedef struct lineinfo {
460 const char *buffer; /* address of buffer */
461 const char *cursor; /* address of cursor */
462 const char *lastchar; /* address of last character */
463 } LineInfo;
464 buffer is not NUL terminated. This function may be called after
466 el_gets() to obtain the LineInfo structure pertaining to line
467 returned by that function, and from within user defined func‐
468 tions added with EL_ADDFN .
469 el_insertstr()
471 Insert str into the line at the cursor. Returns -1 if str is
472 empty or won't fit, and 0 otherwise.
473 el_deletestr()
475 Delete count characters before the cursor.
476
478 The history functions use a common data structure, History, which is
479 created by history_init() and freed by history_end().
480 The following functions are available:
482 history_init()
484 Initialize the history list, and return a data structure to be
485 used by all other history list functions, or NULL on failure.
486 history_end()
488 Clean up and finish with h, assumed to have been created with
489 history_init().
490 history()
492 Perform operation op on the history list, with optional argu‐
493 ments as needed by the operation. ev is changed accordingly to
494 operation. The following values for op are supported, along
495 with the required argument list:
496 H_SETSIZE , int size
498 Set size of history to size elements.
499 H_GETSIZE
501 Get number of events currently in history.
502 H_END Cleans up and finishes with h, assumed to be created with
504 history_init().
505 H_CLEAR
507 Clear the history.
508 H_FUNC , void *ptr, Fa history_gfun_t first,
510 Fa "history_gfun_t next" , Fa "history_gfun_t last" , Fa
511 "history_gfun_t prev" , Fa "history_gfun_t curr" , Fa
512 "history_sfun_t set" , Fa "history_vfun_t clear" , Fa
513 "history_efun_t enter" , Fa "history_efun_t add" Define
514 functions to perform various history operations. ptr is
515 the argument given to a function when it's invoked.
516 H_FIRST
518 Return the first element in the history.
519 H_LAST Return the last element in the history.
521 H_PREV Return the previous element in the history. It is newer
523 than the current one.
524 H_NEXT Return the next element in the history. It is older than
526 the current one.
527 H_CURR Return the current element in the history.
529 H_SET Set the cursor to point to the requested element.
531 H_ADD , const char *str
533 Append str to the current element of the history, or per‐
534 form the H_ENTER operation with argument str if there is
535 no current element.
536 H_APPEND , const char *str
538 Append str to the last new element of the history.
539 H_ENTER , const char *str
541 Add str as a new element to the history and, if neces‐
542 sary, removing the oldest entry to keep the list to the
543 created size. If H_SETUNIQUE has been called with a non-
544 zero argument, the element will not be entered into the
545 history if its contents match the ones of the current
546 history element. If the element is entered history()
547 returns 1; if it is ignored as a duplicate returns 0.
548 Finally history() returns -1 if an error occurred.
549 H_PREV_STR , const char *str
551 Return the closest previous event that starts with str.
552 H_NEXT_STR , const char *str
554 Return the closest next event that starts with str.
555 H_PREV_EVENT , int e
557 Return the previous event numbered e.
558 H_NEXT_EVENT , int e
560 Return the next event numbered e.
561 H_LOAD , const char *file
563 Load the history list stored in file.
564 H_SAVE , const char *file
566 Save the history list to file.
567 H_SAVE_FP , FILE *fp
569 Save the history list to the opened
570 FILE
572 pointer fp.
573 H_SETUNIQUE , int unique
575 Set flag that adjacent identical event strings should not
576 be entered into the history.
577 H_GETUNIQUE
579 Retrieve the current setting if adjacent identical ele‐
580 ments should be entered into the history.
581 H_DEL , int e
583 Delete the event numbered e. This function is only pro‐
584 vided for readline(3) compatibility. The caller is
585 responsible for free'ing the string in the returned His‐
586 tEvent.
587 history(); returns >= 0 if the operation op succeeds. Otherwise, -1 is
589 returned and ev is updated to contain more details about the error.
590
592 The tokenization functions use a common data structure, Tokenizer,
593 which is created by tok_init() and freed by tok_end().
594 The following functions are available:
596 tok_init()
598 Initialize the tokenizer, and return a data structure to be used
599 by all other tokenizer functions. IFS contains the Input Field
600 Separators, which defaults to <space ,> <tab ,> and <newline> if
601 NULL .
602 tok_end()
604 Clean up and finish with t, assumed to have been created with
605 tok_init().
606 tok_reset()
608 Reset the tokenizer state. Use after a line has been success‐
609 fully tokenized by tok_line() or tok_str() and before a new line
610 is to be tokenized.
611 tok_line()
613 Tokenize li, If successful, modify: argv to contain the words,
614 argc to contain the number of words, cursorc (if not NULL ) to
615 contain the index of the word containing the cursor, and cursoro
616 (if not NULL ) to contain the offset within argv[cursorc] of the
617 cursor.
618 Returns 0 if successful, -1 for an internal error, 1 for an
620 unmatched single quote, 2 for an unmatched double quote, and 3
621 for a backslash quoted <newline .> A positive exit code indi‐
622 cates that another line should be read and tokenization
623 attempted again.
624 tok_str()
626 A simpler form of tok_line(; ) str is a NUL terminated string to
627 tokenize.
628
630 sh(1), signal(3), termcap(3), editrc(5), termcap(5), editline(7)
631
633 The editline library first appeared in Bx 4.4 . CC_REDISPLAY appeared
634 in Nx 1.3 . CC_REFRESH_BEEP , EL_EDITMODE and the readline emulation
635 appeared in Nx 1.4 . EL_RPROMPT appeared in Nx 1.5 .
636
638 -nosplit The editline library was written by
639 Christos Zoulas .
641 Luke Mewburn wrote this manual and implemented CC_REDISPLAY ,
643 CC_REFRESH_BEEP , EL_EDITMODE , and EL_RPROMPT .
644 Jaromir Dolecek implemented the readline emulation.
646 Johny Mattsson implemented wide-character support.
648
650 At this time, it is the responsibility of the caller to check the
651 result of the EL_EDITMODE operation of el_get() (after an el_source()
652 or el_parse() ) to determine if editline should be used for further
653 input. I.e., EL_EDITMODE is purely an indication of the result of the
654 most recent editrc(5) edit command.
655 May 22, 2016 EDITLINE(3)