1 .\" $NetBSD: editline.3,v 1.4 1997/01/14 04:17:23 lukem Exp $
3 .\" Copyright (c) 1997 The NetBSD Foundation, Inc.
4 .\" All rights reserved.
6 .\" This file was contributed to The NetBSD Foundation by Luke Mewburn.
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
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.
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.
36 .\" $FreeBSD: src/lib/libedit/editline.3,v 1.8.2.7 2001/12/17 10:08:30 ru Exp $
61 .Nd line editor and history functions
67 .Fn el_init "const char *prog" "FILE *fin" "FILE *fout"
69 .Fn el_end "EditLine *e"
71 .Fn el_reset "EditLine *e"
73 .Fn el_gets "EditLine *e" "int *count"
75 .Fn el_getc "EditLine *e" "char *ch"
77 .Fn el_push "EditLine *e" "const char *str"
79 .Fn el_parse "EditLine *e" "int argc" "char *argv[]"
81 .Fn el_set "EditLine *e" "int op" "..."
83 .Fn el_source "EditLine *e" "const char *file"
85 .Fn el_resize "EditLine *e"
87 .Fn el_line "EditLine *e"
89 .Fn el_insertstr "EditLine *e" "char *str"
91 .Fn el_deletestr "EditLine *e" "int count"
93 .Fn el_data_set "EditLine *e" "void *data"
95 .Fn el_data_get "EditLine *e"
99 .Fn history_end "History *h"
100 .Ft const HistEvent *
101 .Fn history "History *h" "int op" "..."
105 library provides generic line editing and history functions,
106 similar to those found in
109 These functions are available in the
111 library (which needs the
114 Programs should be linked with
116 .Sh LINE EDITING FUNCTIONS
117 The line editing functions use a common data structure,
124 The following functions are available:
127 Initialise the line editor, and return a data structure
128 to be used by all other line editing functions.
130 is the name of the invoking program, used when reading the
132 file to determine which settings to use.
136 are the input and output streams (respectively) to use.
137 In this documentation, references to
139 are actually to this input/output stream combination.
141 Clean up and finish with
143 assumed to have been created with
146 Reset the tty and the parser.
147 This should be called after an error which may have upset the tty's
150 Read a line from the tty.
152 is modified to contain the number of characters read.
153 Returns the line read if successful, or
155 if no characters were read or if an error occurred.
157 Read a character from the tty.
159 is modified to contain the character read.
160 Returns the number of characters read if successful, -1 otherwise.
164 back onto the input stream.
165 This is used by the macro expansion mechanism.
166 Refer to the description of
171 for more information.
181 If the command is prefixed with
185 will only execute the command if
192 -1 if the command is unknown,
193 0 if there was no error or
196 1 if the command returned an error.
199 for more information.
209 will be replaced with a NUL
216 determines which parameter to set, and each operation has its
219 The following values for
221 are supported, along with the required argument list:
223 .It Dv EL_PROMPT , Fa "char *(*f)(EditLine *)"
224 Define prompt printing function as
226 which is to return a string that contains the prompt.
227 .It Dv EL_TERMINAL , Fa "const char *type"
228 Define terminal type of the tty to be
236 .It Dv EL_EDITOR , Fa "const char *mode"
243 .It Dv EL_SIGNAL , Fa "int flag"
248 will install its own signal handler for the following signals when
249 reading command input:
259 Otherwise, the current signal handlers will be used.
270 for more information.
271 .It Dv EL_ECHOTC , Xo
281 for more information.
292 for more information.
303 for more information.
304 .It Dv EL_TELLTC , Xo
314 for more information.
316 .Fa "const char *name" ,
317 .Fa "const char *help" ,
318 .Fa "unsigned char (*func)(EditLine *e, int ch)
320 Add a user defined function,
324 which is invoked when a key which is bound to
332 is the key which caused the invocation.
336 .Bl -tag -width "CC_REDISPLAY"
338 Add a normal character.
340 End of line was entered.
344 Expecting further command input as arguments, do nothing visually.
348 Cursor moved, so update and perform
351 Redisplay entire input line.
352 This is useful if a key binding outputs extra information.
357 Fatal error, reset tty to known state.
360 .Fa "History *(*func)(History *, int op, ...)" ,
361 .Fa "const char *ptr"
363 Defines which history function to use, which is usually
366 should be the value returned by
372 by reading the contents of
375 is called for each line in
385 for details on the format of
388 Must be called if the terminal size changes.
393 then this is done automatically.
394 Otherwise, it's the responsibility of the application to call
396 on the appropriate occasions.
398 Return the editing information for the current line in a
400 structure, which is defined as follows:
402 typedef struct lineinfo {
403 const char *buffer; /* address of buffer */
404 const char *cursor; /* address of cursor */
405 const char *lastchar; /* address of last character */
411 into the line at the cursor.
414 is empty or won't fit, and 0 otherwise.
418 characters before the cursor.
425 .Sh HISTORY LIST FUNCTIONS
426 The history functions use a common data structure,
433 The following functions are available:
436 Initialise the history list, and return a data structure
437 to be used by all other history list functions.
439 Clean up and finish with
441 assumed to have been created with
446 on the history list, with optional arguments as needed by the
448 The following values for
450 are supported, along with the required argument list:
452 .It Dv H_EVENT , Fa "int size"
453 Set size of history to
457 Cleans up and finishes with
459 assumed to be created with
465 .Fa "history_gfun_t first" ,
466 .Fa "history_gfun_t next" ,
467 .Fa "history_gfun_t last" ,
468 .Fa "history_gfun_t prev" ,
469 .Fa "history_gfun_t curr" ,
470 .Fa "history_vfun_t clear" ,
471 .Fa "history_efun_t enter" ,
472 .Fa "history_efun_t add"
474 Define functions to perform various history operations.
476 is the argument given to a function when it's invoked.
478 Return the first element in the history.
480 Return the last element in the history.
482 Return the previous element in the history.
484 Return the next element in the history.
486 Return the current element in the history.
487 .It Dv H_ADD , Fa "const char *str"
490 to the current element of the history, or create an element with
493 .It Dv H_ENTER , Fa "const char *str"
496 as a new element to the history, and, if necessary,
497 removing the oldest entry to keep the list to the created size.
498 .It Dv H_PREV_STR , Fa "const char *str"
499 Return the closest previous event that starts with
501 .It Dv H_NEXT_STR , Fa "const char *str"
502 Return the closest next event that starts with
504 .It Dv H_PREV_EVENT , Fa "int e"
505 Return the previous event numbered
507 .It Dv H_NEXT_EVENT , Fa "int e"
508 Return the next event numbered
510 .It Dv H_LOAD , Fa "const char *file"
511 Load the history list stored in
513 .It Dv H_SAVE , Fa "const char *file"
514 Save the history list to
519 .\"XXX: provide some examples
528 library first appeared in
534 library was written by
535 .An Christos Zoulas ,
536 and this manual was written by
539 This documentation is probably incomplete.
542 should not modify the supplied
545 The tokenization functions are not publicly defined in