627 lines
14 KiB
Groff
627 lines
14 KiB
Groff
.\" $NetBSD: editline.3,v 1.20 2000/02/28 17:41:05 chopps Exp $
|
|
.\"
|
|
.\" Copyright (c) 1997-1999 The NetBSD Foundation, Inc.
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" This file was contributed to The NetBSD Foundation by Luke Mewburn.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\" 3. All advertising materials mentioning features or use of this software
|
|
.\" must display the following acknowledgement:
|
|
.\" This product includes software developed by the NetBSD
|
|
.\" Foundation, Inc. and its contributors.
|
|
.\" 4. Neither the name of The NetBSD Foundation nor the names of its
|
|
.\" contributors may be used to endorse or promote products derived
|
|
.\" from this software without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
|
|
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
|
|
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
|
|
.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
|
|
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
|
|
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
|
|
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
|
|
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
|
|
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
|
|
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
|
|
.\" POSSIBILITY OF SUCH DAMAGE.
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd November 12, 1999
|
|
.Os
|
|
.Dt EDITLINE 3
|
|
.Sh NAME
|
|
.Nm editline ,
|
|
.Nm el_init ,
|
|
.Nm el_end ,
|
|
.Nm el_reset ,
|
|
.Nm el_gets ,
|
|
.Nm el_getc ,
|
|
.Nm el_push ,
|
|
.Nm el_parse ,
|
|
.Nm el_set ,
|
|
.Nm el_source ,
|
|
.Nm el_resize ,
|
|
.Nm el_line ,
|
|
.Nm el_insertstr ,
|
|
.Nm el_deletestr ,
|
|
.Nm history_init ,
|
|
.Nm history_end ,
|
|
.Nm history
|
|
.Nd line editor and history functions
|
|
.Sh LIBRARY
|
|
.Lb libedit
|
|
.Sh SYNOPSIS
|
|
.In histedit.h
|
|
.Ft EditLine *
|
|
.Fn el_init "const char *prog" "FILE *fin" "FILE *fout" "FILE *ferr"
|
|
.Ft void
|
|
.Fn el_end "EditLine *e"
|
|
.Ft void
|
|
.Fn el_reset "EditLine *e"
|
|
.Ft const char *
|
|
.Fn el_gets "EditLine *e" "int *count"
|
|
.Ft int
|
|
.Fn el_getc "EditLine *e" "char *ch"
|
|
.Ft void
|
|
.Fn el_push "EditLine *e" "const char *str"
|
|
.Ft int
|
|
.Fn el_parse "EditLine *e" "int argc" "char *argv[]"
|
|
.Ft int
|
|
.Fn el_set "EditLine *e" "int op" "..."
|
|
.Ft int
|
|
.Fn el_get "EditLine *e" "int op" "void *result"
|
|
.Ft int
|
|
.Fn el_source "EditLine *e" "const char *file"
|
|
.Ft void
|
|
.Fn el_resize "EditLine *e"
|
|
.Ft const LineInfo *
|
|
.Fn el_line "EditLine *e"
|
|
.Ft int
|
|
.Fn el_insertstr "EditLine *e" "const char *str"
|
|
.Ft void
|
|
.Fn el_deletestr "EditLine *e" "int count"
|
|
.Ft History *
|
|
.Fn history_init
|
|
.Ft void
|
|
.Fn history_end "History *h"
|
|
.Ft int
|
|
.Fn history "History *h" "HistEvent *ev" "int op" "..."
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
library provides generic line editing and history functions,
|
|
similar to those found in
|
|
.Xr sh 1 .
|
|
.Pp
|
|
These functions are available in the
|
|
.Nm libedit
|
|
library (which needs the
|
|
.Nm libtermcap
|
|
library).
|
|
Programs should be linked with
|
|
.Fl ledit ltermcap .
|
|
.Sh LINE EDITING FUNCTIONS
|
|
The line editing functions use a common data structure,
|
|
.Fa EditLine ,
|
|
which is created by
|
|
.Fn el_init
|
|
and freed by
|
|
.Fn el_end .
|
|
.Pp
|
|
The following functions are available:
|
|
.Bl -tag -width 4n
|
|
.It 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
|
|
.Xr 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
|
|
.Dq the tty
|
|
are actually to this input/output stream combination.
|
|
.It Fn el_end
|
|
Clean up and finish with
|
|
.Fa e ,
|
|
assumed to have been created with
|
|
.Fn el_init .
|
|
.It Fn el_reset
|
|
Reset the tty and the parser.
|
|
This should be called after an error which may have upset the tty's
|
|
state.
|
|
.It 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
|
|
.Dv NULL
|
|
if no characters were read or if an error occurred.
|
|
.It 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.
|
|
.It Fn el_push
|
|
Pushes
|
|
.Fa str
|
|
back onto the input stream.
|
|
This is used by the macro expansion mechanism.
|
|
Refer to the description of
|
|
.Ic bind
|
|
.Fl s
|
|
in
|
|
.Xr editrc 5
|
|
for more information.
|
|
.It Fn el_parse
|
|
Parses the
|
|
.Fa argv
|
|
array (which is
|
|
.Fa argc
|
|
elements in size)
|
|
to execute builtin
|
|
.Nm
|
|
commands.
|
|
If the command is prefixed with
|
|
.Dq prog:
|
|
then
|
|
.Fn el_parse
|
|
will only execute the command if
|
|
.Dq 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
|
|
.Dq prog
|
|
didn't match, or
|
|
1 if the command returned an error.
|
|
Refer to
|
|
.Xr editrc 5
|
|
for more information.
|
|
.It Fn el_set
|
|
Set
|
|
.Nm
|
|
parameters.
|
|
.Fa op
|
|
determines which parameter to set, and each operation has its
|
|
own parameter list.
|
|
.Pp
|
|
The following values for
|
|
.Fa op
|
|
are supported, along with the required argument list:
|
|
.Bl -tag -width 4n
|
|
.It Dv EL_PROMPT , Fa "char *(*f)(EditLine *)"
|
|
Define prompt printing function as
|
|
.Fa f ,
|
|
which is to return a string that contains the prompt.
|
|
.It Dv 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.
|
|
.It Dv EL_TERMINAL , Fa "const char *type"
|
|
Define terminal type of the tty to be
|
|
.Fa type ,
|
|
or to
|
|
.Ev TERM
|
|
if
|
|
.Fa type
|
|
is
|
|
.Dv NULL .
|
|
.It Dv EL_EDITOR , Fa "const char *mode"
|
|
Set editing mode to
|
|
.Fa mode ,
|
|
which must be one of
|
|
.Dq emacs
|
|
or
|
|
.Dq vi .
|
|
.It Dv EL_SIGNAL , Fa "int flag"
|
|
If
|
|
.Fa flag
|
|
is non-zero,
|
|
.Nm
|
|
will install its own signal handler for the following signals when
|
|
reading command input:
|
|
.Dv SIGCONT ,
|
|
.Dv SIGHUP ,
|
|
.Dv SIGINT ,
|
|
.Dv SIGQUIT ,
|
|
.Dv SIGSTOP ,
|
|
.Dv SIGTERM ,
|
|
.Dv SIGTSTP ,
|
|
and
|
|
.Dv SIGWINCH .
|
|
Otherwise, the current signal handlers will be used.
|
|
.It Dv EL_BIND , Xo
|
|
.Fa "const char *" ,
|
|
.Fa "..." ,
|
|
.Dv NULL
|
|
.Xc
|
|
Perform the
|
|
.Ic bind
|
|
builtin command.
|
|
Refer to
|
|
.Xr editrc 5
|
|
for more information.
|
|
.It Dv EL_ECHOTC , Xo
|
|
.Fa "const char *" ,
|
|
.Fa "..." ,
|
|
.Dv NULL
|
|
.Xc
|
|
Perform the
|
|
.Ic echotc
|
|
builtin command.
|
|
Refer to
|
|
.Xr editrc 5
|
|
for more information.
|
|
.It Dv EL_SETTC , Xo
|
|
.Fa "const char *" ,
|
|
.Fa "..." ,
|
|
.Dv NULL
|
|
.Xc
|
|
Perform the
|
|
.Ic settc
|
|
builtin command.
|
|
Refer to
|
|
.Xr editrc 5
|
|
for more information.
|
|
.It Dv EL_SETTY , Xo
|
|
.Fa "const char *" ,
|
|
.Fa "..." ,
|
|
.Dv NULL
|
|
.Xc
|
|
Perform the
|
|
.Ic setty
|
|
builtin command.
|
|
Refer to
|
|
.Xr editrc 5
|
|
for more information.
|
|
.It Dv EL_TELLTC , Xo
|
|
.Fa "const char *" ,
|
|
.Fa "..." ,
|
|
.Dv NULL
|
|
.Xc
|
|
Perform the
|
|
.Ic telltc
|
|
builtin command.
|
|
Refer to
|
|
.Xr editrc 5
|
|
for more information.
|
|
.It Dv EL_ADDFN , Xo
|
|
.Fa "const char *name" ,
|
|
.Fa "const char *help" ,
|
|
.Fa "unsigned char (*func)(EditLine *e, int ch)
|
|
.Xc
|
|
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:
|
|
.Bl -tag -width "CC_REDISPLAY"
|
|
.It Dv CC_NORM
|
|
Add a normal character.
|
|
.It Dv CC_NEWLINE
|
|
End of line was entered.
|
|
.It Dv CC_EOF
|
|
EOF was entered.
|
|
.It Dv CC_ARGHACK
|
|
Expecting further command input as arguments, do nothing visually.
|
|
.It Dv CC_REFRESH
|
|
Refresh display.
|
|
.It Dv CC_REFRESH_BEEP
|
|
Refresh display, and beep.
|
|
.It Dv CC_CURSOR
|
|
Cursor moved, so update and perform
|
|
.Dv CC_REFRESH .
|
|
.It Dv CC_REDISPLAY
|
|
Redisplay entire input line.
|
|
This is useful if a key binding outputs extra information.
|
|
.It Dv CC_ERROR
|
|
An error occurred.
|
|
Beep, and flush tty.
|
|
.It Dv CC_FATAL
|
|
Fatal error, reset tty to known state.
|
|
.El
|
|
.It Dv EL_HIST , Xo
|
|
.Fa "History *(*func)(History *, int op, ...)" ,
|
|
.Fa "const char *ptr"
|
|
.Xc
|
|
Defines which history function to use, which is usually
|
|
.Fn history .
|
|
.Fa ptr
|
|
should be the value returned by
|
|
.Fn history_init .
|
|
.It Dv 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
|
|
.Nm .
|
|
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
|
|
.It Fn el_get
|
|
Get
|
|
.Nm
|
|
parameters.
|
|
.Fa op
|
|
determines which parameter to retrieve into
|
|
.Fa result .
|
|
.Pp
|
|
The following values for
|
|
.Fa op
|
|
are supported, along with actual type of
|
|
.Fa result :
|
|
.Bl -tag -width 4n
|
|
.It Dv EL_PROMPT , Fa "char *(*f)(EditLine *)"
|
|
Return a pointer to the function that displays the prompt.
|
|
.It Dv EL_RPROMPT , Fa "char *(*f)(EditLine *)"
|
|
Return a pointer to the function that displays the rightside prompt.
|
|
.It Dv EL_EDITOR , Fa "const char *"
|
|
Return the name of the editor, which will be one of
|
|
.Dq emacs
|
|
or
|
|
.Dq vi .
|
|
.It Dv EL_SIGNAL , Fa "int *"
|
|
Return non-zero if
|
|
.Nm
|
|
has installed private signal handlers (see
|
|
.Fn el_get
|
|
above).
|
|
.It Dv EL_EDITMODE, Fa "int *"
|
|
Return non-zero if editing is enabled.
|
|
.El
|
|
.It Fn el_source
|
|
Initialise
|
|
.Nm
|
|
by reading the contents of
|
|
.Fa file .
|
|
.Fn el_parse
|
|
is called for each line in
|
|
.Fa file .
|
|
If
|
|
.Fa file
|
|
is
|
|
.Dv NULL ,
|
|
try
|
|
.Pa $PWD/.editrc
|
|
then
|
|
.Pa $HOME/.editrc .
|
|
Refer to
|
|
.Xr editrc 5
|
|
for details on the format of
|
|
.Fa file .
|
|
.It Fn el_resize
|
|
Must be called if the terminal size changes.
|
|
If
|
|
.Dv 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.
|
|
.It Fn el_line
|
|
Return the editing information for the current line in a
|
|
.Fa LineInfo
|
|
structure, which is defined as follows:
|
|
.Bd -literal
|
|
typedef struct lineinfo {
|
|
const char *buffer; /* address of buffer */
|
|
const char *cursor; /* address of cursor */
|
|
const char *lastchar; /* address of last character */
|
|
} LineInfo;
|
|
.Ed
|
|
.It 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.
|
|
.It Fn el_deletestr
|
|
Delete
|
|
.Fa num
|
|
characters before the cursor.
|
|
.El
|
|
.Sh 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 .
|
|
.Pp
|
|
The following functions are available:
|
|
.Bl -tag -width 4n
|
|
.It Fn history_init
|
|
Initialise the history list, and return a data structure
|
|
to be used by all other history list functions.
|
|
.It Fn history_end
|
|
Clean up and finish with
|
|
.Fa h ,
|
|
assumed to have been created with
|
|
.Fn history_init .
|
|
.It 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:
|
|
.Bl -tag -width 4n
|
|
.It Dv H_SETSIZE , Fa "int size"
|
|
Set size of history to
|
|
.Fa size
|
|
elements.
|
|
.It Dv H_GETSIZE
|
|
Get number of events currently in history.
|
|
.It Dv H_END
|
|
Cleans up and finishes with
|
|
.Fa h ,
|
|
assumed to be created with
|
|
.Fn history_init .
|
|
.It Dv H_CLEAR
|
|
Clear the history.
|
|
.It Dv H_FUNC , Xo
|
|
.Fa "void *ptr" ,
|
|
.Fa "history_gfun_t first" ,
|
|
.Fa "history_gfun_t next" ,
|
|
.Fa "history_gfun_t last" ,
|
|
.Fa "history_gfun_t prev" ,
|
|
.Fa "history_gfun_t curr" ,
|
|
.Fa "history_sfun_t set" ,
|
|
.Fa "history_vfun_t clear" ,
|
|
.Fa "history_efun_t enter" ,
|
|
.Fa "history_efun_t add"
|
|
.Xc
|
|
Define functions to perform various history operations.
|
|
.Fa ptr
|
|
is the argument given to a function when it's invoked.
|
|
.It Dv H_FIRST
|
|
Return the first element in the history.
|
|
.It Dv H_LAST
|
|
Return the last element in the history.
|
|
.It Dv H_PREV
|
|
Return the previous element in the history.
|
|
.It Dv H_NEXT
|
|
Return the next element in the history.
|
|
.It Dv H_CURR
|
|
Return the current element in the history.
|
|
.It Dv H_SET
|
|
Set the cursor to point to the requested element.
|
|
.It Dv H_ADD , Fa "const char *str"
|
|
Append
|
|
.Fa str
|
|
to the current element of the history, or create an element with
|
|
.It Dv H_APPEND , Fa "const char *str"
|
|
Append
|
|
.Fa str
|
|
to the last new element of the history.
|
|
.It Dv 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.
|
|
.It Dv H_PREV_STR , Fa "const char *str"
|
|
Return the closest previous event that starts with
|
|
.Fa str .
|
|
.It Dv H_NEXT_STR , Fa "const char *str"
|
|
Return the closest next event that starts with
|
|
.Fa str .
|
|
.It Dv H_PREV_EVENT , Fa "int e"
|
|
Return the previous event numbered
|
|
.Fa e .
|
|
.It Dv H_NEXT_EVENT , Fa "int e"
|
|
Return the next event numbered
|
|
.Fa e .
|
|
.It Dv H_LOAD , Fa "const char *file"
|
|
Load the history list stored in
|
|
.Fa file .
|
|
.It Dv H_SAVE , Fa "const char *file"
|
|
Save the history list to
|
|
.Fa file .
|
|
.El
|
|
.Pp
|
|
.Fn history
|
|
returns 0 if the operation
|
|
.Fa op
|
|
succeeds.
|
|
Otherwise, \-1 is returned and
|
|
.Fa ev
|
|
is updated to contain more details about the error.
|
|
.El
|
|
.\"XXX.Sh EXAMPLES
|
|
.\"XXX: provide some examples
|
|
.Sh SEE ALSO
|
|
.Xr sh 1 ,
|
|
.Xr signal 3 ,
|
|
.Xr termcap 3 ,
|
|
.Xr editrc 5
|
|
.Sh HISTORY
|
|
The
|
|
.Nm
|
|
library first appeared in
|
|
.Bx 4.4 .
|
|
.Dv CC_REDISPLAY
|
|
appeared in
|
|
.Nx 1.3 .
|
|
.Dv CC_REFRESH_BEEP ,
|
|
.Dv EL_EDITMODE
|
|
and the readline emulation appeared in
|
|
.Nx 1.4 .
|
|
.Dv EL_RPROMPT
|
|
appeared in
|
|
.Nx 1.5 .
|
|
.Sh AUTHORS
|
|
.An -nosplit
|
|
The
|
|
.Nm
|
|
library was written by
|
|
.An Christos Zoulas .
|
|
.An Luke Mewburn
|
|
wrote this manual and implemented
|
|
.Dv CC_REDISPLAY ,
|
|
.Dv CC_REFRESH_BEEP ,
|
|
.Dv EL_EDITMODE ,
|
|
and
|
|
.Dv EL_RPROMPT .
|
|
.An Jaromir Dolecek
|
|
implemented the readline emulation.
|
|
.Sh BUGS
|
|
The tokenization functions are not publically defined in
|
|
.Aq Pa histedit.h .
|
|
.Pp
|
|
At this time, it is the responsibility of the caller to
|
|
check the result of the
|
|
.Dv EL_EDITMODE
|
|
operation of
|
|
.Fn el_get
|
|
(after an
|
|
.Fn el_source
|
|
or
|
|
.Fn el_parse )
|
|
to determine if
|
|
.Nm
|
|
should be used for further input.
|
|
I.e.,
|
|
.Dv EL_EDITMODE
|
|
is purely an indication of the result of the most recent
|
|
.Xr editrc 5
|
|
.Ic edit
|
|
command.
|