lib/libedit/editline.3

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