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