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