Annotation of src/lib/libedit/editline.3, Revision 1.38
1.38 ! wiz 1: .\" $NetBSD: editline.3,v 1.37 2003/09/26 17:44:51 christos Exp $
1.1 lukem 2: .\"
1.18 lukem 3: .\" Copyright (c) 1997-1999 The NetBSD Foundation, Inc.
1.1 lukem 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
1.17 simonb 27: .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
1.5 jtc 28: .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
1.1 lukem 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: .\"
1.38 ! wiz 36: .Dd September 26, 2003
1.16 garbled 37: .Os
1.1 lukem 38: .Dt EDITLINE 3
39: .Sh NAME
40: .Nm editline ,
41: .Nm el_init ,
42: .Nm el_end ,
43: .Nm el_reset ,
44: .Nm el_gets ,
45: .Nm el_getc ,
46: .Nm el_push ,
47: .Nm el_parse ,
48: .Nm el_set ,
49: .Nm el_source ,
50: .Nm el_resize ,
51: .Nm el_line ,
52: .Nm el_insertstr ,
53: .Nm el_deletestr ,
54: .Nm history_init ,
55: .Nm history_end ,
56: .Nm history
57: .Nd line editor and history functions
1.9 perry 58: .Sh LIBRARY
59: .Lb libedit
1.1 lukem 60: .Sh SYNOPSIS
1.33 wiz 61: .In histedit.h
1.1 lukem 62: .Ft EditLine *
1.10 christos 63: .Fn el_init "const char *prog" "FILE *fin" "FILE *fout" "FILE *ferr"
1.1 lukem 64: .Ft void
65: .Fn el_end "EditLine *e"
66: .Ft void
67: .Fn el_reset "EditLine *e"
68: .Ft const char *
69: .Fn el_gets "EditLine *e" "int *count"
70: .Ft int
71: .Fn el_getc "EditLine *e" "char *ch"
72: .Ft void
73: .Fn el_push "EditLine *e" "const char *str"
74: .Ft int
1.28 yamt 75: .Fn el_parse "EditLine *e" "int argc" "const char *argv[]"
1.1 lukem 76: .Ft int
77: .Fn el_set "EditLine *e" "int op" "..."
78: .Ft int
1.14 lukem 79: .Fn el_get "EditLine *e" "int op" "void *result"
80: .Ft int
1.1 lukem 81: .Fn el_source "EditLine *e" "const char *file"
82: .Ft void
83: .Fn el_resize "EditLine *e"
84: .Ft const LineInfo *
85: .Fn el_line "EditLine *e"
86: .Ft int
1.20 chopps 87: .Fn el_insertstr "EditLine *e" "const char *str"
1.1 lukem 88: .Ft void
89: .Fn el_deletestr "EditLine *e" "int count"
90: .Ft History *
91: .Fn history_init
92: .Ft void
93: .Fn history_end "History *h"
1.6 christos 94: .Ft int
1.15 lukem 95: .Fn history "History *h" "HistEvent *ev" "int op" "..."
1.1 lukem 96: .Sh DESCRIPTION
97: The
98: .Nm
99: library provides generic line editing and history functions,
100: similar to those found in
101: .Xr sh 1 .
102: .Pp
103: These functions are available in the
104: .Nm libedit
105: library (which needs the
106: .Nm libtermcap
107: library).
108: Programs should be linked with
109: .Fl ledit ltermcap .
110: .Sh LINE EDITING FUNCTIONS
111: The line editing functions use a common data structure,
112: .Fa EditLine ,
113: which is created by
114: .Fn el_init
115: and freed by
116: .Fn el_end .
117: .Pp
118: The following functions are available:
119: .Bl -tag -width 4n
120: .It Fn el_init
121: Initialise the line editor, and return a data structure
122: to be used by all other line editing functions.
123: .Fa prog
124: is the name of the invoking program, used when reading the
125: .Xr editrc 5
126: file to determine which settings to use.
1.10 christos 127: .Fa fin ,
128: .Fa fout
1.1 lukem 129: and
1.10 christos 130: .Fa ferr
131: are the input, output, and error streams (respectively) to use.
1.1 lukem 132: In this documentation, references to
133: .Dq the tty
134: are actually to this input/output stream combination.
135: .It Fn el_end
136: Clean up and finish with
137: .Fa e ,
138: assumed to have been created with
139: .Fn el_init .
140: .It Fn el_reset
141: Reset the tty and the parser.
142: This should be called after an error which may have upset the tty's
143: state.
144: .It Fn el_gets
145: Read a line from the tty.
146: .Fa count
147: is modified to contain the number of characters read.
148: Returns the line read if successful, or
149: .Dv NULL
150: if no characters were read or if an error occurred.
151: .It Fn el_getc
152: Read a character from the tty.
153: .Fa ch
154: is modified to contain the character read.
1.31 wiz 155: Returns the number of characters read if successful, \-1 otherwise.
1.1 lukem 156: .It Fn el_push
157: Pushes
158: .Fa str
159: back onto the input stream.
160: This is used by the macro expansion mechanism.
161: Refer to the description of
162: .Ic bind
163: .Fl s
164: in
165: .Xr editrc 5
166: for more information.
167: .It Fn el_parse
168: Parses the
169: .Fa argv
170: array (which is
171: .Fa argc
172: elements in size)
173: to execute builtin
174: .Nm
175: commands.
176: If the command is prefixed with
1.25 wiz 177: .Dq prog :
1.1 lukem 178: then
179: .Fn el_parse
180: will only execute the command if
181: .Dq prog
182: matches the
183: .Fa prog
184: argument supplied to
185: .Fn el_init .
1.2 lukem 186: The return value is
1.31 wiz 187: \-1 if the command is unknown,
1.2 lukem 188: 0 if there was no error or
1.1 lukem 189: .Dq prog
1.2 lukem 190: didn't match, or
191: 1 if the command returned an error.
1.1 lukem 192: Refer to
193: .Xr editrc 5
194: for more information.
195: .It Fn el_set
196: Set
197: .Nm
198: parameters.
199: .Fa op
200: determines which parameter to set, and each operation has its
201: own parameter list.
202: .Pp
203: The following values for
204: .Fa op
205: are supported, along with the required argument list:
206: .Bl -tag -width 4n
207: .It Dv EL_PROMPT , Fa "char *(*f)(EditLine *)"
208: Define prompt printing function as
209: .Fa f ,
210: which is to return a string that contains the prompt.
1.18 lukem 211: .It Dv EL_RPROMPT , Fa "char *(*f)(EditLine *)"
212: Define right side prompt printing function as
213: .Fa f ,
214: which is to return a string that contains the prompt.
1.1 lukem 215: .It Dv EL_TERMINAL , Fa "const char *type"
216: Define terminal type of the tty to be
217: .Fa type ,
218: or to
219: .Ev TERM
220: if
221: .Fa type
222: is
223: .Dv NULL .
224: .It Dv EL_EDITOR , Fa "const char *mode"
225: Set editing mode to
226: .Fa mode ,
227: which must be one of
228: .Dq emacs
229: or
230: .Dq vi .
231: .It Dv EL_SIGNAL , Fa "int flag"
232: If
233: .Fa flag
234: is non-zero,
235: .Nm
236: will install its own signal handler for the following signals when
237: reading command input:
238: .Dv SIGCONT ,
239: .Dv SIGHUP ,
240: .Dv SIGINT ,
241: .Dv SIGQUIT ,
242: .Dv SIGSTOP ,
243: .Dv SIGTERM ,
244: .Dv SIGTSTP ,
245: and
246: .Dv SIGWINCH .
247: Otherwise, the current signal handlers will be used.
248: .It Dv EL_BIND , Xo
249: .Fa "const char *" ,
250: .Fa "..." ,
251: .Dv NULL
252: .Xc
253: Perform the
254: .Ic bind
255: builtin command.
1.17 simonb 256: Refer to
1.1 lukem 257: .Xr editrc 5
258: for more information.
259: .It Dv EL_ECHOTC , Xo
260: .Fa "const char *" ,
261: .Fa "..." ,
262: .Dv NULL
263: .Xc
264: Perform the
265: .Ic echotc
266: builtin command.
1.17 simonb 267: Refer to
1.1 lukem 268: .Xr editrc 5
269: for more information.
270: .It Dv EL_SETTC , Xo
271: .Fa "const char *" ,
272: .Fa "..." ,
273: .Dv NULL
274: .Xc
275: Perform the
276: .Ic settc
277: builtin command.
1.17 simonb 278: Refer to
1.1 lukem 279: .Xr editrc 5
280: for more information.
281: .It Dv EL_SETTY , Xo
282: .Fa "const char *" ,
283: .Fa "..." ,
284: .Dv NULL
285: .Xc
286: Perform the
287: .Ic setty
288: builtin command.
1.17 simonb 289: Refer to
1.1 lukem 290: .Xr editrc 5
291: for more information.
292: .It Dv EL_TELLTC , Xo
293: .Fa "const char *" ,
294: .Fa "..." ,
295: .Dv NULL
296: .Xc
297: Perform the
298: .Ic telltc
299: builtin command.
1.17 simonb 300: Refer to
1.1 lukem 301: .Xr editrc 5
302: for more information.
303: .It Dv EL_ADDFN , Xo
304: .Fa "const char *name" ,
305: .Fa "const char *help" ,
1.27 wiz 306: .Fa "unsigned char (*func)(EditLine *e, int ch)"
1.1 lukem 307: .Xc
308: Add a user defined function,
309: .Fn func ,
310: referred to as
311: .Fa name
312: which is invoked when a key which is bound to
313: .Fa name
314: is entered.
315: .Fa help
316: is a description of
317: .Fa name .
318: At invocation time,
319: .Fa ch
320: is the key which caused the invocation.
321: The return value of
322: .Fn func
323: should be one of:
1.4 lukem 324: .Bl -tag -width "CC_REDISPLAY"
1.1 lukem 325: .It Dv CC_NORM
326: Add a normal character.
327: .It Dv CC_NEWLINE
328: End of line was entered.
329: .It Dv CC_EOF
330: EOF was entered.
331: .It Dv CC_ARGHACK
332: Expecting further command input as arguments, do nothing visually.
333: .It Dv CC_REFRESH
334: Refresh display.
1.12 lukem 335: .It Dv CC_REFRESH_BEEP
336: Refresh display, and beep.
1.1 lukem 337: .It Dv CC_CURSOR
1.4 lukem 338: Cursor moved, so update and perform
1.23 lukem 339: .Dv CC_REFRESH .
1.4 lukem 340: .It Dv CC_REDISPLAY
341: Redisplay entire input line.
342: This is useful if a key binding outputs extra information.
1.1 lukem 343: .It Dv CC_ERROR
344: An error occurred.
345: Beep, and flush tty.
346: .It Dv CC_FATAL
347: Fatal error, reset tty to known state.
348: .El
349: .It Dv EL_HIST , Xo
350: .Fa "History *(*func)(History *, int op, ...)" ,
351: .Fa "const char *ptr"
352: .Xc
353: Defines which history function to use, which is usually
354: .Fn history .
355: .Fa ptr
356: should be the value returned by
357: .Fn history_init .
1.14 lukem 358: .It Dv EL_EDITMODE , Fa "int flag"
359: If
360: .Fa flag
361: is non-zero,
362: editing is enabled (the default).
363: Note that this is only an indication, and does not
364: affect the operation of
1.32 wiz 365: .Nm .
1.14 lukem 366: At this time, it is the caller's responsibility to
367: check this
368: (using
369: .Fn el_get )
370: to determine if editing should be enabled or not.
1.22 christos 371: .It Dv EL_GETCFN , Fa "int (*f)(EditLine *, char *c)"
372: Define the character reading function as
373: .Fa f ,
374: which is to return the number of characters read and store them in
375: .Fa c .
376: This function is called internally by
377: .Fn el_gets
378: and
379: .Fn el_getc .
380: The builtin function can be set or restored with the special function
381: name ``EL_BUILTIN_GETCFN''.
1.24 christos 382: .It Dv EL_CLIENTDATA , Fa "void *data"
1.25 wiz 383: Register
1.24 christos 384: .Fa data
1.29 wiz 385: to be associated with this EditLine structure.
386: It can be retrieved with the corresponding
1.24 christos 387: .Fn el_get
388: call.
1.14 lukem 389: .El
390: .It Fn el_get
391: Get
392: .Nm
393: parameters.
394: .Fa op
395: determines which parameter to retrieve into
396: .Fa result .
1.35 jeremy 397: Returns 0 if successful, \-1 otherwise.
1.14 lukem 398: .Pp
399: The following values for
400: .Fa op
401: are supported, along with actual type of
402: .Fa result :
403: .Bl -tag -width 4n
404: .It Dv EL_PROMPT , Fa "char *(*f)(EditLine *)"
405: Return a pointer to the function that displays the prompt.
1.18 lukem 406: .It Dv EL_RPROMPT , Fa "char *(*f)(EditLine *)"
407: Return a pointer to the function that displays the rightside prompt.
1.14 lukem 408: .It Dv EL_EDITOR , Fa "const char *"
409: Return the name of the editor, which will be one of
410: .Dq emacs
411: or
412: .Dq vi .
413: .It Dv EL_SIGNAL , Fa "int *"
414: Return non-zero if
415: .Nm
416: has installed private signal handlers (see
417: .Fn el_get
418: above).
419: .It Dv EL_EDITMODE, Fa "int *"
420: Return non-zero if editing is enabled.
1.22 christos 421: .It Dv EL_GETCFN, Fa "int (**f)(EditLine *, char *)"
422: Return a pointer to the function that read characters, which is equal to
423: ``EL_BUILTIN_GETCFN'' in the case of the default builtin function.
1.24 christos 424: .It Dv EL_CLIENTDATA , Fa "void **data"
1.25 wiz 425: Retrieve
1.24 christos 426: .Fa data
427: previously registered with the corresponding
428: .Fn el_set
429: call.
1.37 christos 430: .It Dv EL_UNBUFFERED, Fa "int"
1.38 ! wiz 431: Sets or clears unbuffered mode.
! 432: In this mode,
1.37 christos 433: .Fn el_gets
434: will return immediately after processing a single character.
1.1 lukem 435: .El
436: .It Fn el_source
437: Initialise
438: .Nm
1.17 simonb 439: by reading the contents of
1.1 lukem 440: .Fa file .
441: .Fn el_parse
442: is called for each line in
443: .Fa file .
444: If
445: .Fa file
446: is
447: .Dv NULL ,
448: try
449: .Pa $PWD/.editrc
450: then
451: .Pa $HOME/.editrc .
452: Refer to
453: .Xr editrc 5
454: for details on the format of
455: .Fa file .
456: .It Fn el_resize
457: Must be called if the terminal size changes.
458: If
459: .Dv EL_SIGNAL
460: has been set with
461: .Fn el_set ,
462: then this is done automatically.
463: Otherwise, it's the responsibility of the application to call
464: .Fn el_resize
465: on the appropriate occasions.
466: .It Fn el_line
467: Return the editing information for the current line in a
468: .Fa LineInfo
469: structure, which is defined as follows:
470: .Bd -literal
471: typedef struct lineinfo {
472: const char *buffer; /* address of buffer */
473: const char *cursor; /* address of cursor */
474: const char *lastchar; /* address of last character */
475: } LineInfo;
476: .Ed
477: .It Fn el_insertstr
478: Insert
479: .Fa str
480: into the line at the cursor.
1.31 wiz 481: Returns \-1 if
1.1 lukem 482: .Fa str
483: is empty or won't fit, and 0 otherwise.
484: .It Fn el_deletestr
485: Delete
486: .Fa num
487: characters before the cursor.
488: .El
489: .Sh HISTORY LIST FUNCTIONS
490: The history functions use a common data structure,
491: .Fa History ,
492: which is created by
493: .Fn history_init
494: and freed by
495: .Fn history_end .
496: .Pp
497: The following functions are available:
498: .Bl -tag -width 4n
499: .It Fn history_init
500: Initialise the history list, and return a data structure
501: to be used by all other history list functions.
502: .It Fn history_end
503: Clean up and finish with
504: .Fa h ,
505: assumed to have been created with
506: .Fn history_init .
507: .It Fn history
508: Perform operation
509: .Fa op
510: on the history list, with optional arguments as needed by the
511: operation.
1.6 christos 512: .Fa ev
513: is changed accordingly to operation.
1.1 lukem 514: The following values for
515: .Fa op
516: are supported, along with the required argument list:
517: .Bl -tag -width 4n
1.10 christos 518: .It Dv H_SETSIZE , Fa "int size"
1.1 lukem 519: Set size of history to
520: .Fa size
521: elements.
1.6 christos 522: .It Dv H_GETSIZE
523: Get number of events currently in history.
1.1 lukem 524: .It Dv H_END
525: Cleans up and finishes with
526: .Fa h ,
527: assumed to be created with
528: .Fn history_init .
529: .It Dv H_CLEAR
530: Clear the history.
531: .It Dv H_FUNC , Xo
532: .Fa "void *ptr" ,
533: .Fa "history_gfun_t first" ,
534: .Fa "history_gfun_t next" ,
535: .Fa "history_gfun_t last" ,
536: .Fa "history_gfun_t prev" ,
537: .Fa "history_gfun_t curr" ,
1.10 christos 538: .Fa "history_sfun_t set" ,
1.1 lukem 539: .Fa "history_vfun_t clear" ,
540: .Fa "history_efun_t enter" ,
541: .Fa "history_efun_t add"
542: .Xc
543: Define functions to perform various history operations.
544: .Fa ptr
545: is the argument given to a function when it's invoked.
546: .It Dv H_FIRST
547: Return the first element in the history.
548: .It Dv H_LAST
549: Return the last element in the history.
550: .It Dv H_PREV
551: Return the previous element in the history.
552: .It Dv H_NEXT
553: Return the next element in the history.
554: .It Dv H_CURR
555: Return the current element in the history.
1.10 christos 556: .It Dv H_SET
557: Set the cursor to point to the requested element.
1.1 lukem 558: .It Dv H_ADD , Fa "const char *str"
559: Append
560: .Fa str
561: to the current element of the history, or create an element with
1.11 christos 562: .It Dv H_APPEND , Fa "const char *str"
563: Append
564: .Fa str
565: to the last new element of the history.
1.1 lukem 566: .It Dv H_ENTER , Fa "const char *str"
567: Add
568: .Fa str
1.17 simonb 569: as a new element to the history, and, if necessary,
1.1 lukem 570: removing the oldest entry to keep the list to the created size.
1.31 wiz 571: If
1.30 christos 572: .Dv H_SETUNIQUE
573: was has been called with a non-zero arguments, the element
574: will not be entered into the history if its contents match
575: the ones of the current history element.
576: If the element is entered
577: .Fn history
578: returns 1, if it is ignored as a duplicate returns 0.
579: Finally
580: .Fn history
1.31 wiz 581: returns \-1 if an error occurred.
1.1 lukem 582: .It Dv H_PREV_STR , Fa "const char *str"
583: Return the closest previous event that starts with
584: .Fa str .
585: .It Dv H_NEXT_STR , Fa "const char *str"
586: Return the closest next event that starts with
587: .Fa str .
588: .It Dv H_PREV_EVENT , Fa "int e"
589: Return the previous event numbered
590: .Fa e .
591: .It Dv H_NEXT_EVENT , Fa "int e"
592: Return the next event numbered
593: .Fa e .
594: .It Dv H_LOAD , Fa "const char *file"
595: Load the history list stored in
596: .Fa file .
597: .It Dv H_SAVE , Fa "const char *file"
598: Save the history list to
599: .Fa file .
1.30 christos 600: .It Dv H_SETUNIQUE , Fa "int unique"
1.31 wiz 601: Set if the adjacent identical event strings should not be entered into
1.30 christos 602: the history.
603: .It Dv H_GETUNIQUE
1.31 wiz 604: Retrieve the current setting if if adjacent elements should be entered into
1.30 christos 605: the history.
1.1 lukem 606: .El
1.7 lukem 607: .Pp
608: .Fn history
1.30 christos 609: returns >= 0 if the operation succeeds
1.7 lukem 610: .Fa op
1.29 wiz 611: succeeds.
1.31 wiz 612: Otherwise, \-1 is returned and
1.7 lukem 613: .Fa ev
614: is updated to contain more details about the error.
1.1 lukem 615: .El
616: .\"XXX.Sh EXAMPLES
617: .\"XXX: provide some examples
618: .Sh SEE ALSO
619: .Xr sh 1 ,
620: .Xr signal 3 ,
1.23 lukem 621: .Xr termcap 3 ,
622: .Xr editrc 5
1.1 lukem 623: .Sh HISTORY
624: The
625: .Nm
626: library first appeared in
1.3 lukem 627: .Bx 4.4 .
1.18 lukem 628: .Dv CC_REDISPLAY
629: appeared in
630: .Nx 1.3 .
631: .Dv CC_REFRESH_BEEP ,
632: .Dv EL_EDITMODE
633: and the readline emulation appeared in
634: .Nx 1.4 .
635: .Dv EL_RPROMPT
636: appeared in
637: .Nx 1.5 .
1.1 lukem 638: .Sh AUTHORS
639: The
640: .Nm
1.18 lukem 641: library was written by Christos Zoulas.
642: Luke Mewburn wrote this manual and implemented
643: .Dv CC_REDISPLAY ,
1.19 lukem 644: .Dv CC_REFRESH_BEEP ,
1.18 lukem 645: .Dv EL_EDITMODE ,
646: and
647: .Dv EL_RPROMPT .
648: Jaromir Dolecek implemented the readline emulation.
1.1 lukem 649: .Sh BUGS
1.25 wiz 650: The tokenization functions are not publicly defined in
1.34 wiz 651: .Aq Pa histedit.h .
1.14 lukem 652: .Pp
653: At this time, it is the responsibility of the caller to
654: check the result of the
655: .Dv EL_EDITMODE
656: operation of
657: .Fn el_get
658: (after an
659: .Fn el_source
660: or
661: .Fn el_parse )
662: to determine if
663: .Nm
664: should be used for further input.
665: I.e.,
666: .Dv EL_EDITMODE
667: is purely an indication of the result of the most recent
668: .Xr editrc 5
669: .Ic edit
670: command.
CVSweb <webmaster@jp.NetBSD.org>
![[BACK]](/icons/back.gif){kind=icon}
Return to editline.3 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [cvs.NetBSD.org] / src / lib / libedit