1.\" $NetBSD: editline.3,v 1.98 2017/09/02 06:48:10 wiz Exp $ 2.\" 3.\" Copyright (c) 1997-2014 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.\" 17.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 18.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 19.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 20.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 21.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 22.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 23.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 24.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 25.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 26.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 27.\" POSSIBILITY OF SUCH DAMAGE. 28.\" 29.Dd September 1, 2017 30.Dt EDITLINE 3 31.Os 32.Sh NAME 33.Nm editline , 34.Nm el_init , 35.Nm el_init_fd , 36.Nm el_end , 37.Nm el_reset , 38.Nm el_gets , 39.Nm el_wgets , 40.Nm el_getc , 41.Nm el_wgetc , 42.Nm el_push , 43.Nm el_wpush , 44.Nm el_parse , 45.Nm el_wparse , 46.Nm el_set , 47.Nm el_wset , 48.Nm el_get , 49.Nm el_wget , 50.Nm el_source , 51.Nm el_resize , 52.Nm el_cursor , 53.Nm el_line , 54.Nm el_wline , 55.Nm el_insertstr , 56.Nm el_winsertstr , 57.Nm el_deletestr , 58.Nm el_wdeletestr , 59.Nm history_init , 60.Nm history_winit , 61.Nm history_end , 62.Nm history_wend , 63.Nm history , 64.Nm history_w , 65.Nm tok_init , 66.Nm tok_winit , 67.Nm tok_end , 68.Nm tok_wend , 69.Nm tok_reset , 70.Nm tok_wreset , 71.Nm tok_line , 72.Nm tok_wline , 73.Nm tok_str , 74.Nm tok_wstr 75.Nd line editor, history and tokenization functions 76.Sh LIBRARY 77.Lb libedit 78.Sh SYNOPSIS 79.In histedit.h 80.Ft EditLine * 81.Fn el_init "const char *prog" "FILE *fin" "FILE *fout" "FILE *ferr" 82.Ft EditLine * 83.Fn el_init_fd "const char *prog" "FILE *fin" "FILE *fout" "FILE *ferr" "int fdin" "int fdout" "int fderr" 84.Ft void 85.Fn el_end "EditLine *e" 86.Ft void 87.Fn el_reset "EditLine *e" 88.Ft const char * 89.Fn el_gets "EditLine *e" "int *count" 90.Ft const wchar_t * 91.Fn el_wgets "EditLine *e" "int *count" 92.Ft int 93.Fn el_getc "EditLine *e" "char *ch" 94.Ft int 95.Fn el_wgetc "EditLine *e" "wchar_t *wc" 96.Ft void 97.Fn el_push "EditLine *e" "const char *mbs" 98.Ft void 99.Fn el_wpush "EditLine *e" "const wchar_t *wcs" 100.Ft int 101.Fn el_parse "EditLine *e" "int argc" "const char *argv[]" 102.Ft int 103.Fn el_wparse "EditLine *e" "int argc" "const wchar_t *argv[]" 104.Ft int 105.Fn el_set "EditLine *e" "int op" "..." 106.Ft int 107.Fn el_wset "EditLine *e" "int op" "..." 108.Ft int 109.Fn el_get "EditLine *e" "int op" "..." 110.Ft int 111.Fn el_wget "EditLine *e" "int op" "..." 112.Ft int 113.Fn el_source "EditLine *e" "const char *file" 114.Ft void 115.Fn el_resize "EditLine *e" 116.Ft int 117.Fn el_cursor "EditLine *e" "int count" 118.Ft const LineInfo * 119.Fn el_line "EditLine *e" 120.Ft const LineInfoW * 121.Fn el_wline "EditLine *e" 122.Ft int 123.Fn el_insertstr "EditLine *e" "const char *str" 124.Ft int 125.Fn el_winsertstr "EditLine *e" "const wchar_t *str" 126.Ft void 127.Fn el_deletestr "EditLine *e" "int count" 128.Ft void 129.Fn el_wdeletestr "EditLine *e" "int count" 130.Ft History * 131.Fn history_init void 132.Ft HistoryW * 133.Fn history_winit void 134.Ft void 135.Fn history_end "History *h" 136.Ft void 137.Fn history_wend "HistoryW *h" 138.Ft int 139.Fn history "History *h" "HistEvent *ev" "int op" "..." 140.Ft int 141.Fn history_w "HistoryW *h" "HistEventW *ev" "int op" "..." 142.Ft Tokenizer * 143.Fn tok_init "const char *IFS" 144.Ft TokenizerW * 145.Fn tok_winit "const wchar_t *IFS" 146.Ft void 147.Fn tok_end "Tokenizer *t" 148.Ft void 149.Fn tok_wend "TokenizerW *t" 150.Ft void 151.Fn tok_reset "Tokenizer *t" 152.Ft void 153.Fn tok_wreset "TokenizerW *t" 154.Ft int 155.Fn tok_line "Tokenizer *t" "const LineInfo *li" "int *argc" "const char **argv[]" "int *cursorc" "int *cursoro" 156.Ft int 157.Fn tok_wline "TokenizerW *t" "const LineInfoW *li" "int *argc" "const wchar_t **argv[]" "int *cursorc" "int *cursoro" 158.Ft int 159.Fn tok_str "Tokenizer *t" "const char *str" "int *argc" "const char **argv[]" 160.Ft int 161.Fn tok_wstr "TokenizerW *t" "const wchar_t *str" "int *argc" "const wchar_t **argv[]" 162.Sh DESCRIPTION 163The 164.Nm 165library provides generic line editing, history and tokenization functions, 166similar to those found in 167.Xr sh 1 . 168.Pp 169These functions are available in the 170.Nm libedit 171library (which needs the 172.Nm libtermcap 173library). 174Programs should be linked with 175.Fl ledit ltermcap . 176.Pp 177The 178.Nm 179library respects the 180.Ev LC_CTYPE 181locale set by the application program and never uses 182.Xr setlocale 3 183to change the locale. 184The only locales supported are UTF-8 and the default C or POSIX locale. 185If any other locale is set, behaviour is undefined. 186.Sh LINE EDITING FUNCTIONS 187The line editing functions use a common data structure, 188.Fa EditLine , 189which is created by 190.Fn el_init 191or 192.Fn el_init_fd 193and freed by 194.Fn el_end . 195.Pp 196The wide-character functions behave the same way as their narrow 197counterparts. 198.Pp 199The following functions are available: 200.Bl -tag -width 4n 201.It Fn el_init 202Initialize the line editor, and return a data structure 203to be used by all other line editing functions, or 204.Dv NULL 205on failure. 206.Fa prog 207is the name of the invoking program, used when reading the 208.Xr editrc 5 209file to determine which settings to use. 210.Fa fin , 211.Fa fout 212and 213.Fa ferr 214are the input, output, and error streams (respectively) to use. 215In this documentation, references to 216.Dq the tty 217are actually to this input/output stream combination. 218.It Fn el_init_fd 219Like 220.Fn el_init 221but allows specifying file descriptors for the 222.Xr stdio 3 223corresponding streams, in case those were created with 224.Xr funopen 3 . 225.It Fn el_end 226Clean up and finish with 227.Fa e , 228assumed to have been created with 229.Fn el_init 230or 231.Fn el_init_fd . 232.It Fn el_reset 233Reset the tty and the parser. 234This should be called after an error which may have upset the tty's 235state. 236.It Fn el_gets 237Read a line from the tty. 238.Fa count 239is modified to contain the number of characters read. 240Returns the line read if successful, or 241.Dv NULL 242if no characters were read or if an error occurred. 243If an error occurred, 244.Fa count 245is set to \-1 and 246.Dv errno 247contains the error code that caused it. 248The return value may not remain valid across calls to 249.Fn el_gets 250and must be copied if the data is to be retained. 251.It Fn el_wgetc 252Read a wide character from the tty, respecting the current locale, 253or from the input queue described in 254.Xr editline 7 255if that is not empty, and store it in 256.Fa wc . 257If an invalid or incomplete character is found, it is discarded, 258.Va errno 259is set to 260.Er EILSEQ , 261and the next character is read and stored in 262.Fa wc . 263Returns 1 if a valid character was read, 0 on end of file, or \-1 on 264.Xr read 2 265failure. 266In the latter case, 267.Va errno 268is set to indicate the error. 269.It Fn el_getc 270Read a wide character as described for 271.Fn el_wgetc 272and return 0 on end of file or \-1 on failure. 273If the wide character can be represented as a single-byte character, 274convert it with 275.Xr wctob 3 , 276store the result in 277.Fa ch , 278and return 1; otherwise, set 279.Va errno 280to 281.Er ERANGE 282and return \-1. 283In the C or POSIX locale, this simply reads a byte, but for any other 284locale, including UTF-8, this is rarely useful. 285.It Fn el_wpush 286Push the wide character string 287.Fa wcs 288back onto the input queue described in 289.Xr editline 7 . 290If the queue overflows, for example due to a recursive macro, 291or if an error occurs, for example because 292.Fa wcs 293is 294.Dv NULL 295or memory allocation fails, the function beeps at the user, 296but does not report the problem to the caller. 297.It Fn el_push 298Use the current locale to convert the multibyte string 299.Fa mbs 300to a wide character string, and pass the result to 301.Fn el_wpush . 302.It Fn el_parse 303Parses the 304.Fa argv 305array (which is 306.Fa argc 307elements in size) 308to execute builtin 309.Nm 310commands. 311If the command is prefixed with 312.Dq prog : 313then 314.Fn el_parse 315will only execute the command if 316.Dq prog 317matches the 318.Fa prog 319argument supplied to 320.Fn el_init . 321The return value is 322\-1 if the command is unknown, 3230 if there was no error or 324.Dq prog 325didn't match, or 3261 if the command returned an error. 327Refer to 328.Xr editrc 5 329for more information. 330.It Fn el_set 331Set 332.Nm 333parameters. 334.Fa op 335determines which parameter to set, and each operation has its 336own parameter list. 337Returns 0 on success, \-1 on failure. 338.Pp 339The following values for 340.Fa op 341are supported, along with the required argument list: 342.Bl -tag -width 4n 343.It Dv EL_PROMPT , Fa "char *(*f)(EditLine *)" 344Define prompt printing function as 345.Fa f , 346which is to return a string that contains the prompt. 347.It Dv EL_PROMPT_ESC , Fa "char *(*f)(EditLine *)" , Fa "char c" 348Same as 349.Dv EL_PROMPT , 350but the 351.Fa c 352argument indicates the start/stop literal prompt character. 353.Pp 354If a start/stop literal character is found in the prompt, the 355character itself 356is not printed, but characters after it are printed directly to the 357terminal without affecting the state of the current line. 358A subsequent second start/stop literal character ends this behavior. 359This is typically used to embed literal escape sequences that change the 360color/style of the terminal in the prompt. 361Note that the literal escape character cannot be the last character in the 362prompt, as the escape sequence is attached to the next character in the prompt. 363.Dv 0 364unsets it. 365.It Dv EL_REFRESH 366Re-display the current line on the next terminal line. 367.It Dv EL_RPROMPT , Fa "char *(*f)(EditLine *)" 368Define right side prompt printing function as 369.Fa f , 370which is to return a string that contains the prompt. 371.It Dv EL_RPROMPT_ESC , Fa "char *(*f)(EditLine *)" , Fa "char c" 372Define the right prompt printing function but with a literal escape character. 373.It Dv EL_TERMINAL , Fa "const char *type" 374Define terminal type of the tty to be 375.Fa type , 376or to 377.Ev TERM 378if 379.Fa type 380is 381.Dv NULL . 382.It Dv EL_EDITOR , Fa "const char *mode" 383Set editing mode to 384.Fa mode , 385which must be one of 386.Dq emacs 387or 388.Dq vi . 389.It Dv EL_SIGNAL , Fa "int flag" 390If 391.Fa flag 392is non-zero, 393.Nm 394will install its own signal handler for the following signals when 395reading command input: 396.Dv SIGCONT , 397.Dv SIGHUP , 398.Dv SIGINT , 399.Dv SIGQUIT , 400.Dv SIGSTOP , 401.Dv SIGTERM , 402.Dv SIGTSTP , 403and 404.Dv SIGWINCH . 405Otherwise, the current signal handlers will be used. 406.It Dv EL_BIND , Fa "const char *" , Fa "..." , Dv NULL 407Perform the 408.Ic bind 409builtin command. 410Refer to 411.Xr editrc 5 412for more information. 413.It Dv EL_ECHOTC , Fa "const char *" , Fa "..." , Dv NULL 414Perform the 415.Ic echotc 416builtin command. 417Refer to 418.Xr editrc 5 419for more information. 420.It Dv EL_SETTC , Fa "const char *" , Fa "..." , Dv NULL 421Perform the 422.Ic settc 423builtin command. 424Refer to 425.Xr editrc 5 426for more information. 427.It Dv EL_SETTY , Fa "const char *" , Fa "..." , Dv NULL 428Perform the 429.Ic setty 430builtin command. 431Refer to 432.Xr editrc 5 433for more information. 434.It Dv EL_TELLTC , Fa "const char *" , Fa "..." , Dv NULL 435Perform the 436.Ic telltc 437builtin command. 438Refer to 439.Xr editrc 5 440for more information. 441.It Dv EL_ADDFN , Fa "const char *name" , Fa "const char *help" , \ 442Fa "unsigned char (*func)(EditLine *e, int ch)" 443Add a user defined function, 444.Fn func , 445referred to as 446.Fa name 447which is invoked when a key which is bound to 448.Fa name 449is entered. 450.Fa help 451is a description of 452.Fa name . 453At invocation time, 454.Fa ch 455is the key which caused the invocation. 456The return value of 457.Fn func 458should be one of: 459.Bl -tag -width "CC_REDISPLAY" 460.It Dv CC_NORM 461Add a normal character. 462.It Dv CC_NEWLINE 463End of line was entered. 464.It Dv CC_EOF 465EOF was entered. 466.It Dv CC_ARGHACK 467Expecting further command input as arguments, do nothing visually. 468.It Dv CC_REFRESH 469Refresh display. 470.It Dv CC_REFRESH_BEEP 471Refresh display, and beep. 472.It Dv CC_CURSOR 473Cursor moved, so update and perform 474.Dv CC_REFRESH . 475.It Dv CC_REDISPLAY 476Redisplay entire input line. 477This is useful if a key binding outputs extra information. 478.It Dv CC_ERROR 479An error occurred. 480Beep, and flush tty. 481.It Dv CC_FATAL 482Fatal error, reset tty to known state. 483.El 484.It Dv EL_HIST , Fa "History *(*func)(History *, int op, ...)" , \ 485Fa "const char *ptr" 486Defines which history function to use, which is usually 487.Fn history . 488.Fa ptr 489should be the value returned by 490.Fn history_init . 491.It Dv EL_EDITMODE , Fa "int flag" 492If 493.Fa flag 494is non-zero, 495editing is enabled (the default). 496Note that this is only an indication, and does not 497affect the operation of 498.Nm . 499At this time, it is the caller's responsibility to 500check this 501(using 502.Fn el_get ) 503to determine if editing should be enabled or not. 504.It Dv EL_UNBUFFERED , Fa "int flag" 505If 506.Fa flag 507is zero, 508unbuffered mode is disabled (the default). 509In unbuffered mode, 510.Fn el_gets 511will return immediately after processing a single character. 512.It Dv EL_GETCFN , Fa "el_rfunc_t f" 513Whenever reading a character, use the function 514.Bd -ragged -offset indent -compact 515.Ft int 516.Fo f 517.Fa "EditLine *e" 518.Fa "wchar_t *wc" 519.Fc 520.Ed 521which stores the character in 522.Fa wc 523and returns 1 on success, 0 on end of file, or \-1 on I/O or encoding 524errors. 525Functions internally using it include 526.Fn el_wgets , 527.Fn el_wgetc , 528.Fn el_gets , 529and 530.Fn el_getc . 531Initially, a builtin function is installed, and replacing it 532is discouraged because writing such a function is very error prone. 533The builtin function can be restored at any time by passing the 534special value 535.Dv EL_BUILTIN_GETCFN 536instead of a function pointer. 537.It Dv EL_CLIENTDATA , Fa "void *data" 538Register 539.Fa data 540to be associated with this EditLine structure. 541It can be retrieved with the corresponding 542.Fn el_get 543call. 544.It Dv EL_SETFP , Fa "int fd" , Fa "FILE *fp" 545Set the current 546.Nm editline 547file pointer for 548.Dq input 549.Fa fd 550= 551.Dv 0 , 552.Dq output 553.Fa fd 554= 555.Dv 1 , 556or 557.Dq error 558.Fa fd 559= 560.Dv 2 561from 562.Fa fp . 563.El 564.It Fn el_get 565Get 566.Nm 567parameters. 568.Fa op 569determines which parameter to retrieve into 570.Fa result . 571Returns 0 if successful, \-1 otherwise. 572.Pp 573The following values for 574.Fa op 575are supported, along with actual type of 576.Fa result : 577.Bl -tag -width 4n 578.It Dv EL_PROMPT , Fa "char *(*f)(EditLine *)" , Fa "char *c" 579Set 580.Fa f 581to a pointer to the function that displays the prompt. 582If 583.Fa c 584is not 585.Dv NULL , 586set it to the start/stop literal prompt character. 587.It Dv EL_RPROMPT , Fa "char *(*f)(EditLine *)" , Fa "char *c" 588Set 589.Fa f 590to a pointer to the function that displays the prompt. 591If 592.Fa c 593is not 594.Dv NULL , 595set it to the start/stop literal prompt character. 596.It Dv EL_EDITOR , Fa "const char **n" 597Set the name of the editor in 598.Fa n , 599which will be one of 600.Dq emacs 601or 602.Dq vi . 603.It Dv EL_GETTC , Fa "const char *name" , Fa "void *value" 604If 605.Fa name 606is a valid 607.Xr termcap 5 608capability set 609.Fa value 610to the current value of that capability. 611.It Dv EL_SIGNAL , Fa "int *s" 612Set 613.Fa s 614to non-zero if 615.Nm 616has installed private signal handlers (see 617.Fn el_get 618above). 619.It Dv EL_EDITMODE , Fa "int *c" 620Set 621.Fa c 622to non-zero if editing is enabled. 623.It Dv EL_GETCFN , Fa "el_rfunc_t *f" 624Set 625.Fa f 626to a pointer to the function that reads characters, or to 627.Dv EL_BUILTIN_GETCFN 628if the builtin function is in use. 629.It Dv EL_CLIENTDATA , Fa "void **data" 630Set 631.Fa data 632to the previously registered client data set by an 633.Fn el_set 634call. 635.It Dv EL_UNBUFFERED , Fa "int *c" 636Set 637.Fa c 638to non-zero if unbuffered mode is enabled. 639.It Dv EL_GETFP , Fa "int fd", Fa "FILE **fp" 640Set 641.Fa fp 642to the current 643.Nm editline 644file pointer for 645.Dq input 646.Fa fd 647= 648.Dv 0 , 649.Dq output 650.Fa fd 651= 652.Dv 1 , 653or 654.Dq error 655.Fa fd 656= 657.Dv 2 . 658.El 659.It Fn el_source 660Initialize 661.Nm 662by reading the contents of 663.Fa file . 664.Fn el_parse 665is called for each line in 666.Fa file . 667If 668.Fa file 669is 670.Dv NULL , 671try 672.Pa $EDITRC 673and if that is not set 674.Pa $HOME/.editrc . 675Refer to 676.Xr editrc 5 677for details on the format of 678.Fa file . 679.Fn el_source 680returns 0 on success and \-1 on error. 681.It Fn el_resize 682Must be called if the terminal size changes. 683If 684.Dv EL_SIGNAL 685has been set with 686.Fn el_set , 687then this is done automatically. 688Otherwise, it's the responsibility of the application to call 689.Fn el_resize 690on the appropriate occasions. 691.It Fn el_cursor 692Move the cursor to the right (if positive) or to the left (if negative) 693.Fa count 694characters. 695Returns the resulting offset of the cursor from the beginning of the line. 696.It Fn el_line 697Return the editing information for the current line in a 698.Fa LineInfo 699structure, which is defined as follows: 700.Bd -literal 701typedef struct lineinfo { 702 const char *buffer; /* address of buffer */ 703 const char *cursor; /* address of cursor */ 704 const char *lastchar; /* address of last character */ 705} LineInfo; 706.Ed 707.Pp 708.Fa buffer 709is not NUL terminated. 710This function may be called after 711.Fn el_gets 712to obtain the 713.Fa LineInfo 714structure pertaining to line returned by that function, 715and from within user defined functions added with 716.Dv EL_ADDFN . 717.It Fn el_insertstr 718Insert 719.Fa str 720into the line at the cursor. 721Returns \-1 if 722.Fa str 723is empty or won't fit, and 0 otherwise. 724.It Fn el_deletestr 725Delete 726.Fa count 727characters before the cursor. 728.El 729.Sh HISTORY LIST FUNCTIONS 730The history functions use a common data structure, 731.Fa History , 732which is created by 733.Fn history_init 734and freed by 735.Fn history_end . 736.Pp 737The following functions are available: 738.Bl -tag -width 4n 739.It Fn history_init 740Initialize the history list, and return a data structure 741to be used by all other history list functions, or 742.Dv NULL 743on failure. 744.It Fn history_end 745Clean up and finish with 746.Fa h , 747assumed to have been created with 748.Fn history_init . 749.It Fn history 750Perform operation 751.Fa op 752on the history list, with optional arguments as needed by the 753operation. 754.Fa ev 755is changed accordingly to operation. 756The following values for 757.Fa op 758are supported, along with the required argument list: 759.Bl -tag -width 4n 760.It Dv H_SETSIZE , Fa "int size" 761Set size of history to 762.Fa size 763elements. 764.It Dv H_GETSIZE 765Get number of events currently in history. 766.It Dv H_END 767Cleans up and finishes with 768.Fa h , 769assumed to be created with 770.Fn history_init . 771.It Dv H_CLEAR 772Clear the history. 773.It Dv H_FUNC , Fa "void *ptr" , Fa "history_gfun_t first" , \ 774Fa "history_gfun_t next" , Fa "history_gfun_t last" , \ 775Fa "history_gfun_t prev" , Fa "history_gfun_t curr" , \ 776Fa "history_sfun_t set" , Fa "history_vfun_t clear" , \ 777Fa "history_efun_t enter" , Fa "history_efun_t add" 778Define functions to perform various history operations. 779.Fa ptr 780is the argument given to a function when it's invoked. 781.It Dv H_FIRST 782Return the first element in the history. 783.It Dv H_LAST 784Return the last element in the history. 785.It Dv H_PREV 786Return the previous element in the history. 787It is newer than the current one. 788.It Dv H_NEXT 789Return the next element in the history. 790It is older than the current one. 791.It Dv H_CURR 792Return the current element in the history. 793.It Dv H_SET , Fa "int position" 794Set the cursor to point to the requested element. 795.It Dv H_ADD , Fa "const char *str" 796Append 797.Fa str 798to the current element of the history, or perform the 799.Dv H_ENTER 800operation with argument 801.Fa str 802if there is no current element. 803.It Dv H_APPEND , Fa "const char *str" 804Append 805.Fa str 806to the last new element of the history. 807.It Dv H_ENTER , Fa "const char *str" 808Add 809.Fa str 810as a new element to the history and, if necessary, 811removing the oldest entry to keep the list to the created size. 812If 813.Dv H_SETUNIQUE 814has been called with a non-zero argument, the element 815will not be entered into the history if its contents match 816the ones of the current history element. 817If the element is entered 818.Fn history 819returns 1; if it is ignored as a duplicate returns 0. 820Finally 821.Fn history 822returns \-1 if an error occurred. 823.It Dv H_PREV_STR , Fa "const char *str" 824Return the closest previous event that starts with 825.Fa str . 826.It Dv H_NEXT_STR , Fa "const char *str" 827Return the closest next event that starts with 828.Fa str . 829.It Dv H_PREV_EVENT , Fa "int e" 830Return the previous event numbered 831.Fa e . 832.It Dv H_NEXT_EVENT , Fa "int e" 833Return the next event numbered 834.Fa e . 835.It Dv H_LOAD , Fa "const char *file" 836Load the history list stored in 837.Fa file . 838.It Dv H_SAVE , Fa "const char *file" 839Save the history list to 840.Fa file . 841.It Dv H_SAVE_FP , Fa "FILE *fp" 842Save the history list to the opened 843.Ft FILE 844pointer 845.Fa fp . 846.It Dv H_NSAVE_FP , Fa "size_t n" , Fa "FILE *fp" 847Save the last 848.Ft n 849history entries to the opened 850.Ft FILE 851pointer 852.Fa fp . 853.It Dv H_SETUNIQUE , Fa "int unique" 854Set flag that adjacent identical event strings should not be entered 855into the history. 856.It Dv H_GETUNIQUE 857Retrieve the current setting if adjacent identical elements should 858be entered into the history. 859.It Dv H_DEL , Fa "int e" 860Delete the event numbered 861.Fa e . 862This function is only provided for 863.Nm readline 864compatibility. 865The caller is responsible for free'ing the string in the returned 866.Fa HistEvent . 867.El 868.Pp 869.Fn history 870returns >= 0 if the operation 871.Fa op 872succeeds. 873Otherwise, \-1 is returned and 874.Fa ev 875is updated to contain more details about the error. 876.El 877.Sh TOKENIZATION FUNCTIONS 878The tokenization functions use a common data structure, 879.Fa Tokenizer , 880which is created by 881.Fn tok_init 882and freed by 883.Fn tok_end . 884.Pp 885The following functions are available: 886.Bl -tag -width 4n 887.It Fn tok_init 888Initialize the tokenizer, and return a data structure 889to be used by all other tokenizer functions. 890.Fa IFS 891contains the Input Field Separators, which defaults to 892.Aq space , 893.Aq tab , 894and 895.Aq newline 896if 897.Dv NULL . 898.It Fn tok_end 899Clean up and finish with 900.Fa t , 901assumed to have been created with 902.Fn tok_init . 903.It Fn tok_reset 904Reset the tokenizer state. 905Use after a line has been successfully tokenized 906by 907.Fn tok_line 908or 909.Fn tok_str 910and before a new line is to be tokenized. 911.It Fn tok_line 912Tokenize 913.Fa li , 914If successful, modify: 915.Fa argv 916to contain the words, 917.Fa argc 918to contain the number of words, 919.Fa cursorc 920(if not 921.Dv NULL ) 922to contain the index of the word containing the cursor, 923and 924.Fa cursoro 925(if not 926.Dv NULL ) 927to contain the offset within 928.Fa argv[cursorc] 929of the cursor. 930.Pp 931Returns 9320 if successful, 933\-1 for an internal error, 9341 for an unmatched single quote, 9352 for an unmatched double quote, 936and 9373 for a backslash quoted 938.Aq newline . 939A positive exit code indicates that another line should be read 940and tokenization attempted again. 941. 942.It Fn tok_str 943A simpler form of 944.Fn tok_line ; 945.Fa str 946is a NUL terminated string to tokenize. 947.El 948. 949.\"XXX.Sh EXAMPLES 950.\"XXX: provide some examples 951.Sh SEE ALSO 952.Xr sh 1 , 953.Xr signal 3 , 954.Xr termcap 3 , 955.Xr editrc 5 , 956.Xr termcap 5 , 957.Xr editline 7 958.Sh HISTORY 959The 960.Nm 961library first appeared in 962.Bx 4.4 . 963.Dv CC_REDISPLAY 964appeared in 965.Nx 1.3 . 966.Dv CC_REFRESH_BEEP , 967.Dv EL_EDITMODE 968and the readline emulation appeared in 969.Nx 1.4 . 970.Dv EL_RPROMPT 971appeared in 972.Nx 1.5 . 973.Sh AUTHORS 974.An -nosplit 975The 976.Nm 977library was written by 978.An Christos Zoulas . 979.An Luke Mewburn 980wrote this manual and implemented 981.Dv CC_REDISPLAY , 982.Dv CC_REFRESH_BEEP , 983.Dv EL_EDITMODE , 984and 985.Dv EL_RPROMPT . 986.An Jaromir Dolecek 987implemented the readline emulation. 988.An Johny Mattsson 989implemented wide-character support. 990.Sh BUGS 991At this time, it is the responsibility of the caller to 992check the result of the 993.Dv EL_EDITMODE 994operation of 995.Fn el_get 996(after an 997.Fn el_source 998or 999.Fn el_parse ) 1000to determine if 1001.Nm 1002should be used for further input. 1003I.e., 1004.Dv EL_EDITMODE 1005is purely an indication of the result of the most recent 1006.Xr editrc 5 1007.Ic edit 1008command. 1009