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 $
37 .\" $DragonFly: src/lib/libedit/editline.3,v 1.2 2003/06/17 04:26:49 dillon Exp $
62 .Nd line editor and history functions
68 .Fn el_init "const char *prog" "FILE *fin" "FILE *fout"
70 .Fn el_end "EditLine *e"
72 .Fn el_reset "EditLine *e"
74 .Fn el_gets "EditLine *e" "int *count"
76 .Fn el_getc "EditLine *e" "char *ch"
78 .Fn el_push "EditLine *e" "const char *str"
80 .Fn el_parse "EditLine *e" "int argc" "char *argv[]"
82 .Fn el_set "EditLine *e" "int op" "..."
84 .Fn el_source "EditLine *e" "const char *file"
86 .Fn el_resize "EditLine *e"
88 .Fn el_line "EditLine *e"
90 .Fn el_insertstr "EditLine *e" "char *str"
92 .Fn el_deletestr "EditLine *e" "int count"
94 .Fn el_data_set "EditLine *e" "void *data"
96 .Fn el_data_get "EditLine *e"
100 .Fn history_end "History *h"
101 .Ft const HistEvent *
102 .Fn history "History *h" "int op" "..."
106 library provides generic line editing and history functions,
107 similar to those found in
110 These functions are available in the
112 library (which needs the
115 Programs should be linked with
117 .Sh LINE EDITING FUNCTIONS
118 The line editing functions use a common data structure,
125 The following functions are available:
128 Initialise the line editor, and return a data structure
129 to be used by all other line editing functions.
131 is the name of the invoking program, used when reading the
133 file to determine which settings to use.
137 are the input and output streams (respectively) to use.
138 In this documentation, references to
140 are actually to this input/output stream combination.
142 Clean up and finish with
144 assumed to have been created with
147 Reset the tty and the parser.
148 This should be called after an error which may have upset the tty's
151 Read a line from the tty.
153 is modified to contain the number of characters read.
154 Returns the line read if successful, or
156 if no characters were read or if an error occurred.
158 Read a character from the tty.
160 is modified to contain the character read.
161 Returns the number of characters read if successful, -1 otherwise.
165 back onto the input stream.
166 This is used by the macro expansion mechanism.
167 Refer to the description of
172 for more information.
182 If the command is prefixed with
186 will only execute the command if
193 -1 if the command is unknown,
194 0 if there was no error or
197 1 if the command returned an error.
200 for more information.
210 will be replaced with a NUL
217 determines which parameter to set, and each operation has its
220 The following values for
222 are supported, along with the required argument list:
224 .It Dv EL_PROMPT , Fa "char *(*f)(EditLine *)"
225 Define prompt printing function as
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
237 .It Dv EL_EDITOR , Fa "const char *mode"
244 .It Dv EL_SIGNAL , Fa "int flag"
249 will install its own signal handler for the following signals when
250 reading command input:
260 Otherwise, the current signal handlers will be used.
271 for more information.
272 .It Dv EL_ECHOTC , Xo
282 for more information.
293 for more information.
304 for more information.
305 .It Dv EL_TELLTC , Xo
315 for more information.
317 .Fa "const char *name" ,
318 .Fa "const char *help" ,
319 .Fa "unsigned char (*func)(EditLine *e, int ch)
321 Add a user defined function,
325 which is invoked when a key which is bound to
333 is the key which caused the invocation.
337 .Bl -tag -width "CC_REDISPLAY"
339 Add a normal character.
341 End of line was entered.
345 Expecting further command input as arguments, do nothing visually.
349 Cursor moved, so update and perform
352 Redisplay entire input line.
353 This is useful if a key binding outputs extra information.
358 Fatal error, reset tty to known state.
361 .Fa "History *(*func)(History *, int op, ...)" ,
362 .Fa "const char *ptr"
364 Defines which history function to use, which is usually
367 should be the value returned by
373 by reading the contents of
376 is called for each line in
386 for details on the format of
389 Must be called if the terminal size changes.
394 then this is done automatically.
395 Otherwise, it's the responsibility of the application to call
397 on the appropriate occasions.
399 Return the editing information for the current line in a
401 structure, which is defined as follows:
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 */
412 into the line at the cursor.
415 is empty or won't fit, and 0 otherwise.
419 characters before the cursor.
426 .Sh HISTORY LIST FUNCTIONS
427 The history functions use a common data structure,
434 The following functions are available:
437 Initialise the history list, and return a data structure
438 to be used by all other history list functions.
440 Clean up and finish with
442 assumed to have been created with
447 on the history list, with optional arguments as needed by the
449 The following values for
451 are supported, along with the required argument list:
453 .It Dv H_EVENT , Fa "int size"
454 Set size of history to
458 Cleans up and finishes with
460 assumed to be created with
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"
475 Define functions to perform various history operations.
477 is the argument given to a function when it's invoked.
479 Return the first element in the history.
481 Return the last element in the history.
483 Return the previous element in the history.
485 Return the next element in the history.
487 Return the current element in the history.
488 .It Dv H_ADD , Fa "const char *str"
491 to the current element of the history, or create an element with
494 .It Dv H_ENTER , Fa "const char *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
502 .It Dv H_NEXT_STR , Fa "const char *str"
503 Return the closest next event that starts with
505 .It Dv H_PREV_EVENT , Fa "int e"
506 Return the previous event numbered
508 .It Dv H_NEXT_EVENT , Fa "int e"
509 Return the next event numbered
511 .It Dv H_LOAD , Fa "const char *file"
512 Load the history list stored in
514 .It Dv H_SAVE , Fa "const char *file"
515 Save the history list to
520 .\"XXX: provide some examples
529 library first appeared in
535 library was written by
536 .An Christos Zoulas ,
537 and this manual was written by
540 This documentation is probably incomplete.
543 should not modify the supplied
546 The tokenization functions are not publicly defined in