6/lib/libedit/editline.3

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