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