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