EDITLINE

NAME

editlineel_initel_init_fdel_endel_resetel_getsel_wgetsel_getcel_wgetcel_pushel_wpushel_parseel_wparseel_setel_wsetel_getel_wgetel_sourceel_resizeel_cursorel_lineel_wlineel_insertstrel_winsertstrel_deletestrel_wdeletestrhistory_inithistory_winithistory_endhistory_wendhistoryhistory_wtok_inittok_winittok_endtok_wendtok_resettok_wresettok_linetok_wlinetok_strtok_wstr
- line editor, history and tokenization functions

DESCRIPTION

The
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

LINE EDITING FUNCTIONS

The line editing functions use a common data structure,
Fa EditLine ,
which is created by
Fn el_init
or
Fn el_init_fd
and freed by
Fn el_end .

The wide-character functions behave the same way as their narrow
counterparts.

The following functions are available:

Fn el_init

Initialise the line editor, and return a data structure
to be used by all other line editing functions.
Fa prog
is the name of the invoking program, used when reading the
editrc(5)
file to determine which settings to use.
Fa fin ,
Fa fout
and
Fa ferr
are the input, output, and error streams (respectively) to use.
In this documentation, references to
``the tty''
are actually to this input/output stream combination.

Fn el_init_fd

Like
Fn el_init
but allows specifying file descriptors for the
stdio(3)
corresponding streams, in case those were created with
funopen(3).

Fn el_end

Clean up and finish with
Fa e ,
assumed to have been created with
Fn el_init
or
Fn el_init_fd .

Fn el_reset

Reset the tty and the parser.
This should be called after an error which may have upset the tty's
state.

Fn el_gets

Read a line from the tty.
Fa count
is modified to contain the number of characters read.
Returns the line read if successful, or
NULL
if no characters were read or if an error occurred.
If an error occurred,
Fa count
is set to -1 and
errno
contains the error code that caused it.
The return value may not remain valid across calls to
Fn el_gets
and must be copied if the data is to be retained.

Fn el_getc

Read a character from the tty.
Fa ch
is modified to contain the character read.
Returns the number of characters read if successful, -1 otherwise,
in which case
errno
can be inspected for the cause.

Fn el_push

Pushes
Fa str
back onto the input stream.
This is used by the macro expansion mechanism.
Refer to the description of
bind
-s
in
editrc(5)
for more information.

Fn el_parse

Parses the
Fa argv
array (which is
Fa argc
elements in size)
to execute builtin
commands.
If the command is prefixed with
``prog''
then
Fn el_parse
will only execute the command if
``prog''
matches the
Fa prog
argument supplied to
Fn 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.

Fn el_set

Set
parameters.
Fa op
determines which parameter to set, and each operation has its
own parameter list.

The following values for
Fa op
are supported, along with the required argument list:

EL_PROMPT , Fa char *(*f)(EditLine *)

Define prompt printing function as
Fa f ,
which is to return a string that contains the prompt.

EL_PROMPT_ESC , Fa char *(*f)(EditLine *) , Fa char c

Same as
EL_PROMPT
but the
Fa 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

Re-display the current line on the next terminal line.

EL_RPROMPT , Fa char *(*f)(EditLine *)

Define right side prompt printing function as
Fa f ,
which is to return a string that contains the prompt.

EL_RPROMPT_ESC , Fa char *(*f)(EditLine *) , Fa char c

Define the right prompt printing function but with a literal escape character.

EL_TERMINAL , Fa const char *type

Define terminal type of the tty to be
Fa type ,
or to
TERM
if
Fa type
is
NULL

EL_EDITOR , Fa const char *mode

Set editing mode to
Fa mode ,
which must be one of
``emacs''
or
``vi''

EL_SIGNAL , Fa int flag

If
Fa flag
is non-zero,
will install its own signal handler for the following signals when
reading command input:
SIGCONTSIGHUPSIGINTSIGQUITSIGSTOPSIGTERMSIGTSTP
and
SIGWINCH
Otherwise, the current signal handlers will be used.

EL_BIND , Fa const char * , Fa ... , NULL

Perform the
bind
builtin command.
Refer to
editrc(5)
for more information.

EL_ECHOTC , Fa const char * , Fa ... , NULL

Perform the
echotc
builtin command.
Refer to
editrc(5)
for more information.

EL_SETTC , Fa const char * , Fa ... , NULL

Perform the
settc
builtin command.
Refer to
editrc(5)
for more information.

EL_SETTY , Fa const char * , Fa ... , NULL

Perform the
setty
builtin command.
Refer to
editrc(5)
for more information.

EL_TELLTC , Fa const char * , Fa ... , NULL

Perform the
telltc
builtin command.
Refer to
editrc(5)
for more information.

EL_ADDFN , Fa const char *name , Fa const char *help

Fa "unsigned char (*func)(EditLine *e, int ch)"
Add a user defined function,
Fn func ,
referred to as
Fa name
which is invoked when a key which is bound to
Fa name
is entered.
Fa help
is a description of
Fa name .
At invocation time,
Fa ch
is the key which caused the invocation.
The return value of
Fn func
should be one of:

Fa "const char *ptr"
Defines which history function to use, which is usually
Fn history .
Fa ptr
should be the value returned by
Fn history_init .

EL_EDITMODE , Fa int flag

If
Fa flag
is non-zero,
editing is enabled (the default).
Note that this is only an indication, and does not
affect the operation of
.
At this time, it is the caller's responsibility to
check this
(using
Fn el_get )
to determine if editing should be enabled or not.

EL_UNBUFFERED , Fa int flag

If
Fa flag
is zero,
unbuffered mode is disabled (the default).
In unbuffered mode,
Fn el_gets
will return immediately after processing a single character.

EL_GETCFN , Fa int (*f)(EditLine *, char *c)

Define the character reading function as
Fa f ,
which is to return the number of characters read and store them in
Fa c .
This function is called internally by
Fn el_gets
and
Fn el_getc .
The builtin function can be set or restored with the special function
name
``EL_BUILTIN_GETCFN
''

EL_CLIENTDATA , Fa void *data

Register
Fa data
to be associated with this EditLine structure.
It can be retrieved with the corresponding
Fn el_get
call.

Initialise
by reading the contents of
Fa file .
Fn el_parse
is called for each line in
Fa file .
If
Fa file
is
NULL
try
$HOME/.editrc
Refer to
editrc(5)
for details on the format of
Fa file .

Fn el_resize

Must be called if the terminal size changes.
If
EL_SIGNAL
has been set with
Fn el_set ,
then this is done automatically.
Otherwise, it's the responsibility of the application to call
Fn el_resize
on the appropriate occasions.

Fn el_cursor

Move the cursor to the right (if positive) or to the left (if negative)
Fa count
characters.
Returns the resulting offset of the cursor from the beginning of the line.

Fn el_line

Return the editing information for the current line in a
Fa LineInfo
structure, which is defined as follows:

Fa buffer
is not NUL terminated.
This function may be called after
Fn el_gets
to obtain the
Fa LineInfo
structure pertaining to line returned by that function,
and from within user defined functions added with
EL_ADDFN

Fn el_insertstr

Insert
Fa str
into the line at the cursor.
Returns -1 if
Fa str
is empty or won't fit, and 0 otherwise.

Fn el_deletestr

Delete
Fa count
characters before the cursor.

HISTORY LIST FUNCTIONS

The history functions use a common data structure,
Fa History ,
which is created by
Fn history_init
and freed by
Fn history_end .

The following functions are available:

Fn history_init

Initialise the history list, and return a data structure
to be used by all other history list functions.

Fn history_end

Clean up and finish with
Fa h ,
assumed to have been created with
Fn history_init .

Fn history

Perform operation
Fa op
on the history list, with optional arguments as needed by the
operation.
Fa ev
is changed accordingly to operation.
The following values for
Fa op
are supported, along with the required argument list:

H_SETSIZE , Fa int size

Set size of history to
Fa size
elements.

H_GETSIZE

Get number of events currently in history.

H_END

Cleans up and finishes with
Fa h ,
assumed to be created with
Fn history_init .

Append
Fa str
to the current element of the history, or perform the
H_ENTER
operation with argument
Fa str
if there is no current element.

H_APPEND , Fa const char *str

Append
Fa str
to the last new element of the history.

H_ENTER , Fa const char *str

Add
Fa str
as a new element to the history, and, if necessary,
removing the oldest entry to keep the list to the created size.
If
H_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
Fn history
returns 1, if it is ignored as a duplicate returns 0.
Finally
Fn history
returns -1 if an error occurred.

H_PREV_STR , Fa const char *str

Return the closest previous event that starts with
Fa str .

H_NEXT_STR , Fa const char *str

Return the closest next event that starts with
Fa str .

H_PREV_EVENT , Fa int e

Return the previous event numbered
Fa e .

H_NEXT_EVENT , Fa int e

Return the next event numbered
Fa e .

H_LOAD , Fa const char *file

Load the history list stored in
Fa file .

H_SAVE , Fa const char *file

Save the history list to
Fa file .

H_SETUNIQUE , Fa int unique

Set flag that adjacent identical event strings should not be entered
into the history.

H_GETUNIQUE

Retrieve the current setting if adjacent identical elements should
be entered into the history.

H_DEL , Fa int e

Delete the event numbered
Fa e .
This function is only provided for
readline(3)
compatibility.
The caller is responsible for free'ing the string in the returned
Fa HistEvent .

Fn history
returns Gt]= 0 if the operation
Fa op
succeeds.
Otherwise, -1 is returned and
Fa ev
is updated to contain more details about the error.

TOKENIZATION FUNCTIONS

The tokenization functions use a common data structure,
Fa Tokenizer ,
which is created by
Fn tok_init
and freed by
Fn tok_end .

The following functions are available:

Fn tok_init

Initialise the tokenizer, and return a data structure
to be used by all other tokenizer functions.
Fa IFS
contains the Input Field Separators, which defaults to
Aq space ,
Aq tab ,
and
Aq newline
if
NULL

Fn tok_end

Clean up and finish with
Fa t ,
assumed to have been created with
Fn tok_init .

Fn tok_reset

Reset the tokenizer state.
Use after a line has been successfully tokenized
by
Fn tok_line
or
Fn tok_str
and before a new line is to be tokenized.

Fn tok_line

Tokenize
Fa li ,
If successful, modify:
Fa argv
to contain the words,
Fa argc
to contain the number of words,
Fa cursorc
(if not
NULL
to contain the index of the word containing the cursor,
and
Fa cursoro
(if not
NULL
to contain the offset within
Fa 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
Aq newline .
A positive exit code indicates that another line should be read
and tokenization attempted again.

Fn tok_str

A simpler form of
Fn tok_line ;
Fa str
is a NUL terminated string to tokenize.

SEE ALSO

HISTORY

The
library first appeared in
BSD 4.4
CC_REDISPLAY
appeared in
Nx 1.3 .
CC_REFRESH_BEEPEL_EDITMODE
and the readline emulation appeared in
Nx 1.4 .
EL_RPROMPT
appeared in
Nx 1.5 .

AUTHORS

The
library was written by Christos Zoulas.
Luke Mewburn wrote this manual and implemented
CC_REDISPLAYCC_REFRESH_BEEPEL_EDITMODE
and
EL_RPROMPT
Jaromir Dolecek implemented the readline emulation.
Johny Mattsson implemented wide-character support.

BUGS

At this time, it is the responsibility of the caller to
check the result of the
EL_EDITMODE
operation of
Fn el_get
(after an
Fn el_source
or
Fn el_parse )
to determine if
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.