Update libedit to bring it into sync with the latest version from NetBSD.

ok deraadt

1 files changed, 238 insertions, 76 deletions

diff --git a/lib/libedit/editline.3 b/lib/libedit/editline.3
index aced91fece8..2061712a1b0 100644
--- a/lib/libedit/editline.3
+++ b/lib/libedit/editline.3
@@ -1,7 +1,7 @@
-.\"	$OpenBSD: editline.3,v 1.27 2010/05/14 21:12:36 nicm Exp $
-.\"	$NetBSD: editline.3,v 1.42 2003/11/04 13:22:19 christos Exp $
+.\"	$OpenBSD: editline.3,v 1.28 2010/06/30 00:05:35 nicm Exp $
+.\"	$NetBSD: editline.3,v 1.73 2010/01/03 19:05:26 wiz Exp $
 .\"
-.\" Copyright (c) 1997-1999 The NetBSD Foundation, Inc.
+.\" Copyright (c) 1997-2003 The NetBSD Foundation, Inc.
 .\" All rights reserved.
 .\"
 .\" This file was contributed to The NetBSD Foundation by Luke Mewburn.
@@ -27,7 +27,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: May 14 2010 $
+.Dd $Mdocdate: June 30 2010 $
 .Dt EDITLINE 3
 .Os
 .Sh NAME
@@ -48,8 +48,15 @@
 .Nm el_deletestr ,
 .Nm history_init ,
 .Nm history_end ,
-.Nm history
-.Nd line editor and history functions
+.Nm history ,
+.Nm tok_init ,
+.Nm tok_end ,
+.Nm tok_reset ,
+.Nm tok_line ,
+.Nm tok_str
+.Nd line editor, history and tokenization functions
+.Sh LIBRARY
+.Lb libedit
 .Sh SYNOPSIS
 .Fd #include <histedit.h>
 .Ft EditLine *
@@ -69,7 +76,7 @@
 .Ft int
 .Fn el_set "EditLine *e" "int op" "..."
 .Ft int
-.Fn el_get "EditLine *e" "int op" "void *result"
+.Fn el_get "EditLine *e" "int op" "..."
 .Ft int
 .Fn el_source "EditLine *e" "const char *file"
 .Ft void
@@ -86,10 +93,20 @@
 .Fn history_end "History *h"
 .Ft int
 .Fn history "History *h" "HistEvent *ev" "int op" "..."
+.Ft Tokenizer *
+.Fn tok_init "const char *IFS"
+.Ft void
+.Fn tok_end "Tokenizer *t"
+.Ft void
+.Fn tok_reset "Tokenizer *t"
+.Ft int
+.Fn tok_line "Tokenizer *t" "const LineInfo *li" "int *argc" "const char **argv[]" "int *cursorc" "int *cursoro"
+.Ft int
+.Fn tok_str "Tokenizer *t" "const char *str" "int *argc" "const char **argv[]"
 .Sh DESCRIPTION
 The
 .Nm
-library provides generic line editing and history functions,
+library provides generic line editing, history and tokenization functions,
 similar to those found in
 .Xr sh 1 .
 .Pp
@@ -143,6 +160,14 @@ 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.
+If an error occurred,
+.Fa count
+is set to \-1 and
+.Dv 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.
 .It Fn el_getc
 Read a character from the tty.
 .Fa ch
@@ -204,10 +229,30 @@ are supported, along with the required argument list:
 Define prompt printing function as
 .Fa f ,
 which is to return a string that contains the prompt.
+.It Dv EL_PROMPT_ESC , Fa "char *(*f)(EditLine *)" , Fa "char c"
+Same as
+.Dv EL_PROMPT ,
+but the
+.Fa c
+argument indicates the start/stop literal prompt character.
+.Pp
+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.
+.Dv 0
+unsets it.
+.It Dv EL_REFRESH
+Re-display the current line on the next terminal line.
 .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_RPROMPT_ESC , Fa "char *(*f)(EditLine *)" , Fa "char c"
+Define the right prompt printing function but with a literal escape character.
 .It Dv EL_TERMINAL , Fa "const char *type"
 Define terminal type of the tty to be
 .Fa type ,
@@ -241,66 +286,43 @@ reading command input:
 and
 .Dv SIGWINCH .
 Otherwise, the current signal handlers will be used.
-.It Dv EL_BIND , Xo
-.Fa "const char *" ,
-.Fa "..." ,
-.Dv NULL
-.Xc
+.It Dv EL_BIND , Fa "const char *" , Fa "..." , Dv NULL
 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
+.It Dv EL_ECHOTC , Fa "const char *" , Fa "..." , Dv NULL
 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
+.It Dv EL_SETTC , Fa "const char *" , Fa "..." , Dv NULL
 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
+.It Dv EL_SETTY , Fa "const char *" , Fa "..." , Dv NULL
 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
+.It Dv EL_TELLTC , Fa "const char *" , Fa "..." , Dv NULL
 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
+.It Dv 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
@@ -342,10 +364,8 @@ 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
+.It Dv EL_HIST , Fa "History *(*func)(History *, int op, ...)" , \
+Fa "const char *ptr"
 Defines which history function to use, which is usually
 .Fn history .
 .Fa ptr
@@ -374,7 +394,8 @@ This function is called internally by
 and
 .Fn el_getc .
 The builtin function can be set or restored with the special function
-name ``EL_BUILTIN_GETCFN''.
+name
+.Dq Dv EL_BUILTIN_GETCFN .
 .It Dv EL_CLIENTDATA , Fa "void *data"
 Register
 .Fa data
@@ -382,6 +403,25 @@ to be associated with this EditLine structure.
 It can be retrieved with the corresponding
 .Fn el_get
 call.
+.It Dv EL_SETFP , Fa "int fd" , Fa "FILE *fp"
+Set the current
+.Nm editline
+file pointer for
+.Dq input
+.Fa fd
+=
+.Dv 0 ,
+.Dq output
+.Fa fd
+=
+.Dv 1 ,
+or
+.Dq error
+.Fa fd
+=
+.Dv 2
+from
+.Fa fp .
 .El
 .It Fn el_get
 Get
@@ -397,39 +437,80 @@ The following values for
 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_PROMPT , Fa "char *(*f)(EditLine *)" , Fa "char *c"
+Return a pointer to the function that displays the prompt in
+.Fa f .
+If
+.Fa c
+is not
+.Dv NULL ,
+return the start/stop literal prompt character in it.
+.It Dv EL_RPROMPT , Fa "char *(*f)(EditLine *)" , Fa "char *c"
+Return a pointer to the function that displays the prompt in
+.Fa f .
+If
+.Fa c
+is not
+.Dv NULL ,
+return the start/stop literal prompt character in it.
 .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_GETTC , Fa "const char *name" , Fa "void *value"
+Return non-zero if
+.Fa name
+is a valid
+.Xr termcap 5
+capability
+and set
+.Fa value
+to the current value of that capability.
 .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 *"
+.It Dv EL_EDITMODE , Fa "int *"
 Return non-zero if editing is enabled.
-.It Dv EL_GETCFN, Fa "int (**f)(EditLine *, char *)"
+.It Dv EL_GETCFN , Fa "int (**f)(EditLine *, char *)"
 Return a pointer to the function that read characters, which is equal to
-``EL_BUILTIN_GETCFN'' in the case of the default builtin function.
+.Dq Dv EL_BUILTIN_GETCFN
+in the case of the default builtin function.
 .It Dv EL_CLIENTDATA , Fa "void **data"
 Retrieve
 .Fa data
 previously registered with the corresponding
 .Fn el_set
 call.
-.It Dv EL_UNBUFFERED, Fa "int"
+.It Dv EL_UNBUFFERED , Fa "int"
 Sets or clears unbuffered mode.
 In this mode,
 .Fn el_gets
 will return immediately after processing a single character.
-.It Dv EL_PREP_TERM, Fa "int"
+.It Dv EL_PREP_TERM , Fa "int"
 Sets or clears terminal editing mode.
+.It Dv EL_GETFP , Fa "int fd", Fa "FILE **fp"
+Return in
+.Fa fp
+the current
+.Nm editline
+file pointer for
+.Dq input
+.Fa fd
+=
+.Dv 0 ,
+.Dq output
+.Fa fd
+=
+.Dv 1 ,
+or
+.Dq error
+.Fa fd
+=
+.Dv 2 .
 .El
 .It Fn el_source
 Initialise
@@ -474,6 +555,16 @@ typedef struct lineinfo {
     const char *lastchar;  /* address of last character */
 } LineInfo;
 .Ed
+.Pp
+.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
+.Dv EL_ADDFN .
 .It Fn el_insertstr
 Insert
 .Fa str
@@ -483,7 +574,7 @@ Returns \-1 if
 is empty or won't fit, and 0 otherwise.
 .It Fn el_deletestr
 Delete
-.Fa num
+.Fa count
 characters before the cursor.
 .El
 .Sh HISTORY LIST FUNCTIONS
@@ -530,18 +621,11 @@ 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
+.It Dv H_FUNC , 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"
 Define functions to perform various history operations.
 .Fa ptr
 is the argument given to a function when it's invoked.
@@ -604,29 +688,109 @@ Load the history list stored in
 Save the history list to
 .Fa file .
 .It Dv H_SETUNIQUE , Fa "int unique"
-Set if the adjacent identical event strings should not be entered into
-the history.
+Set flag that adjacent identical event strings should not be entered
+into the history.
 .It Dv H_GETUNIQUE
-Retrieve the current setting if adjacent elements should be entered into
-the history.
+Retrieve the current setting if adjacent identical elements should
+be entered into the history.
+.It Dv H_DEL , Fa "int e"
+Delete the event numbered
+.Fa e .
+This function is only provided for
+.Xr readline 3
+compatibility.
+The caller is responsible for free'ing the string in the returned
+.Fa HistEvent .
 .El
 .Pp
 .Fn history
-returns \*(Ge 0 if the operation
+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.
 .El
+.Sh 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 .
+.Pp
+The following functions are available:
+.Bl -tag -width 4n
+.It 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
+.Dv NULL .
+.It Fn tok_end
+Clean up and finish with
+.Fa t ,
+assumed to have been created with
+.Fn tok_init .
+.It 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.
+.It 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
+.Dv NULL )
+to contain the index of the word containing the cursor,
+and
+.Fa cursoro
+(if not
+.Dv NULL )
+to contain the offset within
+.Fa argv[cursorc]
+of the cursor.
+.Pp
+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.
+.
+.It Fn tok_str
+A simpler form of
+.Fn tok_line ;
+.Fa str
+is a NUL terminated string to tokenize.
+.El
+.
 .\"XXX.Sh EXAMPLES
 .\"XXX: provide some examples
 .Sh SEE ALSO
 .Xr sh 1 ,
-.Xr curses 3 ,
+.Xr curses 3
 .Xr signal 3 ,
-.Xr termcap 3 ,
-.Xr editrc 5
+.Xr editrc 5 ,
+.Xr termcap 5
 .Sh HISTORY
 The
 .Nm
@@ -653,10 +817,8 @@ Luke Mewburn wrote this manual and implemented
 and
 .Dv EL_RPROMPT .
 Jaromir Dolecek implemented the readline emulation.
+Johny Mattsson implemented wide character support.
 .Sh BUGS
-The tokenization functions are not publicly 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