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