1.\" $NetBSD: editline.3,v 1.48 2005/07/14 15:02:37 wiz Exp $ |
2.\" |
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.\" |
36.\" $FreeBSD: head/lib/libedit/editline.3 148834 2005-08-07 20:55:59Z stefanf $ |
37.\" |
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 , |
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 |
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 |
82.Fn el_parse "EditLine *e" "int argc" "const char *argv[]" |
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[]" |
113.Sh DESCRIPTION 114The 115.Nm |
116library provides generic line editing, history and tokenization functions, |
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. |
172Returns the number of characters read if successful, \-1 otherwise. |
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 |
194.Dq prog : |
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 |
204\-1 if the command is unknown, |
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" , |
323.Fa "unsigned char (*func)(EditLine *e, int ch)" |
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. |
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. |
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. |
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 . |
506.It Fn el_insertstr 507Insert 508.Fa str 509into the line at the cursor. |
510Returns \-1 if |
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 |
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. |
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. |
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 . |
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. |
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 |
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. |