1EDITLINE(3)              BSD Library Functions Manual              EDITLINE(3)
2

NAME

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

LIBRARY

13     Command Line Editor Library (libedit, -ledit)
14

SYNOPSIS

16     #include <histedit.h>
17
18     EditLine *
19     el_init(const char *prog, FILE *fin, FILE *fout, FILE *ferr);
20
21     void
22     el_end(EditLine *e);
23
24     void
25     el_reset(EditLine *e);
26
27     const char *
28     el_gets(EditLine *e, int *count);
29
30     const wchar_t *
31     el_wgets(EditLine *e, int *count);
32
33     int
34     el_getc(EditLine *e, char *ch);
35
36     int
37     el_wgetc(EditLine *e, wchar_t *ch);
38
39     void
40     el_push(EditLine *e, const char *str);
41
42     void
43     el_wpush(EditLine *e, const wchar_t *str);
44
45     int
46     el_parse(EditLine *e, int argc, const char *argv[]);
47
48     int
49     el_wparse(EditLine *e, int argc, const wchar_t *argv[]);
50
51     int
52     el_set(EditLine *e, int op, ...);
53
54     int
55     el_wset(EditLine *e, int op, ...);
56
57     int
58     el_get(EditLine *e, int op, ...);
59
60     int
61     el_wget(EditLine *e, int op, ...);
62
63     int
64     el_source(EditLine *e, const char *file);
65
66     void
67     el_resize(EditLine *e);
68
69     const LineInfo *
70     el_line(EditLine *e);
71
72     int
73     el_insertstr(EditLine *e, const char *str);
74
75     int
76     el_winsertstr(EditLine *e, const wchar_t *str);
77
78     void
79     el_deletestr(EditLine *e, int count);
80
81     void
82     el_wdeletestr(EditLine *e, int count);
83
84     History *
85     history_init();
86
87     HistoryW *
88     history_winit();
89
90     void
91     history_end(History *h);
92
93     void
94     history_wend(HistoryW *h);
95
96     int
97     history(History *h, HistEvent *ev, int op, ...);
98
99     int
100     history_w(HistoryW *h, HistEventW *ev, int op, ...);
101
102     Tokenizer *
103     tok_init(const char *IFS);
104
105     TokenizerW *
106     tok_winit(const wchar_t *IFS);
107
108     void
109     tok_end(Tokenizer *t);
110
111     void
112     tok_wend(TokenizerW *t);
113
114     void
115     tok_reset(Tokenizer *t);
116
117     void
118     tok_wreset(TokenizerW *t);
119
120     int
121     tok_line(Tokenizer *t, const LineInfo *li, int *argc,
122         const char **argv[], int *cursorc, int *cursoro);
123
124     int
125     tok_wline(TokenizerW *t, const LineInfoW *li, int *argc,
126         const wchar_t **argv[], int *cursorc, int *cursoro);
127
128     int
129     tok_str(Tokenizer *t, const char *str, int *argc, const char **argv[]);
130
131     int
132     tok_wstr(TokenizerW *t, const wchar_t *str, int *argc,
133         const wchar_t **argv[]);
134

DESCRIPTION

136     The editline library provides generic line editing, history and tokeniza‐
137     tion functions, similar to those found in sh(1).
138
139     These functions are available in the libedit library (which needs the
140     libtermcap library).  Programs should be linked with -ledit -ltermcap.
141

LINE EDITING FUNCTIONS

143     The line editing functions use a common data structure, EditLine, which
144     is created by el_init() and freed by el_end().
145
146     The wide-character functions behave the same way as their narrow counter‐
147     parts.
148
149     The following functions are available:
150
151     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
160     el_end()
161           Clean up and finish with e, assumed to have been created with
162           el_init().
163
164     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
168     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
176     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
181     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
186     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
195     el_set()
196           Set editline parameters.  op determines which parameter to set, and
197           each operation has its own parameter list.
198
199           The following values for op are supported, along with the required
200           argument list:
201
202           EL_PROMPT, char *(*f)(EditLine *)
203                 Define prompt printing function as f, which is to return a
204                 string that contains the prompt.
205
206           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
210                 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
218           EL_REFRESH
219                 Re-display the current line on the next terminal line.
220
221           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
225           EL_RPROMPT_ESC, char *(*f)(EditLine *), char c
226                 Define the right prompt printing function but with a literal
227                 escape character.
228
229           EL_TERMINAL, const char *type
230                 Define terminal type of the tty to be type, or to TERM if
231                 type is NULL.
232
233           EL_EDITOR, const char *mode
234                 Set editing mode to mode, which must be one of “emacs” or
235                 “vi”.
236
237           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
244           EL_BIND, const char *, ..., NULL
245                 Perform the bind builtin command.  Refer to editrc(5) for
246                 more information.
247
248           EL_ECHOTC, const char *, ..., NULL
249                 Perform the echotc builtin command.  Refer to editrc(5) for
250                 more information.
251
252           EL_SETTC, const char *, ..., NULL
253                 Perform the settc builtin command.  Refer to editrc(5) for
254                 more information.
255
256           EL_SETTY, const char *, ..., NULL
257                 Perform the setty builtin command.  Refer to editrc(5) for
258                 more information.
259
260           EL_TELLTC, const char *, ..., NULL
261                 Perform the telltc builtin command.  Refer to editrc(5) for
262                 more information.
263
264           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
272                 CC_NORM       Add a normal character.
273
274                 CC_NEWLINE    End of line was entered.
275
276                 CC_EOF        EOF was entered.
277
278                 CC_ARGHACK    Expecting further command input as arguments,
279                               do nothing visually.
280
281                 CC_REFRESH    Refresh display.
282
283                 CC_REFRESH_BEEP
284                               Refresh display, and beep.
285
286                 CC_CURSOR     Cursor moved, so update and perform CC_REFRESH.
287
288                 CC_REDISPLAY  Redisplay entire input line.  This is useful if
289                               a key binding outputs extra information.
290
291                 CC_ERROR      An error occurred.  Beep, and flush tty.
292
293                 CC_FATAL      Fatal error, reset tty to known state.
294
295           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
300           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
307           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
312           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
319           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
323           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
327     el_get()
328           Get editline parameters.  op determines which parameter to retrieve
329           into result.  Returns 0 if successful, -1 otherwise.
330
331           The following values for op are supported, along with actual type
332           of result:
333
334           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
339           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
344           EL_EDITOR, const char **
345                 Return the name of the editor, which will be one of “emacs”
346                 or “vi”.
347
348           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
352           EL_SIGNAL, int *
353                 Return non-zero if editline has installed private signal han‐
354                 dlers (see el_get() above).
355
356           EL_EDITMODE, int *
357                 Return non-zero if editing is enabled.
358
359           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
364           EL_CLIENTDATA, void **data
365                 Retrieve data previously registered with the corresponding
366                 el_set() call.
367
368           EL_UNBUFFERED, int
369                 Return non-zero if unbuffered mode is enabled.
370
371           EL_PREP_TERM, int
372                 Sets or clears terminal editing mode.
373
374           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
378     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
384     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
390     el_line()
391           Return the editing information for the current line in a LineInfo
392           structure, which is defined as follows:
393
394           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
400           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
405     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
409     el_deletestr()
410           Delete count characters before the cursor.
411

HISTORY LIST FUNCTIONS

413     The history functions use a common data structure, History, which is cre‐
414     ated by history_init() and freed by history_end().
415
416     The following functions are available:
417
418     history_init()
419           Initialise the history list, and return a data structure to be used
420           by all other history list functions.
421
422     history_end()
423           Clean up and finish with h, assumed to have been created with
424           history_init().
425
426     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
432           H_SETSIZE, int size
433                 Set size of history to size elements.
434
435           H_GETSIZE
436                 Get number of events currently in history.
437
438           H_END
439                 Cleans up and finishes with h, assumed to be created with
440                 history_init().
441
442           H_CLEAR
443                 Clear the history.
444
445           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
452           H_FIRST
453                 Return the first element in the history.
454
455           H_LAST
456                 Return the last element in the history.
457
458           H_PREV
459                 Return the previous element in the history.
460
461           H_NEXT
462                 Return the next element in the history.
463
464           H_CURR
465                 Return the current element in the history.
466
467           H_SET
468                 Set the cursor to point to the requested element.
469
470           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
475           H_APPEND, const char *str
476                 Append str to the last new element of the history.
477
478           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
488           H_PREV_STR, const char *str
489                 Return the closest previous event that starts with str.
490
491           H_NEXT_STR, const char *str
492                 Return the closest next event that starts with str.
493
494           H_PREV_EVENT, int e
495                 Return the previous event numbered e.
496
497           H_NEXT_EVENT, int e
498                 Return the next event numbered e.
499
500           H_LOAD, const char *file
501                 Load the history list stored in file.
502
503           H_SAVE, const char *file
504                 Save the history list to file.
505
506           H_SETUNIQUE, int unique
507                 Set flag that adjacent identical event strings should not be
508                 entered into the history.
509
510           H_GETUNIQUE
511                 Retrieve the current setting if adjacent identical elements
512                 should be entered into the history.
513
514           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
519           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

TOKENIZATION FUNCTIONS

524     The tokenization functions use a common data structure, Tokenizer, which
525     is created by tok_init() and freed by tok_end().
526
527     The following functions are available:
528
529     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
534     tok_end()
535           Clean up and finish with t, assumed to have been created with
536           tok_init().
537
538     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
543     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
549           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
554     tok_str()
555           A simpler form of tok_line(); str is a NUL terminated string to
556           tokenize.
557

SEE ALSO

559     sh(1), signal(3), termcap(3), editrc(5), termcap(5)
560

HISTORY

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

AUTHORS

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

BUGS

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.
578
579BSD                           September 11, 2012                           BSD
Impressum