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

NAME

6       editline,   el_init,   el_end,  el_reset,  el_gets,  el_getc,  el_push,
7       el_parse, el_set, el_get, el_source, el_resize, el_line,  el_insertstr,
8       el_deletestr,  history_init,  history_end,  history, tok_init, tok_end,
9       tok_reset, tok_line, tok_str - line editor,  history  and  tokenization
10       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       int
31       el_getc(EditLine *e, char *ch);
32
33       void
34       el_push(EditLine *e, const char *str);
35
36       int
37       el_parse(EditLine *e, int argc, const char *argv[]);
38
39       int
40       el_set(EditLine *e, int op, ...);
41
42       int
43       el_get(EditLine *e, int op, ...);
44
45       int
46       el_source(EditLine *e, const char *file);
47
48       void
49       el_resize(EditLine *e);
50
51       const LineInfo *
52       el_line(EditLine *e);
53
54       int
55       el_insertstr(EditLine *e, const char *str);
56
57       void
58       el_deletestr(EditLine *e, int count);
59
60       History *
61       history_init();
62
63       void
64       history_end(History *h);
65
66       int
67       history(History *h, HistEvent *ev, int op, ...);
68
69       Tokenizer *
70       tok_init(const char *IFS);
71
72       void
73       tok_end(Tokenizer *t);
74
75       void
76       tok_reset(Tokenizer *t);
77
78       int
79       tok_line(Tokenizer  *t,  const  LineInfo  *li,  int  *argc,  const char
80       **argv[], int *cursorc, int *cursoro);
81
82       int
83       tok_str(Tokenizer *t, const char *str, int *argc, const char **argv[]);
84

DESCRIPTION

86       The editline library provides generic line editing,  history  and  tok‐
87       enization functions, similar to those found in sh(1).
88
89       These  functions  are available in the libedit library (which needs the
90       libcurses library).  Programs should be linked with -ledit -lcurses.
91

LINE EDITING FUNCTIONS

93       The line editing functions use a common data structure, EditLine, which
94       is created by el_init() and freed by el_end().
95
96       The following functions are available:
97
98       el_init()
99              Initialise  the  line  editor, and return a data structure to be
100              used by all other line editing functions.  prog is the  name  of
101              the  invoking  program,  used when reading the editrc(5) file to
102              determine which settings to use.  fin, fout  and  ferr  are  the
103              input, output, and error streams (respectively) to use.  In this
104              documentation, references to ``the tty'' are  actually  to  this
105              input/output stream combination.
106
107       el_end()
108              Clean  up  and  finish with e, assumed to have been created with
109              el_init().
110
111       el_reset()
112              Reset the tty and the parser.  This should be  called  after  an
113              error which may have upset the tty's state.
114
115       el_gets()
116              Read a line from the tty.  count is modified to contain the num‐
117              ber of characters read.  Returns the line read if successful, or
118              NULL  if no characters were read or if an error occurred.  If an
119              error occurred, count is set to -1 and errno contains the  error
120              code  that  caused  it.   The  return value may not remain valid
121              across calls to el_gets() and must be copied if the data  is  to
122              be retained.
123
124       el_getc()
125              Read  a  character  from the tty.  ch is modified to contain the
126              character read.  Returns the number of characters read  if  suc‐
127              cessful, -1 otherwise.
128
129       el_push()
130              Pushes  str  back  onto  the  input stream.  This is used by the
131              macro expansion mechanism.  Refer to the description of bind  -s
132              in editrc(5) for more information.
133
134       el_parse()
135              Parses  the  argv array (which is argc elements in size) to exe‐
136              cute builtin editline commands.  If the command is prefixed with
137              ``prog  :''  then  el_parse()  will  only execute the command if
138              ``prog'' matches the prog argument supplied to  el_init().   The
139              return  value is -1 if the command is unknown, 0 if there was no
140              error or ``prog'' didn't match, or 1 if the command returned  an
141              error.  Refer to editrc(5) for more information.
142
143       el_set()
144              Set  editline parameters.  op determines which parameter to set,
145              and each operation has its own parameter list.
146
147              The following values  for  op  are  supported,  along  with  the
148              required argument list:
149
150              EL_PROMPT , char *(*f)(EditLine *)
151                     Define  prompt printing function as f, which is to return
152                     a string that contains the prompt.
153
154              EL_PROMPT_ESC , char *(*f)(EditLine *), Fa char c
155                     Same as EL_PROMPT , but  the  c  argument  indicates  the
156                     start/stop literal prompt character.
157
158                     If a start/stop literal character is found in the prompt,
159                     the character itself is not printed, but characters after
160                     it are printed directly to the terminal without affecting
161                     the state of  the  current  line.   A  subsequent  second
162                     start/stop literal character ends this behavior.  This is
163                     typically used to embed  literal  escape  sequences  that
164                     change  the color/style of the terminal in the prompt.  0
165                     unsets it.
166
167              EL_REFRESH
168                     Re-display the current line on the next terminal line.
169
170              EL_RPROMPT , char *(*f)(EditLine *)
171                     Define right side prompt printing function as f, which is
172                     to return a string that contains the prompt.
173
174              EL_RPROMPT_ESC , char *(*f)(EditLine *), Fa char c
175                     Define the right prompt printing function but with a lit‐
176                     eral escape character.
177
178              EL_TERMINAL , const char *type
179                     Define terminal type of the tty to be type, or to TERM if
180                     type is NULL .
181
182              EL_EDITOR , const char *mode
183                     Set  editing mode to mode, which must be one of ``emacs''
184                     or ``vi''.
185
186              EL_SIGNAL , int flag
187                     If flag is non-zero, editline will install its own signal
188                     handler  for  the  following signals when reading command
189                     input: SIGCONT , SIGHUP , SIGINT , SIGQUIT  ,  SIGSTOP  ,
190                     SIGTERM  ,  SIGTSTP , and SIGWINCH .  Otherwise, the cur‐
191                     rent signal handlers will be used.
192
193              EL_BIND , const char *, Fa ..., Dv NULL
194                     Perform the bind builtin command.  Refer to editrc(5) for
195                     more information.
196
197              EL_ECHOTC , const char *, Fa ..., Dv NULL
198                     Perform  the  echotc builtin command.  Refer to editrc(5)
199                     for more information.
200
201              EL_SETTC , const char *, Fa ..., Dv NULL
202                     Perform the settc builtin command.   Refer  to  editrc(5)
203                     for more information.
204
205              EL_SETTY , const char *, Fa ..., Dv NULL
206                     Perform  the  setty  builtin command.  Refer to editrc(5)
207                     for more information.
208
209              EL_TELLTC , const char *, Fa ..., Dv NULL
210                     Perform the telltc builtin command.  Refer  to  editrc(5)
211                     for more information.
212
213              EL_ADDFN , const char *name, Fa const char *help,
214                     Fa  "unsigned  char  (*func)(EditLine  *e, int ch)" Add a
215                     user defined function, func(), referred to as name  which
216                     is  invoked when a key which is bound to name is entered.
217                     help is a description of name.  At invocation time, ch is
218                     the key which caused the invocation.  The return value of
219                     func() should be one of:
220
221                     CC_NORM
222                            Add a normal character.
223
224                     CC_NEWLINE
225                            End of line was entered.
226
227                     CC_EOF EOF was entered.
228
229                     CC_ARGHACK
230                            Expecting further command input as  arguments,  do
231                            nothing visually.
232
233                     CC_REFRESH
234                            Refresh display.
235
236                     CC_REFRESH_BEEP
237                            Refresh display, and beep.
238
239                     CC_CURSOR
240                            Cursor moved, so update and perform CC_REFRESH .
241
242                     CC_REDISPLAY
243                            Redisplay  entire input line.  This is useful if a
244                            key binding outputs extra information.
245
246                     CC_ERROR
247                            An error occurred.  Beep, and flush tty.
248
249                     CC_FATAL
250                            Fatal error, reset tty to known state.
251
252              EL_HIST , History *(*func)(History *, int op, ...),
253                     Fa "const char *ptr" Defines which  history  function  to
254                     use, which is usually history().  ptr should be the value
255                     returned by history_init().
256
257              EL_EDITMODE , int flag
258                     If flag is non-zero, editing is  enabled  (the  default).
259                     Note that this is only an indication, and does not affect
260                     the operation of .  At this  time,  it  is  the  caller's
261                     responsibility  to check this (using el_get() ) to deter‐
262                     mine if editing should be enabled or not.
263
264              EL_GETCFN , int (*f)(EditLine *, char *c)
265                     Define the character reading function as f, which  is  to
266                     return the number of characters read and store them in c.
267                     This function  is  called  internally  by  el_gets()  and
268                     el_getc().   The  builtin function can be set or restored
269                     with the special function name ``Dv EL_BUILTIN_GETCFN''.
270
271              EL_CLIENTDATA , void *data
272                     Register data to be associated with this EditLine  struc‐
273                     ture.    It  can  be  retrieved  with  the  corresponding
274                     el_get() call.
275
276              EL_SETFP , int fd, Fa FILE *fp
277                     Set the current editline file pointer for ``input'' fd  =
278                     0 , ``output'' fd = 1 , or ``error'' fd = 2 from fp.
279
280       el_get()
281              Get  editline  parameters.   op  determines  which  parameter to
282              retrieve into result.  Returns 0 if successful, -1 otherwise.
283
284              The following values for op are  supported,  along  with  actual
285              type of result :
286
287              EL_PROMPT , char *(*f)(EditLine *), Fa char *c
288                     Return a pointer to the function that displays the prompt
289                     in f.  If c is not NULL , return the  start/stop  literal
290                     prompt character in it.
291
292              EL_RPROMPT , char *(*f)(EditLine *), Fa char *c
293                     Return a pointer to the function that displays the prompt
294                     in f.  If c is not NULL , return the  start/stop  literal
295                     prompt character in it.
296
297              EL_EDITOR , const char *
298                     Return  the  name  of  the  editor,  which will be one of
299                     ``emacs'' or ``vi''.
300
301              EL_GETTC , const char *name, Fa void *value
302                     Return non-zero if name is a valid termcap(5)  capability
303                     and set value to the current value of that capability.
304
305              EL_SIGNAL , int *
306                     Return  non-zero if editline has installed private signal
307                     handlers (see el_get() above).
308
309              EL_EDITMODE , int *
310                     Return non-zero if editing is enabled.
311
312              EL_GETCFN , int (**f)(EditLine *, char *)
313                     Return a pointer to the function  that  read  characters,
314                     which is equal to ``Dv EL_BUILTIN_GETCFN'' in the case of
315                     the default builtin function.
316
317              EL_CLIENTDATA , void **data
318                     Retrieve data previously registered with the  correspond‐
319                     ing el_set() call.
320
321              EL_UNBUFFERED , int
322                     Sets  or clears unbuffered mode.  In this mode, el_gets()
323                     will return immediately after processing a single charac‐
324                     ter.
325
326              EL_PREP_TERM , int
327                     Sets or clears terminal editing mode.
328
329              EL_GETFP , int fd", Fa FILE **fp
330                     Return  in  fp  the  current  editline  file  pointer for
331                     ``input'' fd = 0 , ``output'' fd = 1 , or ``error'' fd  =
332                     2 .
333
334       el_source()
335              Initialise editline by reading the contents of file.  el_parse()
336              is called for each  line  in  file.   If  file  is  NULL  ,  try
337              $PWD/.editrc then $HOME/.editrc.  Refer to editrc(5) for details
338              on the format of file.
339
340       el_resize()
341              Must be called if the terminal size changes.  If  EL_SIGNAL  has
342              been set with el_set(), then this is done automatically.  Other‐
343              wise,  it's  the  responsibility  of  the  application  to  call
344              el_resize() on the appropriate occasions.
345
346       el_line()
347              Return  the  editing information for the current line in a Line‐
348              Info structure, which is defined as follows:
349
350              typedef struct lineinfo {
351                  const char *buffer;    /* address of buffer */
352                  const char *cursor;    /* address of cursor */
353                  const char *lastchar;  /* address of last character */
354              } LineInfo;
355
356              buffer is not NUL terminated.  This function may be called after
357              el_gets()  to  obtain  the LineInfo structure pertaining to line
358              returned by that function, and from within  user  defined  func‐
359              tions added with EL_ADDFN .
360
361       el_insertstr()
362              Insert  str  into  the line at the cursor.  Returns -1 if str is
363              empty or won't fit, and 0 otherwise.
364
365       el_deletestr()
366              Delete count characters before the cursor.
367

HISTORY LIST FUNCTIONS

369       The history functions use a common data structure,  History,  which  is
370       created by history_init() and freed by history_end().
371
372       The following functions are available:
373
374       history_init()
375              Initialise  the  history list, and return a data structure to be
376              used by all other history list functions.
377
378       history_end()
379              Clean up and finish with h, assumed to have  been  created  with
380              history_init().
381
382       history()
383              Perform  operation  op  on the history list, with optional argu‐
384              ments as needed by the operation.  ev is changed accordingly  to
385              operation.   The  following  values  for op are supported, along
386              with the required argument list:
387
388              H_SETSIZE , int size
389                     Set size of history to size elements.
390
391              H_GETSIZE
392                     Get number of events currently in history.
393
394              H_END  Cleans up and finishes with h, assumed to be created with
395                     history_init().
396
397              H_CLEAR
398                     Clear the history.
399
400              H_FUNC , void *ptr, Fa history_gfun_t first,
401                     Fa  "history_gfun_t next" , Fa "history_gfun_t last" , Fa
402                     "history_gfun_t prev" , Fa  "history_gfun_t  curr"  ,  Fa
403                     "history_sfun_t  set"  ,  Fa  "history_vfun_t clear" , Fa
404                     "history_efun_t enter" , Fa "history_efun_t  add"  Define
405                     functions  to perform various history operations.  ptr is
406                     the argument given to a function when it's invoked.
407
408              H_FIRST
409                     Return the first element in the history.
410
411              H_LAST Return the last element in the history.
412
413              H_PREV Return the previous element in the history.
414
415              H_NEXT Return the next element in the history.
416
417              H_CURR Return the current element in the history.
418
419              H_SET  Set the cursor to point to the requested element.
420
421              H_ADD , const char *str
422                     Append str to the current element of the history, or per‐
423                     form  the H_ENTER operation with argument str if there is
424                     no current element.
425
426              H_APPEND , const char *str
427                     Append str to the last new element of the history.
428
429              H_ENTER , const char *str
430                     Add str as a new element to the history, and,  if  neces‐
431                     sary,  removing  the oldest entry to keep the list to the
432                     created size.  If H_SETUNIQUE was has been called with  a
433                     non-zero  arguments, the element will not be entered into
434                     the history if its contents match the ones of the current
435                     history  element.   If  the  element is entered history()
436                     returns 1, if it is ignored as  a  duplicate  returns  0.
437                     Finally history() returns -1 if an error occurred.
438
439              H_PREV_STR , const char *str
440                     Return the closest previous event that starts with str.
441
442              H_NEXT_STR , const char *str
443                     Return the closest next event that starts with str.
444
445              H_PREV_EVENT , int e
446                     Return the previous event numbered e.
447
448              H_NEXT_EVENT , int e
449                     Return the next event numbered e.
450
451              H_LOAD , const char *file
452                     Load the history list stored in file.
453
454              H_SAVE , const char *file
455                     Save the history list to file.
456
457              H_SETUNIQUE , int unique
458                     Set flag that adjacent identical event strings should not
459                     be entered into the history.
460
461              H_GETUNIQUE
462                     Retrieve the current setting if adjacent  identical  ele‐
463                     ments should be entered into the history.
464
465              H_DEL , int e
466                     Delete  the event numbered e.  This function is only pro‐
467                     vided  for  readline(3)  compatibility.   The  caller  is
468                     responsible  for free'ing the string in the returned His‐
469                     tEvent.
470
471       history() returns = 0 if the operation op succeeds.  Otherwise,  -1  is
472       returned and ev is updated to contain more details about the error.
473

TOKENIZATION FUNCTIONS

475       The  tokenization  functions  use  a  common data structure, Tokenizer,
476       which is created by tok_init() and freed by tok_end().
477
478       The following functions are available:
479
480       tok_init()
481              Initialise the tokenizer, and return a data structure to be used
482              by  all other tokenizer functions.  IFS contains the Input Field
483              Separators, which defaults to <space> , <tab> , and <newline> if
484              NULL .
485
486       tok_end()
487              Clean  up  and  finish with t, assumed to have been created with
488              tok_init().
489
490       tok_reset()
491              Reset the tokenizer state.  Use after a line has  been  success‐
492              fully tokenized by tok_line() or tok_str() and before a new line
493              is to be tokenized.
494
495       tok_line()
496              Tokenize li, If successful, modify: argv to contain  the  words,
497              argc  to  contain the number of words, cursorc (if not NULL ) to
498              contain the index of the word containing the cursor, and cursoro
499              (if not NULL ) to contain the offset within argv[cursorc] of the
500              cursor.
501
502              Returns 0 if successful, -1 for an  internal  error,  1  for  an
503              unmatched  single  quote, 2 for an unmatched double quote, and 3
504              for a backslash quoted <newline .> A positive  exit  code  indi‐
505              cates   that  another  line  should  be  read  and  tokenization
506              attempted again.
507
508       tok_str()
509              A simpler form of tok_line(; ) str is a NUL terminated string to
510              tokenize.
511

SEE ALSO

513       sh(1), signal(3), termcap(3), editrc(5), termcap(5)
514

HISTORY

516       The  editline library first appeared in Bx 4.4 .  CC_REDISPLAY appeared
517       in Nx 1.3 .  CC_REFRESH_BEEP , EL_EDITMODE and the  readline  emulation
518       appeared in Nx 1.4 .  EL_RPROMPT appeared in Nx 1.5 .
519

AUTHORS

521       The  editline  library  was  written  by Christos Zoulas.  Luke Mewburn
522       wrote this manual and  implemented  CC_REDISPLAY  ,  CC_REFRESH_BEEP  ,
523       EL_EDITMODE  ,  and EL_RPROMPT .  Jaromir Dolecek implemented the read‐
524       line emulation.
525

BUGS

527       At this time, it is the responsibility  of  the  caller  to  check  the
528       result  of  the EL_EDITMODE operation of el_get() (after an el_source()
529       or el_parse() ) to determine if editline should  be  used  for  further
530       input.   I.e., EL_EDITMODE is purely an indication of the result of the
531       most recent editrc(5) edit command.
532
533
534
535                                 July 5, 2009                      EDITLINE(3)
Impressum