1EDITLINE(3) BSD Library Functions Manual EDITLINE(3)
2
4 editline, el_init, el_end, el_reset, el_gets, el_wgets, el_getc,
5 el_wgetc, el_push, el_wpush, el_parse, el_wparse, el_set, el_wset,
6 el_get, el_wget, el_source, el_resize, el_line, el_wline, el_insertstr,
7 el_winsertstr, el_deletestr, el_wdeletestr, history_init, history_winit,
8 history_end, history_wend, history, history_w, tok_init, tok_winit,
9 tok_end, tok_wend, tok_reset, tok_wreset, tok_line, tok_wline, tok_str
10 tok_wstr — line editor, history and tokenization functions
11
13 Command Line Editor Library (libedit, -ledit)
14
16 #include <histedit.h>
17 EditLine *
19 el_init(const char *prog, FILE *fin, FILE *fout, FILE *ferr);
20 void
22 el_end(EditLine *e);
23 void
25 el_reset(EditLine *e);
26 const char *
28 el_gets(EditLine *e, int *count);
29 const wchar_t *
31 el_wgets(EditLine *e, int *count);
32 int
34 el_getc(EditLine *e, char *ch);
35 int
37 el_wgetc(EditLine *e, wchar_t *ch);
38 void
40 el_push(EditLine *e, const char *str);
41 void
43 el_wpush(EditLine *e, const wchar_t *str);
44 int
46 el_parse(EditLine *e, int argc, const char *argv[]);
47 int
49 el_wparse(EditLine *e, int argc, const wchar_t *argv[]);
50 int
52 el_set(EditLine *e, int op, ...);
53 int
55 el_wset(EditLine *e, int op, ...);
56 int
58 el_get(EditLine *e, int op, ...);
59 int
61 el_wget(EditLine *e, int op, ...);
62 int
64 el_source(EditLine *e, const char *file);
65 void
67 el_resize(EditLine *e);
68 const LineInfo *
70 el_line(EditLine *e);
71 int
73 el_insertstr(EditLine *e, const char *str);
74 int
76 el_winsertstr(EditLine *e, const wchar_t *str);
77 void
79 el_deletestr(EditLine *e, int count);
80 void
82 el_wdeletestr(EditLine *e, int count);
83 History *
85 history_init();
86 HistoryW *
88 history_winit();
89 void
91 history_end(History *h);
92 void
94 history_wend(HistoryW *h);
95 int
97 history(History *h, HistEvent *ev, int op, ...);
98 int
100 history_w(HistoryW *h, HistEventW *ev, int op, ...);
101 Tokenizer *
103 tok_init(const char *IFS);
104 TokenizerW *
106 tok_winit(const wchar_t *IFS);
107 void
109 tok_end(Tokenizer *t);
110 void
112 tok_wend(TokenizerW *t);
113 void
115 tok_reset(Tokenizer *t);
116 void
118 tok_wreset(TokenizerW *t);
119 int
121 tok_line(Tokenizer *t, const LineInfo *li, int *argc,
122 const char **argv[], int *cursorc, int *cursoro);
123 int
125 tok_wline(TokenizerW *t, const LineInfoW *li, int *argc,
126 const wchar_t **argv[], int *cursorc, int *cursoro);
127 int
129 tok_str(Tokenizer *t, const char *str, int *argc, const char **argv[]);
130 int
132 tok_wstr(TokenizerW *t, const wchar_t *str, int *argc,
133 const wchar_t **argv[]);
134
136 The editline library provides generic line editing, history and tokeniza‐
137 tion functions, similar to those found in sh(1).
138 These functions are available in the libedit library (which needs the
140 libtermcap library). Programs should be linked with -ledit -ltermcap.
141
143 The line editing functions use a common data structure, EditLine, which
144 is created by el_init() and freed by el_end().
145 The wide-character functions behave the same way as their narrow counter‐
147 parts.
148 The following functions are available:
150 el_init()
152 Initialise the line editor, and return a data structure to be used
153 by all other line editing functions. prog is the name of the
154 invoking program, used when reading the editrc(5) file to determine
155 which settings to use. fin, fout and ferr are the input, output,
156 and error streams (respectively) to use. In this documentation,
157 references to “the tty” are actually to this input/output stream
158 combination.
159 el_end()
161 Clean up and finish with e, assumed to have been created with
162 el_init().
163 el_reset()
165 Reset the tty and the parser. This should be called after an error
166 which may have upset the tty's state.
167 el_gets()
169 Read a line from the tty. count is modified to contain the number
170 of characters read. Returns the line read if successful, or NULL
171 if no characters were read or if an error occurred. If an error
172 occurred, count is set to -1 and errno contains the error code that
173 caused it. The return value may not remain valid across calls to
174 el_gets() and must be copied if the data is to be retained.
175 el_getc()
177 Read a character from the tty. ch is modified to contain the char‐
178 acter read. Returns the number of characters read if successful,
179 -1 otherwise, in which case errno can be inspected for the cause.
180 el_push()
182 Pushes str back onto the input stream. This is used by the macro
183 expansion mechanism. Refer to the description of bind -s in
184 editrc(5) for more information.
185 el_parse()
187 Parses the argv array (which is argc elements in size) to execute
188 builtin editline commands. If the command is prefixed with “prog”:
189 then el_parse() will only execute the command if “prog” matches the
190 prog argument supplied to el_init(). The return value is -1 if the
191 command is unknown, 0 if there was no error or “prog” didn't match,
192 or 1 if the command returned an error. Refer to editrc(5) for more
193 information.
194 el_set()
196 Set editline parameters. op determines which parameter to set, and
197 each operation has its own parameter list.
198 The following values for op are supported, along with the required
200 argument list:
201 EL_PROMPT, char *(*f)(EditLine *)
203 Define prompt printing function as f, which is to return a
204 string that contains the prompt.
205 EL_PROMPT_ESC, char *(*f)(EditLine *), char c
207 Same as EL_PROMPT, but the c argument indicates the
208 start/stop literal prompt character.
209 If a start/stop literal character is found in the prompt, the
211 character itself is not printed, but characters after it are
212 printed directly to the terminal without affecting the state
213 of the current line. A subsequent second start/stop literal
214 character ends this behavior. This is typically used to
215 embed literal escape sequences that change the color/style of
216 the terminal in the prompt. 0 unsets it.
217 EL_REFRESH
219 Re-display the current line on the next terminal line.
220 EL_RPROMPT, char *(*f)(EditLine *)
222 Define right side prompt printing function as f, which is to
223 return a string that contains the prompt.
224 EL_RPROMPT_ESC, char *(*f)(EditLine *), char c
226 Define the right prompt printing function but with a literal
227 escape character.
228 EL_TERMINAL, const char *type
230 Define terminal type of the tty to be type, or to TERM if
231 type is NULL.
232 EL_EDITOR, const char *mode
234 Set editing mode to mode, which must be one of “emacs” or
235 “vi”.
236 EL_SIGNAL, int flag
238 If flag is non-zero, editline will install its own signal
239 handler for the following signals when reading command input:
240 SIGCONT, SIGHUP, SIGINT, SIGQUIT, SIGSTOP, SIGTERM, SIGTSTP,
241 and SIGWINCH. Otherwise, the current signal handlers will be
242 used.
243 EL_BIND, const char *, ..., NULL
245 Perform the bind builtin command. Refer to editrc(5) for
246 more information.
247 EL_ECHOTC, const char *, ..., NULL
249 Perform the echotc builtin command. Refer to editrc(5) for
250 more information.
251 EL_SETTC, const char *, ..., NULL
253 Perform the settc builtin command. Refer to editrc(5) for
254 more information.
255 EL_SETTY, const char *, ..., NULL
257 Perform the setty builtin command. Refer to editrc(5) for
258 more information.
259 EL_TELLTC, const char *, ..., NULL
261 Perform the telltc builtin command. Refer to editrc(5) for
262 more information.
263 EL_ADDFN, const char *name, const char *help, unsigned char
265 (*func)(EditLine *e, int ch)
266 Add a user defined function, func(), referred to as name
267 which is invoked when a key which is bound to name is
268 entered. help is a description of name. At invocation time,
269 ch is the key which caused the invocation. The return value
270 of func() should be one of:
271 CC_NORM Add a normal character.
273 CC_NEWLINE End of line was entered.
275 CC_EOF EOF was entered.
277 CC_ARGHACK Expecting further command input as arguments,
279 do nothing visually.
280 CC_REFRESH Refresh display.
282 CC_REFRESH_BEEP
284 Refresh display, and beep.
285 CC_CURSOR Cursor moved, so update and perform CC_REFRESH.
287 CC_REDISPLAY Redisplay entire input line. This is useful if
289 a key binding outputs extra information.
290 CC_ERROR An error occurred. Beep, and flush tty.
292 CC_FATAL Fatal error, reset tty to known state.
294 EL_HIST, History *(*func)(History *, int op, ...), const char *ptr
296 Defines which history function to use, which is usually
297 history(). ptr should be the value returned by
298 history_init().
299 EL_EDITMODE, int flag
301 If flag is non-zero, editing is enabled (the default). Note
302 that this is only an indication, and does not affect the
303 operation of editline. At this time, it is the caller's
304 responsibility to check this (using el_get()) to determine if
305 editing should be enabled or not.
306 EL_UNBUFFERED, int flag
308 If flag is zero, unbuffered mode is disabled (the default).
309 In unbuffered mode, el_gets() will return immediately after
310 processing a single character.
311 EL_GETCFN, int (*f)(EditLine *, char *c)
313 Define the character reading function as f, which is to
314 return the number of characters read and store them in c.
315 This function is called internally by el_gets() and
316 el_getc(). The builtin function can be set or restored with
317 the special function name “EL_BUILTIN_GETCFN”.
318 EL_CLIENTDATA, void *data
320 Register data to be associated with this EditLine structure.
321 It can be retrieved with the corresponding el_get() call.
322 EL_SETFP, int fd, FILE *fp
324 Set the current editline file pointer for “input” fd = 0,
325 “output” fd = 1, or “error” fd = 2 from fp.
326 el_get()
328 Get editline parameters. op determines which parameter to retrieve
329 into result. Returns 0 if successful, -1 otherwise.
330 The following values for op are supported, along with actual type
332 of result:
333 EL_PROMPT, char *(*f)(EditLine *), char *c
335 Return a pointer to the function that displays the prompt in
336 f. If c is not NULL, return the start/stop literal prompt
337 character in it.
338 EL_RPROMPT, char *(*f)(EditLine *), char *c
340 Return a pointer to the function that displays the prompt in
341 f. If c is not NULL, return the start/stop literal prompt
342 character in it.
343 EL_EDITOR, const char **
345 Return the name of the editor, which will be one of “emacs”
346 or “vi”.
347 EL_GETTC, const char *name, void *value
349 Return non-zero if name is a valid termcap(5) capability and
350 set value to the current value of that capability.
351 EL_SIGNAL, int *
353 Return non-zero if editline has installed private signal han‐
354 dlers (see el_get() above).
355 EL_EDITMODE, int *
357 Return non-zero if editing is enabled.
358 EL_GETCFN, int (**f)(EditLine *, char *)
360 Return a pointer to the function that read characters, which
361 is equal to “EL_BUILTIN_GETCFN” in the case of the default
362 builtin function.
363 EL_CLIENTDATA, void **data
365 Retrieve data previously registered with the corresponding
366 el_set() call.
367 EL_UNBUFFERED, int
369 Return non-zero if unbuffered mode is enabled.
370 EL_PREP_TERM, int
372 Sets or clears terminal editing mode.
373 EL_GETFP, int fd, FILE **fp
375 Return in fp the current editline file pointer for “input” fd
376 = 0, “output” fd = 1, or “error” fd = 2.
377 el_source()
379 Initialise editline by reading the contents of file. el_parse() is
380 called for each line in file. If file is NULL, try $PWD/.editrc
381 then $HOME/.editrc. Refer to editrc(5) for details on the format
382 of file.
383 el_resize()
385 Must be called if the terminal size changes. If EL_SIGNAL has been
386 set with el_set(), then this is done automatically. Otherwise,
387 it's the responsibility of the application to call el_resize() on
388 the appropriate occasions.
389 el_line()
391 Return the editing information for the current line in a LineInfo
392 structure, which is defined as follows:
393 typedef struct lineinfo {
395 const char *buffer; /* address of buffer */
396 const char *cursor; /* address of cursor */
397 const char *lastchar; /* address of last character */
398 } LineInfo;
399 buffer is not NUL terminated. This function may be called after
401 el_gets() to obtain the LineInfo structure pertaining to line
402 returned by that function, and from within user defined functions
403 added with EL_ADDFN.
404 el_insertstr()
406 Insert str into the line at the cursor. Returns -1 if str is empty
407 or won't fit, and 0 otherwise.
408 el_deletestr()
410 Delete count characters before the cursor.
411
413 The history functions use a common data structure, History, which is cre‐
414 ated by history_init() and freed by history_end().
415 The following functions are available:
417 history_init()
419 Initialise the history list, and return a data structure to be used
420 by all other history list functions.
421 history_end()
423 Clean up and finish with h, assumed to have been created with
424 history_init().
425 history()
427 Perform operation op on the history list, with optional arguments
428 as needed by the operation. ev is changed accordingly to opera‐
429 tion. The following values for op are supported, along with the
430 required argument list:
431 H_SETSIZE, int size
433 Set size of history to size elements.
434 H_GETSIZE
436 Get number of events currently in history.
437 H_END
439 Cleans up and finishes with h, assumed to be created with
440 history_init().
441 H_CLEAR
443 Clear the history.
444 H_FUNC, void *ptr, history_gfun_t first, history_gfun_t next,
446 history_gfun_t last, history_gfun_t prev, history_gfun_t
447 curr, history_sfun_t set, history_vfun_t clear,
448 history_efun_t enter, history_efun_t add
449 Define functions to perform various history operations. ptr
450 is the argument given to a function when it's invoked.
451 H_FIRST
453 Return the first element in the history.
454 H_LAST
456 Return the last element in the history.
457 H_PREV
459 Return the previous element in the history.
460 H_NEXT
462 Return the next element in the history.
463 H_CURR
465 Return the current element in the history.
466 H_SET
468 Set the cursor to point to the requested element.
469 H_ADD, const char *str
471 Append str to the current element of the history, or perform
472 the H_ENTER operation with argument str if there is no cur‐
473 rent element.
474 H_APPEND, const char *str
476 Append str to the last new element of the history.
477 H_ENTER, const char *str
479 Add str as a new element to the history, and, if necessary,
480 removing the oldest entry to keep the list to the created
481 size. If H_SETUNIQUE was has been called with a non-zero
482 arguments, the element will not be entered into the history
483 if its contents match the ones of the current history ele‐
484 ment. If the element is entered history() returns 1, if it
485 is ignored as a duplicate returns 0. Finally history()
486 returns -1 if an error occurred.
487 H_PREV_STR, const char *str
489 Return the closest previous event that starts with str.
490 H_NEXT_STR, const char *str
492 Return the closest next event that starts with str.
493 H_PREV_EVENT, int e
495 Return the previous event numbered e.
496 H_NEXT_EVENT, int e
498 Return the next event numbered e.
499 H_LOAD, const char *file
501 Load the history list stored in file.
502 H_SAVE, const char *file
504 Save the history list to file.
505 H_SETUNIQUE, int unique
507 Set flag that adjacent identical event strings should not be
508 entered into the history.
509 H_GETUNIQUE
511 Retrieve the current setting if adjacent identical elements
512 should be entered into the history.
513 H_DEL, int e
515 Delete the event numbered e. This function is only provided
516 for readline(3) compatibility. The caller is responsible for
517 free'ing the string in the returned HistEvent.
518 history() returns >= 0 if the operation op succeeds. Otherwise, -1
520 is returned and ev is updated to contain more details about the
521 error.
522
524 The tokenization functions use a common data structure, Tokenizer, which
525 is created by tok_init() and freed by tok_end().
526 The following functions are available:
528 tok_init()
530 Initialise the tokenizer, and return a data structure to be used by
531 all other tokenizer functions. IFS contains the Input Field Sepa‐
532 rators, which defaults to ⟨space⟩, ⟨tab⟩, and ⟨newline⟩ if NULL.
533 tok_end()
535 Clean up and finish with t, assumed to have been created with
536 tok_init().
537 tok_reset()
539 Reset the tokenizer state. Use after a line has been successfully
540 tokenized by tok_line() or tok_str() and before a new line is to be
541 tokenized.
542 tok_line()
544 Tokenize li, If successful, modify: argv to contain the words, argc
545 to contain the number of words, cursorc (if not NULL) to contain
546 the index of the word containing the cursor, and cursoro (if not
547 NULL) to contain the offset within argv[cursorc] of the cursor.
548 Returns 0 if successful, -1 for an internal error, 1 for an
550 unmatched single quote, 2 for an unmatched double quote, and 3 for
551 a backslash quoted ⟨newline⟩. A positive exit code indicates that
552 another line should be read and tokenization attempted again.
553 tok_str()
555 A simpler form of tok_line(); str is a NUL terminated string to
556 tokenize.
557
559 sh(1), signal(3), termcap(3), editrc(5), termcap(5)
560
562 The editline library first appeared in 4.4BSD. CC_REDISPLAY appeared in
563 NetBSD 1.3. CC_REFRESH_BEEP, EL_EDITMODE and the readline emulation
564 appeared in NetBSD 1.4. EL_RPROMPT appeared in NetBSD 1.5.
565
567 The editline library was written by Christos Zoulas. Luke Mewburn wrote
568 this manual and implemented CC_REDISPLAY, CC_REFRESH_BEEP, EL_EDITMODE,
569 and EL_RPROMPT. Jaromir Dolecek implemented the readline emulation.
570 Johny Mattsson implemented wide-character support.
571
573 At this time, it is the responsibility of the caller to check the result
574 of the EL_EDITMODE operation of el_get() (after an el_source() or
575 el_parse()) to determine if editline should be used for further input.
576 I.e., EL_EDITMODE is purely an indication of the result of the most
577 recent editrc(5) edit command.
578BSD September 11, 2012 BSD