mirror of
https://git.FreeBSD.org/src.git
synced 2024-12-24 11:29:10 +00:00
c4d9468ea0
Avoid using parenthesis enclosure macros (.Pq and .Po/.Pc) with plain text. Not only this slows down the mdoc(7) processing significantly, but it also has an undesired (in this case) effect of disabling hyphenation within the entire enclosed block.
547 lines
12 KiB
Groff
547 lines
12 KiB
Groff
.\" $NetBSD: editline.3,v 1.4 1997/01/14 04:17:23 lukem Exp $
|
|
.\"
|
|
.\" Copyright (c) 1997 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 REGENTS 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 January 11, 1997
|
|
.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 el_data_set ,
|
|
.Nm el_data_get ,
|
|
.Nm history_init ,
|
|
.Nm history_end ,
|
|
.Nm history
|
|
.Nd line editor and history functions
|
|
.Sh LIBRARY
|
|
.Lb libedit
|
|
.Sh SYNOPSIS
|
|
.Fd #include <histedit.h>
|
|
.Ft EditLine *
|
|
.Fn el_init "const char *prog" "FILE *fin" "FILE *fout"
|
|
.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_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" "char *str"
|
|
.Ft void
|
|
.Fn el_deletestr "EditLine *e" "int count"
|
|
.Ft void
|
|
.Fn el_data_set "EditLine *e" "void *data"
|
|
.Ft void *
|
|
.Fn el_data_get "EditLine *e"
|
|
.Ft History *
|
|
.Fn history_init
|
|
.Ft void
|
|
.Fn history_end "History *h"
|
|
.Ft const HistEvent *
|
|
.Fn history "History *h" "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
|
|
and
|
|
.Fa fout
|
|
are the input and output 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.
|
|
.Pp
|
|
.Em NOTE :
|
|
.Va argv[0]
|
|
may be modified by
|
|
.Fn el_parse .
|
|
The colon between
|
|
.Dq prog
|
|
and the command,
|
|
.Ar command ,
|
|
will be replaced with a NUL
|
|
.Pq Dq \e0 .
|
|
.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_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_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 .
|
|
.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 $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.
|
|
.It Fn el_data_set
|
|
Set the user data to
|
|
.Fa data .
|
|
.It Fn el_data_get
|
|
Get the user data.
|
|
.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.
|
|
The following values for
|
|
.Fa op
|
|
are supported, along with the required argument list:
|
|
.Bl -tag -width 4n
|
|
.It Dv H_EVENT , Fa "int size"
|
|
Set size of history to
|
|
.Fa size
|
|
elements.
|
|
.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_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_ADD , Fa "const char *str"
|
|
Append
|
|
.Fa str
|
|
to the current element of the history, or create an element with
|
|
.Dv H_ENTER
|
|
if there isn't one.
|
|
.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
|
|
.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 .
|
|
.Sh AUTHORS
|
|
.An -nosplit
|
|
The
|
|
.Nm
|
|
library was written by
|
|
.An Christos Zoulas ,
|
|
and this manual was written by
|
|
.An Luke Mewburn .
|
|
.Sh BUGS
|
|
This documentation is probably incomplete.
|
|
.Pp
|
|
.Fn el_parse
|
|
should not modify the supplied
|
|
.Va argv[0] .
|
|
.Pp
|
|
The tokenization functions are not publicly defined in
|
|
.Li <histedit.h> .
|