1.\" $NetBSD: editline.3,v 1.20 2000/02/28 17:41:05 chopps Exp $
| 1.\" $NetBSD: editline.3,v 1.48 2005/07/14 15:02:37 wiz Exp $
|
2.\"
| 2.\"
|
3.\" Copyright (c) 1997-1999 The NetBSD Foundation, Inc.
| 3.\" Copyright (c) 1997-2003 The NetBSD Foundation, Inc.
|
4.\" All rights reserved. 5.\" 6.\" This file was contributed to The NetBSD Foundation by Luke Mewburn. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" notice, this list of conditions and the following disclaimer in the 15.\" documentation and/or other materials provided with the distribution. 16.\" 3. All advertising materials mentioning features or use of this software 17.\" must display the following acknowledgement: 18.\" This product includes software developed by the NetBSD 19.\" Foundation, Inc. and its contributors. 20.\" 4. Neither the name of The NetBSD Foundation nor the names of its 21.\" contributors may be used to endorse or promote products derived 22.\" from this software without specific prior written permission. 23.\" 24.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 25.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 26.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 27.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 28.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 29.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 30.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 31.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 32.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 33.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 34.\" POSSIBILITY OF SUCH DAMAGE. 35.\"
| 4.\" All rights reserved. 5.\" 6.\" This file was contributed to The NetBSD Foundation by Luke Mewburn. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" notice, this list of conditions and the following disclaimer in the 15.\" documentation and/or other materials provided with the distribution. 16.\" 3. All advertising materials mentioning features or use of this software 17.\" must display the following acknowledgement: 18.\" This product includes software developed by the NetBSD 19.\" Foundation, Inc. and its contributors. 20.\" 4. Neither the name of The NetBSD Foundation nor the names of its 21.\" contributors may be used to endorse or promote products derived 22.\" from this software without specific prior written permission. 23.\" 24.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 25.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 26.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 27.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 28.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 29.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 30.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 31.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 32.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 33.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 34.\" POSSIBILITY OF SUCH DAMAGE. 35.\"
|
36.\" $FreeBSD: head/lib/libedit/editline.3 141851 2005-02-13 23:45:54Z ru $
| 36.\" $FreeBSD: head/lib/libedit/editline.3 148834 2005-08-07 20:55:59Z stefanf $
|
37.\"
| 37.\"
|
38.Dd November 12, 1999
| 38.Dd July 14, 2005
|
39.Os 40.Dt EDITLINE 3 41.Sh NAME 42.Nm editline , 43.Nm el_init , 44.Nm el_end , 45.Nm el_reset , 46.Nm el_gets , 47.Nm el_getc , 48.Nm el_push , 49.Nm el_parse , 50.Nm el_set , 51.Nm el_source , 52.Nm el_resize , 53.Nm el_line , 54.Nm el_insertstr , 55.Nm el_deletestr , 56.Nm history_init , 57.Nm history_end ,
| 39.Os 40.Dt EDITLINE 3 41.Sh NAME 42.Nm editline , 43.Nm el_init , 44.Nm el_end , 45.Nm el_reset , 46.Nm el_gets , 47.Nm el_getc , 48.Nm el_push , 49.Nm el_parse , 50.Nm el_set , 51.Nm el_source , 52.Nm el_resize , 53.Nm el_line , 54.Nm el_insertstr , 55.Nm el_deletestr , 56.Nm history_init , 57.Nm history_end ,
|
58.Nm history 59.Nd line editor and history functions
| 58.Nm history , 59.Nm tok_init , 60.Nm tok_end , 61.Nm tok_reset , 62.Nm tok_line , 63.Nm tok_str 64.Nd line editor, history and tokenization functions
|
60.Sh LIBRARY 61.Lb libedit 62.Sh SYNOPSIS 63.In histedit.h 64.Ft EditLine * 65.Fn el_init "const char *prog" "FILE *fin" "FILE *fout" "FILE *ferr" 66.Ft void 67.Fn el_end "EditLine *e" 68.Ft void 69.Fn el_reset "EditLine *e" 70.Ft const char * 71.Fn el_gets "EditLine *e" "int *count" 72.Ft int 73.Fn el_getc "EditLine *e" "char *ch" 74.Ft void 75.Fn el_push "EditLine *e" "const char *str" 76.Ft int
| 65.Sh LIBRARY 66.Lb libedit 67.Sh SYNOPSIS 68.In histedit.h 69.Ft EditLine * 70.Fn el_init "const char *prog" "FILE *fin" "FILE *fout" "FILE *ferr" 71.Ft void 72.Fn el_end "EditLine *e" 73.Ft void 74.Fn el_reset "EditLine *e" 75.Ft const char * 76.Fn el_gets "EditLine *e" "int *count" 77.Ft int 78.Fn el_getc "EditLine *e" "char *ch" 79.Ft void 80.Fn el_push "EditLine *e" "const char *str" 81.Ft int
|
77.Fn el_parse "EditLine *e" "int argc" "char *argv[]"
| 82.Fn el_parse "EditLine *e" "int argc" "const char *argv[]"
|
78.Ft int 79.Fn el_set "EditLine *e" "int op" "..." 80.Ft int 81.Fn el_get "EditLine *e" "int op" "void *result" 82.Ft int 83.Fn el_source "EditLine *e" "const char *file" 84.Ft void 85.Fn el_resize "EditLine *e" 86.Ft const LineInfo * 87.Fn el_line "EditLine *e" 88.Ft int 89.Fn el_insertstr "EditLine *e" "const char *str" 90.Ft void 91.Fn el_deletestr "EditLine *e" "int count" 92.Ft History * 93.Fn history_init 94.Ft void 95.Fn history_end "History *h" 96.Ft int 97.Fn history "History *h" "HistEvent *ev" "int op" "..."
| 83.Ft int 84.Fn el_set "EditLine *e" "int op" "..." 85.Ft int 86.Fn el_get "EditLine *e" "int op" "void *result" 87.Ft int 88.Fn el_source "EditLine *e" "const char *file" 89.Ft void 90.Fn el_resize "EditLine *e" 91.Ft const LineInfo * 92.Fn el_line "EditLine *e" 93.Ft int 94.Fn el_insertstr "EditLine *e" "const char *str" 95.Ft void 96.Fn el_deletestr "EditLine *e" "int count" 97.Ft History * 98.Fn history_init 99.Ft void 100.Fn history_end "History *h" 101.Ft int 102.Fn history "History *h" "HistEvent *ev" "int op" "..."
|
| 103.Ft Tokenizer * 104.Fn tok_init "const char *IFS" 105.Ft void 106.Fn tok_end "Tokenizer *t" 107.Ft void 108.Fn tok_reset "Tokenizer *t" 109.Ft int 110.Fn tok_line "Tokenizer *t" "const LineInfo *li" "int *argc" "const char **argv[]" "int *cursorc" "int *cursoro" 111.Ft int 112.Fn tok_str "Tokenizer *t" "const char *str" "int *argc" "const char **argv[]"
|
98.Sh DESCRIPTION 99The 100.Nm
| 113.Sh DESCRIPTION 114The 115.Nm
|
101library provides generic line editing and history functions,
| 116library provides generic line editing, history and tokenization functions,
|
102similar to those found in 103.Xr sh 1 . 104.Pp 105These functions are available in the 106.Nm libedit 107library (which needs the 108.Nm libtermcap 109library). 110Programs should be linked with 111.Fl ledit ltermcap . 112.Sh LINE EDITING FUNCTIONS 113The line editing functions use a common data structure, 114.Fa EditLine , 115which is created by 116.Fn el_init 117and freed by 118.Fn el_end . 119.Pp 120The following functions are available: 121.Bl -tag -width 4n 122.It Fn el_init 123Initialise the line editor, and return a data structure 124to be used by all other line editing functions. 125.Fa prog 126is the name of the invoking program, used when reading the 127.Xr editrc 5 128file to determine which settings to use. 129.Fa fin , 130.Fa fout 131and 132.Fa ferr 133are the input, output, and error streams (respectively) to use. 134In this documentation, references to 135.Dq the tty 136are actually to this input/output stream combination. 137.It Fn el_end 138Clean up and finish with 139.Fa e , 140assumed to have been created with 141.Fn el_init . 142.It Fn el_reset 143Reset the tty and the parser. 144This should be called after an error which may have upset the tty's 145state. 146.It Fn el_gets 147Read a line from the tty. 148.Fa count 149is modified to contain the number of characters read. 150Returns the line read if successful, or 151.Dv NULL 152if no characters were read or if an error occurred. 153.It Fn el_getc 154Read a character from the tty. 155.Fa ch 156is modified to contain the character read.
| 117similar to those found in 118.Xr sh 1 . 119.Pp 120These functions are available in the 121.Nm libedit 122library (which needs the 123.Nm libtermcap 124library). 125Programs should be linked with 126.Fl ledit ltermcap . 127.Sh LINE EDITING FUNCTIONS 128The line editing functions use a common data structure, 129.Fa EditLine , 130which is created by 131.Fn el_init 132and freed by 133.Fn el_end . 134.Pp 135The following functions are available: 136.Bl -tag -width 4n 137.It Fn el_init 138Initialise the line editor, and return a data structure 139to be used by all other line editing functions. 140.Fa prog 141is the name of the invoking program, used when reading the 142.Xr editrc 5 143file to determine which settings to use. 144.Fa fin , 145.Fa fout 146and 147.Fa ferr 148are the input, output, and error streams (respectively) to use. 149In this documentation, references to 150.Dq the tty 151are actually to this input/output stream combination. 152.It Fn el_end 153Clean up and finish with 154.Fa e , 155assumed to have been created with 156.Fn el_init . 157.It Fn el_reset 158Reset the tty and the parser. 159This should be called after an error which may have upset the tty's 160state. 161.It Fn el_gets 162Read a line from the tty. 163.Fa count 164is modified to contain the number of characters read. 165Returns the line read if successful, or 166.Dv NULL 167if no characters were read or if an error occurred. 168.It Fn el_getc 169Read a character from the tty. 170.Fa ch 171is modified to contain the character read.
|
157Returns the number of characters read if successful, -1 otherwise.
| 172Returns the number of characters read if successful, \-1 otherwise.
|
158.It Fn el_push 159Pushes 160.Fa str 161back onto the input stream. 162This is used by the macro expansion mechanism. 163Refer to the description of 164.Ic bind 165.Fl s 166in 167.Xr editrc 5 168for more information. 169.It Fn el_parse 170Parses the 171.Fa argv 172array (which is 173.Fa argc 174elements in size) 175to execute builtin 176.Nm 177commands. 178If the command is prefixed with
| 173.It Fn el_push 174Pushes 175.Fa str 176back onto the input stream. 177This is used by the macro expansion mechanism. 178Refer to the description of 179.Ic bind 180.Fl s 181in 182.Xr editrc 5 183for more information. 184.It Fn el_parse 185Parses the 186.Fa argv 187array (which is 188.Fa argc 189elements in size) 190to execute builtin 191.Nm 192commands. 193If the command is prefixed with
|
179.Dq prog:
| 194.Dq prog :
|
180then 181.Fn el_parse 182will only execute the command if 183.Dq prog 184matches the 185.Fa prog 186argument supplied to 187.Fn el_init . 188The return value is
| 195then 196.Fn el_parse 197will only execute the command if 198.Dq prog 199matches the 200.Fa prog 201argument supplied to 202.Fn el_init . 203The return value is
|
189-1 if the command is unknown,
| 204\-1 if the command is unknown,
|
1900 if there was no error or 191.Dq prog 192did not match, or 1931 if the command returned an error. 194Refer to 195.Xr editrc 5 196for more information. 197.It Fn el_set 198Set 199.Nm 200parameters. 201.Fa op 202determines which parameter to set, and each operation has its 203own parameter list. 204.Pp 205The following values for 206.Fa op 207are supported, along with the required argument list: 208.Bl -tag -width 4n 209.It Dv EL_PROMPT , Fa "char *(*f)(EditLine *)" 210Define prompt printing function as 211.Fa f , 212which is to return a string that contains the prompt. 213.It Dv EL_RPROMPT , Fa "char *(*f)(EditLine *)" 214Define right side prompt printing function as 215.Fa f , 216which is to return a string that contains the prompt. 217.It Dv EL_TERMINAL , Fa "const char *type" 218Define terminal type of the tty to be 219.Fa type , 220or to 221.Ev TERM 222if 223.Fa type 224is 225.Dv NULL . 226.It Dv EL_EDITOR , Fa "const char *mode" 227Set editing mode to 228.Fa mode , 229which must be one of 230.Dq emacs 231or 232.Dq vi . 233.It Dv EL_SIGNAL , Fa "int flag" 234If 235.Fa flag 236is non-zero, 237.Nm 238will install its own signal handler for the following signals when 239reading command input: 240.Dv SIGCONT , 241.Dv SIGHUP , 242.Dv SIGINT , 243.Dv SIGQUIT , 244.Dv SIGSTOP , 245.Dv SIGTERM , 246.Dv SIGTSTP , 247and 248.Dv SIGWINCH . 249Otherwise, the current signal handlers will be used. 250.It Dv EL_BIND , Xo 251.Fa "const char *" , 252.Fa "..." , 253.Dv NULL 254.Xc 255Perform the 256.Ic bind 257builtin command. 258Refer to 259.Xr editrc 5 260for more information. 261.It Dv EL_ECHOTC , Xo 262.Fa "const char *" , 263.Fa "..." , 264.Dv NULL 265.Xc 266Perform the 267.Ic echotc 268builtin command. 269Refer to 270.Xr editrc 5 271for more information. 272.It Dv EL_SETTC , Xo 273.Fa "const char *" , 274.Fa "..." , 275.Dv NULL 276.Xc 277Perform the 278.Ic settc 279builtin command. 280Refer to 281.Xr editrc 5 282for more information. 283.It Dv EL_SETTY , Xo 284.Fa "const char *" , 285.Fa "..." , 286.Dv NULL 287.Xc 288Perform the 289.Ic setty 290builtin command. 291Refer to 292.Xr editrc 5 293for more information. 294.It Dv EL_TELLTC , Xo 295.Fa "const char *" , 296.Fa "..." , 297.Dv NULL 298.Xc 299Perform the 300.Ic telltc 301builtin command. 302Refer to 303.Xr editrc 5 304for more information. 305.It Dv EL_ADDFN , Xo 306.Fa "const char *name" , 307.Fa "const char *help" ,
| 2050 if there was no error or 206.Dq prog 207did not match, or 2081 if the command returned an error. 209Refer to 210.Xr editrc 5 211for more information. 212.It Fn el_set 213Set 214.Nm 215parameters. 216.Fa op 217determines which parameter to set, and each operation has its 218own parameter list. 219.Pp 220The following values for 221.Fa op 222are supported, along with the required argument list: 223.Bl -tag -width 4n 224.It Dv EL_PROMPT , Fa "char *(*f)(EditLine *)" 225Define prompt printing function as 226.Fa f , 227which is to return a string that contains the prompt. 228.It Dv EL_RPROMPT , Fa "char *(*f)(EditLine *)" 229Define right side prompt printing function as 230.Fa f , 231which is to return a string that contains the prompt. 232.It Dv EL_TERMINAL , Fa "const char *type" 233Define terminal type of the tty to be 234.Fa type , 235or to 236.Ev TERM 237if 238.Fa type 239is 240.Dv NULL . 241.It Dv EL_EDITOR , Fa "const char *mode" 242Set editing mode to 243.Fa mode , 244which must be one of 245.Dq emacs 246or 247.Dq vi . 248.It Dv EL_SIGNAL , Fa "int flag" 249If 250.Fa flag 251is non-zero, 252.Nm 253will install its own signal handler for the following signals when 254reading command input: 255.Dv SIGCONT , 256.Dv SIGHUP , 257.Dv SIGINT , 258.Dv SIGQUIT , 259.Dv SIGSTOP , 260.Dv SIGTERM , 261.Dv SIGTSTP , 262and 263.Dv SIGWINCH . 264Otherwise, the current signal handlers will be used. 265.It Dv EL_BIND , Xo 266.Fa "const char *" , 267.Fa "..." , 268.Dv NULL 269.Xc 270Perform the 271.Ic bind 272builtin command. 273Refer to 274.Xr editrc 5 275for more information. 276.It Dv EL_ECHOTC , Xo 277.Fa "const char *" , 278.Fa "..." , 279.Dv NULL 280.Xc 281Perform the 282.Ic echotc 283builtin command. 284Refer to 285.Xr editrc 5 286for more information. 287.It Dv EL_SETTC , Xo 288.Fa "const char *" , 289.Fa "..." , 290.Dv NULL 291.Xc 292Perform the 293.Ic settc 294builtin command. 295Refer to 296.Xr editrc 5 297for more information. 298.It Dv EL_SETTY , Xo 299.Fa "const char *" , 300.Fa "..." , 301.Dv NULL 302.Xc 303Perform the 304.Ic setty 305builtin command. 306Refer to 307.Xr editrc 5 308for more information. 309.It Dv EL_TELLTC , Xo 310.Fa "const char *" , 311.Fa "..." , 312.Dv NULL 313.Xc 314Perform the 315.Ic telltc 316builtin command. 317Refer to 318.Xr editrc 5 319for more information. 320.It Dv EL_ADDFN , Xo 321.Fa "const char *name" , 322.Fa "const char *help" ,
|
308.Fa "unsigned char (*func)(EditLine *e, int ch)
| 323.Fa "unsigned char (*func)(EditLine *e, int ch)"
|
309.Xc 310Add a user defined function, 311.Fn func , 312referred to as 313.Fa name 314which is invoked when a key which is bound to 315.Fa name 316is entered. 317.Fa help 318is a description of 319.Fa name . 320At invocation time, 321.Fa ch 322is the key which caused the invocation. 323The return value of 324.Fn func 325should be one of: 326.Bl -tag -width "CC_REDISPLAY" 327.It Dv CC_NORM 328Add a normal character. 329.It Dv CC_NEWLINE 330End of line was entered. 331.It Dv CC_EOF 332EOF was entered. 333.It Dv CC_ARGHACK 334Expecting further command input as arguments, do nothing visually. 335.It Dv CC_REFRESH 336Refresh display. 337.It Dv CC_REFRESH_BEEP 338Refresh display, and beep. 339.It Dv CC_CURSOR 340Cursor moved, so update and perform 341.Dv CC_REFRESH . 342.It Dv CC_REDISPLAY 343Redisplay entire input line. 344This is useful if a key binding outputs extra information. 345.It Dv CC_ERROR 346An error occurred. 347Beep, and flush tty. 348.It Dv CC_FATAL 349Fatal error, reset tty to known state. 350.El 351.It Dv EL_HIST , Xo 352.Fa "History *(*func)(History *, int op, ...)" , 353.Fa "const char *ptr" 354.Xc 355Defines which history function to use, which is usually 356.Fn history . 357.Fa ptr 358should be the value returned by 359.Fn history_init . 360.It Dv EL_EDITMODE , Fa "int flag" 361If 362.Fa flag 363is non-zero, 364editing is enabled (the default). 365Note that this is only an indication, and does not 366affect the operation of 367.Nm . 368At this time, it is the caller's responsibility to 369check this 370(using 371.Fn el_get ) 372to determine if editing should be enabled or not.
| 324.Xc 325Add a user defined function, 326.Fn func , 327referred to as 328.Fa name 329which is invoked when a key which is bound to 330.Fa name 331is entered. 332.Fa help 333is a description of 334.Fa name . 335At invocation time, 336.Fa ch 337is the key which caused the invocation. 338The return value of 339.Fn func 340should be one of: 341.Bl -tag -width "CC_REDISPLAY" 342.It Dv CC_NORM 343Add a normal character. 344.It Dv CC_NEWLINE 345End of line was entered. 346.It Dv CC_EOF 347EOF was entered. 348.It Dv CC_ARGHACK 349Expecting further command input as arguments, do nothing visually. 350.It Dv CC_REFRESH 351Refresh display. 352.It Dv CC_REFRESH_BEEP 353Refresh display, and beep. 354.It Dv CC_CURSOR 355Cursor moved, so update and perform 356.Dv CC_REFRESH . 357.It Dv CC_REDISPLAY 358Redisplay entire input line. 359This is useful if a key binding outputs extra information. 360.It Dv CC_ERROR 361An error occurred. 362Beep, and flush tty. 363.It Dv CC_FATAL 364Fatal error, reset tty to known state. 365.El 366.It Dv EL_HIST , Xo 367.Fa "History *(*func)(History *, int op, ...)" , 368.Fa "const char *ptr" 369.Xc 370Defines which history function to use, which is usually 371.Fn history . 372.Fa ptr 373should be the value returned by 374.Fn history_init . 375.It Dv EL_EDITMODE , Fa "int flag" 376If 377.Fa flag 378is non-zero, 379editing is enabled (the default). 380Note that this is only an indication, and does not 381affect the operation of 382.Nm . 383At this time, it is the caller's responsibility to 384check this 385(using 386.Fn el_get ) 387to determine if editing should be enabled or not.
|
| 388.It Dv EL_GETCFN , Fa "int (*f)(EditLine *, char *c)" 389Define the character reading function as 390.Fa f , 391which is to return the number of characters read and store them in 392.Fa c . 393This function is called internally by 394.Fn el_gets 395and 396.Fn el_getc . 397The builtin function can be set or restored with the special function 398name ``EL_BUILTIN_GETCFN''. 399.It Dv EL_CLIENTDATA , Fa "void *data" 400Register 401.Fa data 402to be associated with this EditLine structure. 403It can be retrieved with the corresponding 404.Fn el_get 405call.
|
373.El 374.It Fn el_get 375Get 376.Nm 377parameters. 378.Fa op 379determines which parameter to retrieve into 380.Fa result .
| 406.El 407.It Fn el_get 408Get 409.Nm 410parameters. 411.Fa op 412determines which parameter to retrieve into 413.Fa result .
|
| 414Returns 0 if successful, \-1 otherwise.
|
381.Pp 382The following values for 383.Fa op 384are supported, along with actual type of 385.Fa result : 386.Bl -tag -width 4n 387.It Dv EL_PROMPT , Fa "char *(*f)(EditLine *)" 388Return a pointer to the function that displays the prompt. 389.It Dv EL_RPROMPT , Fa "char *(*f)(EditLine *)" 390Return a pointer to the function that displays the rightside prompt. 391.It Dv EL_EDITOR , Fa "const char *" 392Return the name of the editor, which will be one of 393.Dq emacs 394or 395.Dq vi . 396.It Dv EL_SIGNAL , Fa "int *" 397Return non-zero if 398.Nm 399has installed private signal handlers (see 400.Fn el_get 401above). 402.It Dv EL_EDITMODE, Fa "int *" 403Return non-zero if editing is enabled.
| 415.Pp 416The following values for 417.Fa op 418are supported, along with actual type of 419.Fa result : 420.Bl -tag -width 4n 421.It Dv EL_PROMPT , Fa "char *(*f)(EditLine *)" 422Return a pointer to the function that displays the prompt. 423.It Dv EL_RPROMPT , Fa "char *(*f)(EditLine *)" 424Return a pointer to the function that displays the rightside prompt. 425.It Dv EL_EDITOR , Fa "const char *" 426Return the name of the editor, which will be one of 427.Dq emacs 428or 429.Dq vi . 430.It Dv EL_SIGNAL , Fa "int *" 431Return non-zero if 432.Nm 433has installed private signal handlers (see 434.Fn el_get 435above). 436.It Dv EL_EDITMODE, Fa "int *" 437Return non-zero if editing is enabled.
|
| 438.It Dv EL_GETCFN, Fa "int (**f)(EditLine *, char *)" 439Return a pointer to the function that read characters, which is equal to 440``EL_BUILTIN_GETCFN'' in the case of the default builtin function. 441.It Dv EL_CLIENTDATA , Fa "void **data" 442Retrieve 443.Fa data 444previously registered with the corresponding 445.Fn el_set 446call. 447.It Dv EL_UNBUFFERED, Fa "int" 448Sets or clears unbuffered mode. 449In this mode, 450.Fn el_gets 451will return immediately after processing a single character. 452.It Dv EL_PREP_TERM, Fa "int" 453Sets or clears terminal editing mode.
|
404.El 405.It Fn el_source 406Initialise 407.Nm 408by reading the contents of 409.Fa file . 410.Fn el_parse 411is called for each line in 412.Fa file . 413If 414.Fa file 415is 416.Dv NULL , 417try 418.Pa $PWD/.editrc 419then 420.Pa $HOME/.editrc . 421Refer to 422.Xr editrc 5 423for details on the format of 424.Fa file . 425.It Fn el_resize 426Must be called if the terminal size changes. 427If 428.Dv EL_SIGNAL 429has been set with 430.Fn el_set , 431then this is done automatically. 432Otherwise, it is the responsibility of the application to call 433.Fn el_resize 434on the appropriate occasions. 435.It Fn el_line 436Return the editing information for the current line in a 437.Fa LineInfo 438structure, which is defined as follows: 439.Bd -literal 440typedef struct lineinfo { 441 const char *buffer; /* address of buffer */ 442 const char *cursor; /* address of cursor */ 443 const char *lastchar; /* address of last character */ 444} LineInfo; 445.Ed
| 454.El 455.It Fn el_source 456Initialise 457.Nm 458by reading the contents of 459.Fa file . 460.Fn el_parse 461is called for each line in 462.Fa file . 463If 464.Fa file 465is 466.Dv NULL , 467try 468.Pa $PWD/.editrc 469then 470.Pa $HOME/.editrc . 471Refer to 472.Xr editrc 5 473for details on the format of 474.Fa file . 475.It Fn el_resize 476Must be called if the terminal size changes. 477If 478.Dv EL_SIGNAL 479has been set with 480.Fn el_set , 481then this is done automatically. 482Otherwise, it is the responsibility of the application to call 483.Fn el_resize 484on the appropriate occasions. 485.It Fn el_line 486Return the editing information for the current line in a 487.Fa LineInfo 488structure, which is defined as follows: 489.Bd -literal 490typedef struct lineinfo { 491 const char *buffer; /* address of buffer */ 492 const char *cursor; /* address of cursor */ 493 const char *lastchar; /* address of last character */ 494} LineInfo; 495.Ed
|
| 496.Pp 497.Fa buffer 498is not NUL terminated. 499This function may be called after 500.Fn el_gets 501to obtain the 502.Fa LineInfo 503structure pertaining to line returned by that function, 504and from within user defined functions added with 505.Dv EL_ADDFN .
|
446.It Fn el_insertstr 447Insert 448.Fa str 449into the line at the cursor.
| 506.It Fn el_insertstr 507Insert 508.Fa str 509into the line at the cursor.
|
450Returns -1 if
| 510Returns \-1 if
|
451.Fa str 452is empty or will not fit, and 0 otherwise. 453.It Fn el_deletestr 454Delete 455.Fa num 456characters before the cursor. 457.El 458.Sh HISTORY LIST FUNCTIONS 459The history functions use a common data structure, 460.Fa History , 461which is created by 462.Fn history_init 463and freed by 464.Fn history_end . 465.Pp 466The following functions are available: 467.Bl -tag -width 4n 468.It Fn history_init 469Initialise the history list, and return a data structure 470to be used by all other history list functions. 471.It Fn history_end 472Clean up and finish with 473.Fa h , 474assumed to have been created with 475.Fn history_init . 476.It Fn history 477Perform operation 478.Fa op 479on the history list, with optional arguments as needed by the 480operation. 481.Fa ev 482is changed accordingly to operation. 483The following values for 484.Fa op 485are supported, along with the required argument list: 486.Bl -tag -width 4n 487.It Dv H_SETSIZE , Fa "int size" 488Set size of history to 489.Fa size 490elements. 491.It Dv H_GETSIZE 492Get number of events currently in history. 493.It Dv H_END 494Cleans up and finishes with 495.Fa h , 496assumed to be created with 497.Fn history_init . 498.It Dv H_CLEAR 499Clear the history. 500.It Dv H_FUNC , Xo 501.Fa "void *ptr" , 502.Fa "history_gfun_t first" , 503.Fa "history_gfun_t next" , 504.Fa "history_gfun_t last" , 505.Fa "history_gfun_t prev" , 506.Fa "history_gfun_t curr" , 507.Fa "history_sfun_t set" , 508.Fa "history_vfun_t clear" , 509.Fa "history_efun_t enter" , 510.Fa "history_efun_t add" 511.Xc 512Define functions to perform various history operations. 513.Fa ptr 514is the argument given to a function when it is invoked. 515.It Dv H_FIRST 516Return the first element in the history. 517.It Dv H_LAST 518Return the last element in the history. 519.It Dv H_PREV 520Return the previous element in the history. 521.It Dv H_NEXT 522Return the next element in the history. 523.It Dv H_CURR 524Return the current element in the history. 525.It Dv H_SET 526Set the cursor to point to the requested element. 527.It Dv H_ADD , Fa "const char *str" 528Append 529.Fa str
| 511.Fa str 512is empty or will not fit, and 0 otherwise. 513.It Fn el_deletestr 514Delete 515.Fa num 516characters before the cursor. 517.El 518.Sh HISTORY LIST FUNCTIONS 519The history functions use a common data structure, 520.Fa History , 521which is created by 522.Fn history_init 523and freed by 524.Fn history_end . 525.Pp 526The following functions are available: 527.Bl -tag -width 4n 528.It Fn history_init 529Initialise the history list, and return a data structure 530to be used by all other history list functions. 531.It Fn history_end 532Clean up and finish with 533.Fa h , 534assumed to have been created with 535.Fn history_init . 536.It Fn history 537Perform operation 538.Fa op 539on the history list, with optional arguments as needed by the 540operation. 541.Fa ev 542is changed accordingly to operation. 543The following values for 544.Fa op 545are supported, along with the required argument list: 546.Bl -tag -width 4n 547.It Dv H_SETSIZE , Fa "int size" 548Set size of history to 549.Fa size 550elements. 551.It Dv H_GETSIZE 552Get number of events currently in history. 553.It Dv H_END 554Cleans up and finishes with 555.Fa h , 556assumed to be created with 557.Fn history_init . 558.It Dv H_CLEAR 559Clear the history. 560.It Dv H_FUNC , Xo 561.Fa "void *ptr" , 562.Fa "history_gfun_t first" , 563.Fa "history_gfun_t next" , 564.Fa "history_gfun_t last" , 565.Fa "history_gfun_t prev" , 566.Fa "history_gfun_t curr" , 567.Fa "history_sfun_t set" , 568.Fa "history_vfun_t clear" , 569.Fa "history_efun_t enter" , 570.Fa "history_efun_t add" 571.Xc 572Define functions to perform various history operations. 573.Fa ptr 574is the argument given to a function when it is invoked. 575.It Dv H_FIRST 576Return the first element in the history. 577.It Dv H_LAST 578Return the last element in the history. 579.It Dv H_PREV 580Return the previous element in the history. 581.It Dv H_NEXT 582Return the next element in the history. 583.It Dv H_CURR 584Return the current element in the history. 585.It Dv H_SET 586Set the cursor to point to the requested element. 587.It Dv H_ADD , Fa "const char *str" 588Append 589.Fa str
|
530to the current element of the history, or create an element with
| 590to the current element of the history, or perform the 591.Dv H_ENTER 592operation with argument 593.Fa str 594if there is no current element.
|
531.It Dv H_APPEND , Fa "const char *str" 532Append 533.Fa str 534to the last new element of the history. 535.It Dv H_ENTER , Fa "const char *str" 536Add 537.Fa str 538as a new element to the history, and, if necessary, 539removing the oldest entry to keep the list to the created size.
| 595.It Dv H_APPEND , Fa "const char *str" 596Append 597.Fa str 598to the last new element of the history. 599.It Dv H_ENTER , Fa "const char *str" 600Add 601.Fa str 602as a new element to the history, and, if necessary, 603removing the oldest entry to keep the list to the created size.
|
| 604If 605.Dv H_SETUNIQUE 606was has been called with a non-zero arguments, the element 607will not be entered into the history if its contents match 608the ones of the current history element. 609If the element is entered 610.Fn history 611returns 1, if it is ignored as a duplicate returns 0. 612Finally 613.Fn history 614returns \-1 if an error occurred.
|
540.It Dv H_PREV_STR , Fa "const char *str" 541Return the closest previous event that starts with 542.Fa str . 543.It Dv H_NEXT_STR , Fa "const char *str" 544Return the closest next event that starts with 545.Fa str . 546.It Dv H_PREV_EVENT , Fa "int e" 547Return the previous event numbered 548.Fa e . 549.It Dv H_NEXT_EVENT , Fa "int e" 550Return the next event numbered 551.Fa e . 552.It Dv H_LOAD , Fa "const char *file" 553Load the history list stored in 554.Fa file . 555.It Dv H_SAVE , Fa "const char *file" 556Save the history list to 557.Fa file .
| 615.It Dv H_PREV_STR , Fa "const char *str" 616Return the closest previous event that starts with 617.Fa str . 618.It Dv H_NEXT_STR , Fa "const char *str" 619Return the closest next event that starts with 620.Fa str . 621.It Dv H_PREV_EVENT , Fa "int e" 622Return the previous event numbered 623.Fa e . 624.It Dv H_NEXT_EVENT , Fa "int e" 625Return the next event numbered 626.Fa e . 627.It Dv H_LOAD , Fa "const char *file" 628Load the history list stored in 629.Fa file . 630.It Dv H_SAVE , Fa "const char *file" 631Save the history list to 632.Fa file .
|
| 633.It Dv H_SETUNIQUE , Fa "int unique" 634Set if the adjacent identical event strings should not be entered into 635the history. 636.It Dv H_GETUNIQUE 637Retrieve the current setting if if adjacent elements should be entered into 638the history. 639.It Dv H_DEL , Fa "int num" 640Delete the event numbered 641.Fa e . 642This function is only provided for 643.Xr readline 3 644compatibility. 645The caller is responsible for free'ing the string in the returned 646.Fa HistEvent .
|
558.El 559.Pp 560The 561.Fn history 562function returns 0 if the operation 563.Fa op 564succeeds. 565Otherwise, \-1 is returned and 566.Fa ev 567is updated to contain more details about the error. 568.El
| 647.El 648.Pp 649The 650.Fn history 651function returns 0 if the operation 652.Fa op 653succeeds. 654Otherwise, \-1 is returned and 655.Fa ev 656is updated to contain more details about the error. 657.El
|
| 658.Sh TOKENIZATION FUNCTIONS 659The tokenization functions use a common data structure, 660.Fa Tokenizer , 661which is created by 662.Fn tok_init 663and freed by 664.Fn tok_end . 665.Pp 666The following functions are available: 667.Bl -tag -width 4n 668.It Fn tok_init 669Initialise the tokenizer, and return a data structure 670to be used by all other tokenizer functions. 671.Fa IFS 672contains the Input Field Separators, which defaults to 673.Aq space , 674.Aq tab , 675and 676.Aq newline 677if 678.Dv NULL . 679.It Fn tok_end 680Clean up and finish with 681.Fa t , 682assumed to have been created with 683.Fn tok_init . 684.It Fn tok_reset 685Reset the tokenizer state. 686Use after a line has been successfully tokenized 687by 688.Fn tok_line 689or 690.Fn tok_str 691and before a new line is to be tokenized. 692.It Fn tok_line 693Tokenize 694.Fa li , 695If successful, modify: 696.Fa argv 697to contain the words, 698.Fa argc 699to contain the number of words, 700.Fa cursorc 701(if not 702.Dv NULL ) 703to contain the index of the word containing the cursor, 704and 705.Fa cursoro 706(if not 707.Dv NULL ) 708to contain the offset within 709.Fa argv[cursorc] 710of the cursor. 711.Pp 712Returns 7130 if successful, 714\-1 for an internal error, 7151 for an unmatched single quote, 7162 for an unmatched double quote, 717and 7183 for a backslash quoted 719.Aq newline . 720A positive exit code indicates that another line should be read 721and tokenization attempted again. 722. 723.It Fn tok_str 724A simpler form of 725.Fn tok_line ; 726.Fa str 727is a NUL terminated string to tokenize. 728.El 729.
|
569.\"XXX.Sh EXAMPLES 570.\"XXX: provide some examples 571.Sh SEE ALSO 572.Xr sh 1 , 573.Xr signal 3 , 574.Xr termcap 3 , 575.Xr editrc 5 576.Sh HISTORY 577The 578.Nm 579library first appeared in 580.Bx 4.4 . 581.Dv CC_REDISPLAY 582appeared in 583.Nx 1.3 . 584.Dv CC_REFRESH_BEEP 585and 586.Dv EL_EDITMODE 587appeared in 588.Nx 1.4 . 589.Dv EL_RPROMPT 590appeared in 591.Nx 1.5 . 592.Sh AUTHORS 593.An -nosplit 594The 595.Nm 596library was written by 597.An Christos Zoulas . 598.An Luke Mewburn 599wrote this manual and implemented 600.Dv CC_REDISPLAY , 601.Dv CC_REFRESH_BEEP , 602.Dv EL_EDITMODE , 603and 604.Dv EL_RPROMPT . 605.Sh BUGS
| 730.\"XXX.Sh EXAMPLES 731.\"XXX: provide some examples 732.Sh SEE ALSO 733.Xr sh 1 , 734.Xr signal 3 , 735.Xr termcap 3 , 736.Xr editrc 5 737.Sh HISTORY 738The 739.Nm 740library first appeared in 741.Bx 4.4 . 742.Dv CC_REDISPLAY 743appeared in 744.Nx 1.3 . 745.Dv CC_REFRESH_BEEP 746and 747.Dv EL_EDITMODE 748appeared in 749.Nx 1.4 . 750.Dv EL_RPROMPT 751appeared in 752.Nx 1.5 . 753.Sh AUTHORS 754.An -nosplit 755The 756.Nm 757library was written by 758.An Christos Zoulas . 759.An Luke Mewburn 760wrote this manual and implemented 761.Dv CC_REDISPLAY , 762.Dv CC_REFRESH_BEEP , 763.Dv EL_EDITMODE , 764and 765.Dv EL_RPROMPT . 766.Sh BUGS
|
606The tokenization functions are not publically defined in 607.In histedit.h . 608.Pp
| |
609At this time, it is the responsibility of the caller to 610check the result of the 611.Dv EL_EDITMODE 612operation of 613.Fn el_get 614(after an 615.Fn el_source 616or 617.Fn el_parse ) 618to determine if 619.Nm 620should be used for further input. 621I.e., 622.Dv EL_EDITMODE 623is purely an indication of the result of the most recent 624.Xr editrc 5 625.Ic edit 626command.
| 767At this time, it is the responsibility of the caller to 768check the result of the 769.Dv EL_EDITMODE 770operation of 771.Fn el_get 772(after an 773.Fn el_source 774or 775.Fn el_parse ) 776to determine if 777.Nm 778should be used for further input. 779I.e., 780.Dv EL_EDITMODE 781is purely an indication of the result of the most recent 782.Xr editrc 5 783.Ic edit 784command.
|