diff options
Diffstat (limited to 'editline.3')
| -rw-r--r-- | editline.3 | 176 |
1 files changed, 118 insertions, 58 deletions
diff --git a/editline.3 b/editline.3 index a0f32b6a1b8a..e2504107c8b8 100644 --- a/editline.3 +++ b/editline.3 @@ -1,4 +1,4 @@ -.\" $NetBSD: editline.3,v 1.55 2007/01/12 16:31:13 christos Exp $ +.\" $NetBSD: editline.3,v 1.73 2010/01/03 19:05:26 wiz Exp $ .\" .\" Copyright (c) 1997-2003 The NetBSD Foundation, Inc. .\" All rights reserved. @@ -13,9 +13,6 @@ .\" 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. 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 @@ -29,33 +26,50 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGE. .\" -.Dd January 12, 2007 -.Os +.Dd January 3, 2010 .Dt EDITLINE 3 +.Os .Sh NAME .Nm editline , .Nm el_init , .Nm el_end , .Nm el_reset , .Nm el_gets , +.Nm el_wgets , .Nm el_getc , +.Nm el_wgetc , .Nm el_push , +.Nm el_wpush , .Nm el_parse , +.Nm el_wparse , .Nm el_set , +.Nm el_wset , .Nm el_get , +.Nm el_wget , .Nm el_source , .Nm el_resize , .Nm el_line , +.Nm el_wline , .Nm el_insertstr , +.Nm el_winsertstr , .Nm el_deletestr , +.Nm el_wdeletestr , .Nm history_init , +.Nm history_winit , .Nm history_end , +.Nm history_wend , .Nm history , +.Nm history_w , .Nm tok_init , +.Nm tok_winit , .Nm tok_end , +.Nm tok_wend , .Nm tok_reset , +.Nm tok_wreset , .Nm tok_line , +.Nm tok_wline , .Nm tok_str +.Nm tok_wstr .Nd line editor, history and tokenization functions .Sh LIBRARY .Lb libedit @@ -69,17 +83,29 @@ .Fn el_reset "EditLine *e" .Ft const char * .Fn el_gets "EditLine *e" "int *count" +.Ft const wchar_t * +.Fn el_wgets "EditLine *e" "int *count" .Ft int .Fn el_getc "EditLine *e" "char *ch" +.Ft int +.Fn el_wgetc "EditLine *e" "wchar_t *ch" .Ft void .Fn el_push "EditLine *e" "const char *str" +.Ft void +.Fn el_wpush "EditLine *e" "const wchar_t *str" .Ft int .Fn el_parse "EditLine *e" "int argc" "const char *argv[]" .Ft int +.Fn el_wparse "EditLine *e" "int argc" "const wchar_t *argv[]" +.Ft int .Fn el_set "EditLine *e" "int op" "..." .Ft int +.Fn el_wset "EditLine *e" "int op" "..." +.Ft int .Fn el_get "EditLine *e" "int op" "..." .Ft int +.Fn el_wget "EditLine *e" "int op" "..." +.Ft int .Fn el_source "EditLine *e" "const char *file" .Ft void .Fn el_resize "EditLine *e" @@ -87,24 +113,44 @@ .Fn el_line "EditLine *e" .Ft int .Fn el_insertstr "EditLine *e" "const char *str" +.Ft int +.Fn el_winsertstr "EditLine *e" "const wchar_t *str" .Ft void .Fn el_deletestr "EditLine *e" "int count" +.Ft void +.Fn el_wdeletestr "EditLine *e" "int count" .Ft History * .Fn history_init +.Ft HistoryW * +.Fn history_winit .Ft void .Fn history_end "History *h" +.Ft void +.Fn history_wend "HistoryW *h" .Ft int .Fn history "History *h" "HistEvent *ev" "int op" "..." +.Ft int +.Fn history_w "HistoryW *h" "HistEventW *ev" "int op" "..." .Ft Tokenizer * .Fn tok_init "const char *IFS" +.Ft TokenizerW * +.Fn tok_winit "const wchar_t *IFS" .Ft void .Fn tok_end "Tokenizer *t" .Ft void +.Fn tok_wend "TokenizerW *t" +.Ft void .Fn tok_reset "Tokenizer *t" +.Ft void +.Fn tok_wreset "TokenizerW *t" .Ft int .Fn tok_line "Tokenizer *t" "const LineInfo *li" "int *argc" "const char **argv[]" "int *cursorc" "int *cursoro" .Ft int +.Fn tok_wline "TokenizerW *t" "const LineInfoW *li" "int *argc" "const wchar_t **argv[]" "int *cursorc" "int *cursoro" +.Ft int .Fn tok_str "Tokenizer *t" "const char *str" "int *argc" "const char **argv[]" +.Ft int +.Fn tok_wstr "TokenizerW *t" "const wchar_t *str" "int *argc" "const wchar_t **argv[]" .Sh DESCRIPTION The .Nm @@ -127,6 +173,9 @@ which is created by and freed by .Fn el_end . .Pp +The wide character functions behave the same way as their narrow +counterparts. +.Pp The following functions are available: .Bl -tag -width 4n .It Fn el_init @@ -160,6 +209,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 @@ -220,10 +277,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 , @@ -257,66 +334,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 @@ -358,10 +412,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 @@ -390,7 +442,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 @@ -432,10 +485,22 @@ 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 @@ -460,7 +525,8 @@ above). Return non-zero if editing is enabled. .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 @@ -599,18 +665,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. @@ -802,6 +861,7 @@ 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 At this time, it is the responsibility of the caller to check the result of the |