| editline.3 (141851) | editline.3 (148834) |
|---|---|
| 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 --- 16 unchanged lines hidden (view full) --- 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 --- 16 unchanged lines hidden (view full) --- 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" --- 4 unchanged lines hidden (view full) --- 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" --- 4 unchanged lines hidden (view full) --- 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). --- 39 unchanged lines hidden (view full) --- 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). --- 39 unchanged lines hidden (view full) --- 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 --- 5 unchanged lines hidden (view full) --- 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 --- 5 unchanged lines hidden (view full) --- 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 --- 102 unchanged lines hidden (view full) --- 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 --- 102 unchanged lines hidden (view full) --- 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. --- 48 unchanged lines hidden (view full) --- 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. --- 48 unchanged lines hidden (view full) --- 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. --- 7 unchanged lines hidden (view full) --- 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. --- 7 unchanged lines hidden (view full) --- 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 --- 26 unchanged lines hidden (view full) --- 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 --- 26 unchanged lines hidden (view full) --- 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 --- 63 unchanged lines hidden (view full) --- 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 --- 63 unchanged lines hidden (view full) --- 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 --- 21 unchanged lines hidden (view full) --- 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 --- 21 unchanged lines hidden (view full) --- 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. |