EDITLINE(3) | Library Functions Manual | EDITLINE(3) |
editline
, el_init
,
el_end
, el_reset
,
el_gets
, el_wgets
,
el_getc
, el_wgetc
,
el_push
, el_wpush
,
el_parse
, el_wparse
,
el_set
, el_wset
,
el_get
, el_wget
,
el_source
, el_resize
,
el_line
, el_wline
,
el_insertstr
, el_winsertstr
,
el_deletestr
, el_wdeletestr
,
history_init
, history_winit
,
history_end
, history_wend
,
history
, history_w
,
tok_init
, tok_winit
,
tok_end
, tok_wend
,
tok_reset
, tok_wreset
,
tok_line
, tok_wline
,
tok_str
tok_wstr
—
line editor, history and tokenization functions
Command Line Editor Library (libedit, -ledit)
#include
<histedit.h>
EditLine *
el_init
(const
char *prog, FILE
*fin, FILE *fout,
FILE *ferr);
void
el_end
(EditLine
*e);
void
el_reset
(EditLine
*e);
const char *
el_gets
(EditLine
*e, int
*count);
const wchar_t *
el_wgets
(EditLine
*e, int
*count);
int
el_getc
(EditLine
*e, char *ch);
int
el_wgetc
(EditLine
*e, wchar_t
*ch);
void
el_push
(EditLine
*e, const char
*str);
void
el_wpush
(EditLine
*e, const wchar_t
*str);
int
el_parse
(EditLine
*e, int argc,
const char *argv[]);
int
el_wparse
(EditLine
*e, int argc,
const wchar_t
*argv[]);
int
el_set
(EditLine
*e, int op,
...);
int
el_wset
(EditLine
*e, int op,
...);
int
el_get
(EditLine
*e, int op,
...);
int
el_wget
(EditLine
*e, int op,
...);
int
el_source
(EditLine
*e, const char
*file);
void
el_resize
(EditLine
*e);
const LineInfo *
el_line
(EditLine
*e);
int
el_insertstr
(EditLine
*e, const char
*str);
int
el_winsertstr
(EditLine
*e, const wchar_t
*str);
void
el_deletestr
(EditLine
*e, int count);
void
el_wdeletestr
(EditLine
*e, int count);
History *
history_init
();
HistoryW *
history_winit
();
void
history_end
(History
*h);
void
history_wend
(HistoryW
*h);
int
history
(History
*h, HistEvent *ev,
int op,
...);
int
history_w
(HistoryW
*h, HistEventW *ev,
int op,
...);
Tokenizer *
tok_init
(const
char *IFS);
TokenizerW *
tok_winit
(const
wchar_t *IFS);
void
tok_end
(Tokenizer
*t);
void
tok_wend
(TokenizerW
*t);
void
tok_reset
(Tokenizer
*t);
void
tok_wreset
(TokenizerW
*t);
int
tok_line
(Tokenizer
*t, const LineInfo
*li, int *argc,
const char **argv[],
int *cursorc,
int *cursoro);
int
tok_wline
(TokenizerW
*t, const LineInfoW
*li, int *argc,
const wchar_t **argv[],
int *cursorc,
int *cursoro);
int
tok_str
(Tokenizer
*t, const char
*str, int *argc,
const char **argv[]);
int
tok_wstr
(TokenizerW
*t, const wchar_t
*str, int *argc,
const wchar_t
**argv[]);
The editline
library provides generic line
editing, history and tokenization functions, similar to those found in
sh(1).
These functions are available in the
libedit
library (which needs the
libtermcap
library). Programs should be linked with
-ledit
-ltermcap
.
The line editing functions use a common data structure,
EditLine, which is created by
el_init
()
and freed by
el_end
().
The wide-character functions behave the same way as their narrow counterparts.
The following functions are available:
el_init
()el_end
()el_init
().el_reset
()el_gets
()NULL
if no characters were read or
if an error occurred. If an error occurred, count is
set to -1 and errno
contains the error code that
caused it. The return value may not remain valid across calls to
el_gets
() and must be copied if the data is to be
retained.el_getc
()errno
can
be inspected for the cause.el_push
()bind
-s
in
editrc(5) for more information.el_parse
()editline
commands. If the command is prefixed with
“prog”: then el_parse
() will only
execute the command if “prog” matches the
prog argument supplied to
el_init
(). The return value is -1 if the command
is unknown, 0 if there was no error or “prog” didn't match,
or 1 if the command returned an error. Refer to
editrc(5) for more information.el_set
()editline
parameters. op
determines which parameter to set, and each operation has its own
parameter list.
The following values for op are supported, along with the required argument list:
EL_PROMPT
,
char *(*f)(EditLine *)EL_PROMPT_ESC
,
char *(*f)(EditLine *), char
cEL_PROMPT
, but the
c argument indicates the start/stop literal
prompt character.
If a start/stop literal character is found in the prompt,
the character itself is not printed, but characters after it are
printed directly to the terminal without affecting the state of the
current line. A subsequent second start/stop literal character ends
this behavior. This is typically used to embed literal escape
sequences that change the color/style of the terminal in the prompt.
0
unsets it.
EL_REFRESH
EL_RPROMPT
,
char *(*f)(EditLine *)EL_RPROMPT_ESC
,
char *(*f)(EditLine *), char
cEL_TERMINAL
,
const char *typeTERM
if type is
NULL
.EL_EDITOR
,
const char *modeEL_SIGNAL
,
int flageditline
will install its own signal handler
for the following signals when reading command input:
SIGCONT
, SIGHUP
,
SIGINT
, SIGQUIT
,
SIGSTOP
, SIGTERM
,
SIGTSTP
, and SIGWINCH
.
Otherwise, the current signal handlers will be used.EL_BIND
,
const char *, ...,
NULL
bind
builtin command. Refer to
editrc(5) for more
information.EL_ECHOTC
,
const char *, ...,
NULL
echotc
builtin command. Refer to
editrc(5) for more
information.EL_SETTC
,
const char *, ...,
NULL
settc
builtin command. Refer to
editrc(5) for more
information.EL_SETTY
,
const char *, ...,
NULL
setty
builtin command. Refer to
editrc(5) for more
information.EL_TELLTC
,
const char *, ...,
NULL
telltc
builtin command. Refer to
editrc(5) for more
information.EL_ADDFN
,
const char *name, const char
*help, unsigned char (*func)(EditLine *e, int
ch)func
(),
referred to as name which is invoked when a key
which is bound to name is entered.
help is a description of
name. At invocation time,
ch is the key which caused the invocation. The
return value of func
() should be one of:
CC_NORM
CC_NEWLINE
CC_EOF
CC_ARGHACK
CC_REFRESH
CC_REFRESH_BEEP
CC_CURSOR
CC_REFRESH
.CC_REDISPLAY
CC_ERROR
CC_FATAL
EL_HIST
,
History *(*func)(History *, int op, ...),
const char *ptrhistory
(). ptr should be
the value returned by history_init
().EL_EDITMODE
,
int flageditline
. At this time, it is
the caller's responsibility to check this (using
el_get
()) to determine if editing should be
enabled or not.EL_UNBUFFERED
,
int flagel_gets
()
will return immediately after processing a single character.EL_GETCFN
,
int (*f)(EditLine *, char *c)el_gets
() and
el_getc
(). The builtin function can be set or
restored with the special function name
“EL_BUILTIN_GETCFN
”.EL_CLIENTDATA
,
void *datael_get
() call.EL_SETFP
,
int fd, FILE *fpeditline
file pointer for
“input” fd =
0
, “output”
fd = 1
, or
“error” fd =
2
from fp.el_get
()editline
parameters. op
determines which parameter to retrieve into result.
Returns 0 if successful, -1 otherwise.
The following values for op are supported, along with actual type of result:
EL_PROMPT
,
char *(*f)(EditLine *), char
*cNULL
, return the start/stop literal prompt
character in it.EL_RPROMPT
,
char *(*f)(EditLine *), char
*cNULL
, return the start/stop literal prompt
character in it.EL_EDITOR
,
const char **EL_GETTC
,
const char *name, void
*valueEL_SIGNAL
,
int *editline
has installed
private signal handlers (see
el_get
()
above).EL_EDITMODE
,
int *EL_GETCFN
,
int (**f)(EditLine *, char *)EL_BUILTIN_GETCFN
” in the
case of the default builtin function.EL_CLIENTDATA
,
void **datael_set
()
call.EL_UNBUFFERED
,
intEL_PREP_TERM
,
intEL_GETFP
,
int fd, FILE **fpeditline
file pointer for
“input” fd =
0
, “output”
fd = 1
, or
“error” fd =
2
.el_source
()editline
by reading the contents of
file.
el_parse
()
is called for each line in file. If
file is NULL
, try
$PWD/.editrc then
$HOME/.editrc. Refer to
editrc(5) for details on the format
of file.el_resize
()EL_SIGNAL
has been set with
el_set
(), then this is done automatically.
Otherwise, it's the responsibility of the application to call
el_resize
() on the appropriate occasions.el_line
()typedef struct lineinfo { const char *buffer; /* address of buffer */ const char *cursor; /* address of cursor */ const char *lastchar; /* address of last character */ } LineInfo;
buffer is not NUL
terminated. This function may be called after
el_gets
()
to obtain the LineInfo structure pertaining to
line returned by that function, and from within user defined functions
added with EL_ADDFN
.
el_insertstr
()el_deletestr
()The history functions use a common data structure,
History, which is created by
history_init
() and freed by
history_end
().
The following functions are available:
history_init
()history_end
()history_init
().history
()H_SETSIZE
,
int sizeH_GETSIZE
H_END
history_init
().H_CLEAR
H_FUNC
,
void *ptr, history_gfun_t
first, history_gfun_t next,
history_gfun_t last,
history_gfun_t prev,
history_gfun_t curr,
history_sfun_t set, history_vfun_t
clear, history_efun_t enter,
history_efun_t addH_FIRST
H_LAST
H_PREV
H_NEXT
H_CURR
H_SET
H_ADD
,
const char *strH_ENTER
operation with
argument str if there is no current
element.H_APPEND
,
const char *strH_ENTER
,
const char *strH_SETUNIQUE
was has been called with
a non-zero arguments, the element will not be entered into the history
if its contents match the ones of the current history element. If the
element is entered history
() returns 1, if it
is ignored as a duplicate returns 0. Finally
history
() returns -1 if an error
occurred.H_PREV_STR
,
const char *strH_NEXT_STR
,
const char *strH_PREV_EVENT
,
int eH_NEXT_EVENT
,
int eH_LOAD
,
const char *fileH_SAVE
,
const char *fileH_SETUNIQUE
,
int uniqueH_GETUNIQUE
H_DEL
,
int ehistory
()
returns >= 0 if the operation op succeeds.
Otherwise, -1 is returned and ev is updated to
contain more details about the error.
The tokenization functions use a common data structure,
Tokenizer, which is created by
tok_init
() and freed by
tok_end
().
The following functions are available:
tok_init
()NULL
.tok_end
()tok_init
().tok_reset
()tok_line
() or
tok_str
() and before a new line is to be
tokenized.tok_line
()NULL
) to
contain the index of the word containing the cursor, and
cursoro (if not NULL
) to
contain the offset within argv[cursorc] of the
cursor.
Returns 0 if successful, -1 for an internal error, 1 for an unmatched single quote, 2 for an unmatched double quote, and 3 for a backslash quoted ⟨newline⟩. A positive exit code indicates that another line should be read and tokenization attempted again.
tok_str
()tok_line
();
str is a NUL terminated string to tokenize.The editline
library first appeared in
4.4BSD. CC_REDISPLAY
appeared in NetBSD 1.3.
CC_REFRESH_BEEP
, EL_EDITMODE
and the readline emulation appeared in NetBSD 1.4.
EL_RPROMPT
appeared in NetBSD
1.5.
The editline
library was written by
Christos Zoulas. Luke Mewburn wrote this manual and implemented
CC_REDISPLAY
,
CC_REFRESH_BEEP
,
EL_EDITMODE
, and EL_RPROMPT
.
Jaromir Dolecek implemented the readline emulation. Johny Mattsson
implemented wide-character support.
At this time, it is the responsibility of the caller to check the
result of the EL_EDITMODE
operation of
el_get
() (after an
el_source
() or el_parse
())
to determine if editline
should be used for further
input. I.e., EL_EDITMODE
is purely an indication of
the result of the most recent editrc(5)
edit
command.
September 11, 2012 | macOS 14.6 |