diff options
Diffstat (limited to 'lib/libedit/editline.3')
| -rw-r--r-- | lib/libedit/editline.3 | 314 |
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 |