lib/libedit/editline.3

   1 .\"     $NetBSD: editline.3,v 1.4 1997/01/14 04:17:23 lukem Exp $
   2 .\"
   3 .\" Copyright (c) 1997 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 REGENTS OR CONTRIBUTORS BE
  28 .\" 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 .\" $FreeBSD: src/lib/libedit/editline.3,v 1.8.2.7 2001/12/17 10:08:30 ru Exp $
  37 .\" $DragonFly: src/lib/libedit/editline.3,v 1.2 2003/06/17 04:26:49 dillon Exp $
  38 .\"
  39 .Dd January 11, 1997
  40 .Os
  41 .Dt EDITLINE 3
  42 .Sh NAME
  43 .Nm editline ,
  44 .Nm el_init ,
  45 .Nm el_end ,
  46 .Nm el_reset ,
  47 .Nm el_gets ,
  48 .Nm el_getc ,
  49 .Nm el_push ,
  50 .Nm el_parse ,
  51 .Nm el_set ,
  52 .Nm el_source ,
  53 .Nm el_resize ,
  54 .Nm el_line ,
  55 .Nm el_insertstr ,
  56 .Nm el_deletestr ,
  57 .Nm el_data_set ,
  58 .Nm el_data_get ,
  59 .Nm history_init ,
  60 .Nm history_end ,
  61 .Nm history
  62 .Nd line editor and history functions
  63 .Sh LIBRARY
  64 .Lb libedit
  65 .Sh SYNOPSIS
  66 .In histedit.h
  67 .Ft EditLine *
  68 .Fn el_init "const char *prog" "FILE *fin" "FILE *fout"
  69 .Ft void
  70 .Fn el_end "EditLine *e"
  71 .Ft void
  72 .Fn el_reset "EditLine *e"
  73 .Ft const char *
  74 .Fn el_gets "EditLine *e" "int *count"
  75 .Ft int
  76 .Fn el_getc "EditLine *e" "char *ch"
  77 .Ft void
  78 .Fn el_push "EditLine *e" "const char *str"
  79 .Ft int
  80 .Fn el_parse "EditLine *e" "int argc" "char *argv[]"
  81 .Ft int
  82 .Fn el_set "EditLine *e" "int op" "..."
  83 .Ft int
  84 .Fn el_source "EditLine *e" "const char *file"
  85 .Ft void
  86 .Fn el_resize "EditLine *e"
  87 .Ft const LineInfo *
  88 .Fn el_line "EditLine *e"
  89 .Ft int
  90 .Fn el_insertstr "EditLine *e" "char *str"
  91 .Ft void
  92 .Fn el_deletestr "EditLine *e" "int count"
  93 .Ft void
  94 .Fn el_data_set "EditLine *e" "void *data"
  95 .Ft void *
  96 .Fn el_data_get "EditLine *e"
  97 .Ft History *
  98 .Fn history_init
  99 .Ft void
 100 .Fn history_end "History *h"
 101 .Ft const HistEvent *
 102 .Fn history "History *h" "int op" "..."
 103 .Sh DESCRIPTION
 104 The
 105 .Nm
 106 library provides generic line editing and history functions,
 107 similar to those found in
 108 .Xr sh 1 .
 109 .Pp
 110 These functions are available in the
 111 .Nm libedit
 112 library (which needs the
 113 .Nm libtermcap
 114 library).
 115 Programs should be linked with
 116 .Fl ledit ltermcap .
 117 .Sh LINE EDITING FUNCTIONS
 118 The line editing functions use a common data structure,
 119 .Fa EditLine ,
 120 which is created by
 121 .Fn el_init
 122 and freed by
 123 .Fn el_end .
 124 .Pp
 125 The following functions are available:
 126 .Bl -tag -width 4n
 127 .It Fn el_init
 128 Initialise the line editor, and return a data structure
 129 to be used by all other line editing functions.
 130 .Fa prog
 131 is the name of the invoking program, used when reading the
 132 .Xr editrc 5
 133 file to determine which settings to use.
 134 .Fa fin
 135 and
 136 .Fa fout
 137 are the input and output streams (respectively) to use.
 138 In this documentation, references to
 139 .Dq the tty
 140 are actually to this input/output stream combination.
 141 .It Fn el_end
 142 Clean up and finish with
 143 .Fa e ,
 144 assumed to have been created with
 145 .Fn el_init .
 146 .It Fn el_reset
 147 Reset the tty and the parser.
 148 This should be called after an error which may have upset the tty's
 149 state.
 150 .It Fn el_gets
 151 Read a line from the tty.
 152 .Fa count
 153 is modified to contain the number of characters read.
 154 Returns the line read if successful, or
 155 .Dv NULL
 156 if no characters were read or if an error occurred.
 157 .It Fn el_getc
 158 Read a character from the tty.
 159 .Fa ch
 160 is modified to contain the character read.
 161 Returns the number of characters read if successful, -1 otherwise.
 162 .It Fn el_push
 163 Pushes
 164 .Fa str
 165 back onto the input stream.
 166 This is used by the macro expansion mechanism.
 167 Refer to the description of
 168 .Ic bind
 169 .Fl s
 170 in
 171 .Xr editrc 5
 172 for more information.
 173 .It Fn el_parse
 174 Parses the
 175 .Fa argv
 176 array (which is
 177 .Fa argc
 178 elements in size)
 179 to execute builtin
 180 .Nm
 181 commands.
 182 If the command is prefixed with
 183 .Dq prog:
 184 then
 185 .Fn el_parse
 186 will only execute the command if
 187 .Dq prog
 188 matches the
 189 .Fa prog
 190 argument supplied to
 191 .Fn el_init .
 192 The return value is
 193 -1 if the command is unknown,
 194 0 if there was no error or
 195 .Dq prog
 196 didn't match, or
 197 1 if the command returned an error.
 198 Refer to
 199 .Xr editrc 5
 200 for more information.
 201 .Pp
 202 .Em NOTE :
 203 .Va argv[0]
 204 may be modified by
 205 .Fn el_parse .
 206 The colon between
 207 .Dq prog
 208 and the command,
 209 .Ar command ,
 210 will be replaced with a NUL
 211 .Pq Dq \e0 .
 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_TERMINAL , Fa "const char *type"
 229 Define terminal type of the tty to be
 230 .Fa type ,
 231 or to
 232 .Ev TERM
 233 if
 234 .Fa type
 235 is
 236 .Dv NULL .
 237 .It Dv EL_EDITOR , Fa "const char *mode"
 238 Set editing mode to
 239 .Fa mode ,
 240 which must be one of
 241 .Dq emacs
 242 or
 243 .Dq vi .
 244 .It Dv EL_SIGNAL , Fa "int flag"
 245 If
 246 .Fa flag
 247 is non-zero,
 248 .Nm
 249 will install its own signal handler for the following signals when
 250 reading command input:
 251 .Dv SIGCONT ,
 252 .Dv SIGHUP ,
 253 .Dv SIGINT ,
 254 .Dv SIGQUIT ,
 255 .Dv SIGSTOP ,
 256 .Dv SIGTERM ,
 257 .Dv SIGTSTP ,
 258 and
 259 .Dv SIGWINCH .
 260 Otherwise, the current signal handlers will be used.
 261 .It Dv EL_BIND , Xo
 262 .Fa "const char *" ,
 263 .Fa "..." ,
 264 .Dv NULL
 265 .Xc
 266 Perform the
 267 .Ic bind
 268 builtin command.
 269 Refer to
 270 .Xr editrc 5
 271 for more information.
 272 .It Dv EL_ECHOTC , Xo
 273 .Fa "const char *" ,
 274 .Fa "..." ,
 275 .Dv NULL
 276 .Xc
 277 Perform the
 278 .Ic echotc
 279 builtin command.
 280 Refer to
 281 .Xr editrc 5
 282 for more information.
 283 .It Dv EL_SETTC , Xo
 284 .Fa "const char *" ,
 285 .Fa "..." ,
 286 .Dv NULL
 287 .Xc
 288 Perform the
 289 .Ic settc
 290 builtin command.
 291 Refer to
 292 .Xr editrc 5
 293 for more information.
 294 .It Dv EL_SETTY , Xo
 295 .Fa "const char *" ,
 296 .Fa "..." ,
 297 .Dv NULL
 298 .Xc
 299 Perform the
 300 .Ic setty
 301 builtin command.
 302 Refer to
 303 .Xr editrc 5
 304 for more information.
 305 .It Dv EL_TELLTC , Xo
 306 .Fa "const char *" ,
 307 .Fa "..." ,
 308 .Dv NULL
 309 .Xc
 310 Perform the
 311 .Ic telltc
 312 builtin command.
 313 Refer to
 314 .Xr editrc 5
 315 for more information.
 316 .It Dv EL_ADDFN , Xo
 317 .Fa "const char *name" ,
 318 .Fa "const char *help" ,
 319 .Fa "unsigned char (*func)(EditLine *e, int ch)
 320 .Xc
 321 Add a user defined function,
 322 .Fn func ,
 323 referred to as
 324 .Fa name
 325 which is invoked when a key which is bound to
 326 .Fa name
 327 is entered.
 328 .Fa help
 329 is a description of
 330 .Fa name .
 331 At invocation time,
 332 .Fa ch
 333 is the key which caused the invocation.
 334 The return value of
 335 .Fn func
 336 should be one of:
 337 .Bl -tag -width "CC_REDISPLAY"
 338 .It Dv CC_NORM
 339 Add a normal character.
 340 .It Dv CC_NEWLINE
 341 End of line was entered.
 342 .It Dv CC_EOF
 343 EOF was entered.
 344 .It Dv CC_ARGHACK
 345 Expecting further command input as arguments, do nothing visually.
 346 .It Dv CC_REFRESH
 347 Refresh display.
 348 .It Dv CC_CURSOR
 349 Cursor moved, so update and perform
 350 .Dv CC_REFRESH .
 351 .It Dv CC_REDISPLAY
 352 Redisplay entire input line.
 353 This is useful if a key binding outputs extra information.
 354 .It Dv CC_ERROR
 355 An error occurred.
 356 Beep, and flush tty.
 357 .It Dv CC_FATAL
 358 Fatal error, reset tty to known state.
 359 .El
 360 .It Dv EL_HIST , Xo
 361 .Fa "History *(*func)(History *, int op, ...)" ,
 362 .Fa "const char *ptr"
 363 .Xc
 364 Defines which history function to use, which is usually
 365 .Fn history .
 366 .Fa ptr
 367 should be the value returned by
 368 .Fn history_init .
 369 .El
 370 .It Fn el_source
 371 Initialise
 372 .Nm
 373 by reading the contents of
 374 .Fa file .
 375 .Fn el_parse
 376 is called for each line in
 377 .Fa file .
 378 If
 379 .Fa file
 380 is
 381 .Dv NULL ,
 382 try
 383 .Pa $HOME/.editrc .
 384 Refer to
 385 .Xr editrc 5
 386 for details on the format of
 387 .Fa file .
 388 .It Fn el_resize
 389 Must be called if the terminal size changes.
 390 If
 391 .Dv EL_SIGNAL
 392 has been set with
 393 .Fn el_set ,
 394 then this is done automatically.
 395 Otherwise, it's the responsibility of the application to call
 396 .Fn el_resize
 397 on the appropriate occasions.
 398 .It Fn el_line
 399 Return the editing information for the current line in a
 400 .Fa LineInfo
 401 structure, which is defined as follows:
 402 .Bd -literal
 403 typedef struct lineinfo {
 404     const char *buffer;    /* address of buffer */
 405     const char *cursor;    /* address of cursor */
 406     const char *lastchar;  /* address of last character */
 407 } LineInfo;
 408 .Ed
 409 .It Fn el_insertstr
 410 Insert
 411 .Fa str
 412 into the line at the cursor.
 413 Returns -1 if
 414 .Fa str
 415 is empty or won't fit, and 0 otherwise.
 416 .It Fn el_deletestr
 417 Delete
 418 .Fa num
 419 characters before the cursor.
 420 .It Fn el_data_set
 421 Set the user data to
 422 .Fa data .
 423 .It Fn el_data_get
 424 Get the user data.
 425 .El
 426 .Sh HISTORY LIST FUNCTIONS
 427 The history functions use a common data structure,
 428 .Fa History ,
 429 which is created by
 430 .Fn history_init
 431 and freed by
 432 .Fn history_end .
 433 .Pp
 434 The following functions are available:
 435 .Bl -tag -width 4n
 436 .It Fn history_init
 437 Initialise the history list, and return a data structure
 438 to be used by all other history list functions.
 439 .It Fn history_end
 440 Clean up and finish with
 441 .Fa h ,
 442 assumed to have been created with
 443 .Fn history_init .
 444 .It Fn history
 445 Perform operation
 446 .Fa op
 447 on the history list, with optional arguments as needed by the
 448 operation.
 449 The following values for
 450 .Fa op
 451 are supported, along with the required argument list:
 452 .Bl -tag -width 4n
 453 .It Dv H_EVENT , Fa "int size"
 454 Set size of history to
 455 .Fa size
 456 elements.
 457 .It Dv H_END
 458 Cleans up and finishes with
 459 .Fa h ,
 460 assumed to be created with
 461 .Fn history_init .
 462 .It Dv H_CLEAR
 463 Clear the history.
 464 .It Dv H_FUNC , Xo
 465 .Fa "void *ptr" ,
 466 .Fa "history_gfun_t first" ,
 467 .Fa "history_gfun_t next" ,
 468 .Fa "history_gfun_t last" ,
 469 .Fa "history_gfun_t prev" ,
 470 .Fa "history_gfun_t curr" ,
 471 .Fa "history_vfun_t clear" ,
 472 .Fa "history_efun_t enter" ,
 473 .Fa "history_efun_t add"
 474 .Xc
 475 Define functions to perform various history operations.
 476 .Fa ptr
 477 is the argument given to a function when it's invoked.
 478 .It Dv H_FIRST
 479 Return the first element in the history.
 480 .It Dv H_LAST
 481 Return the last element in the history.
 482 .It Dv H_PREV
 483 Return the previous element in the history.
 484 .It Dv H_NEXT
 485 Return the next element in the history.
 486 .It Dv H_CURR
 487 Return the current element in the history.
 488 .It Dv H_ADD , Fa "const char *str"
 489 Append
 490 .Fa str
 491 to the current element of the history, or create an element with
 492 .Dv H_ENTER
 493 if there isn't one.
 494 .It Dv H_ENTER , Fa "const char *str"
 495 Add
 496 .Fa str
 497 as a new element to the history, and, if necessary,
 498 removing the oldest entry to keep the list to the created size.
 499 .It Dv H_PREV_STR , Fa "const char *str"
 500 Return the closest previous event that starts with
 501 .Fa str .
 502 .It Dv H_NEXT_STR , Fa "const char *str"
 503 Return the closest next event that starts with
 504 .Fa str .
 505 .It Dv H_PREV_EVENT , Fa "int e"
 506 Return the previous event numbered
 507 .Fa e .
 508 .It Dv H_NEXT_EVENT , Fa "int e"
 509 Return the next event numbered
 510 .Fa e .
 511 .It Dv H_LOAD , Fa "const char *file"
 512 Load the history list stored in
 513 .Fa file .
 514 .It Dv H_SAVE , Fa "const char *file"
 515 Save the history list to
 516 .Fa file .
 517 .El
 518 .El
 519 .\"XXX.Sh EXAMPLES
 520 .\"XXX: provide some examples
 521 .Sh SEE ALSO
 522 .Xr sh 1 ,
 523 .Xr signal 3 ,
 524 .Xr termcap 3 ,
 525 .Xr editrc 5
 526 .Sh HISTORY
 527 The
 528 .Nm
 529 library first appeared in
 530 .Bx 4.4 .
 531 .Sh AUTHORS
 532 .An -nosplit
 533 The
 534 .Nm
 535 library was written by
 536 .An Christos Zoulas ,
 537 and this manual was written by
 538 .An Luke Mewburn .
 539 .Sh BUGS
 540 This documentation is probably incomplete.
 541 .Pp
 542 .Fn el_parse
 543 should not modify the supplied
 544 .Va argv[0] .
 545 .Pp
 546 The tokenization functions are not publicly defined in
 547 .Li <histedit.h> .