root/src/noitedit/editline.3

Revision bafab25395cb398ddf5eae42145f0d0bfc00ec22, 14.0 kB (checked in by Theo Schlossnagle <jesus@omniti.com>, 6 years ago)

import of libedit... prepare to hack

  • Property mode set to 100644
Line 
1 .\"     $NetBSD: editline.3,v 1.21 2001/04/02 18:29:49 wiz Exp $
2 .\"
3 .\" Copyright (c) 1997-1999 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 FOUNDATION OR CONTRIBUTORS
28 .\" BE 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 .Dd November 12, 1999
37 .Os
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
58 .Sh LIBRARY
59 .Lb libedit
60 .Sh SYNOPSIS
61 .Fd #include <histedit.h>
62 .Ft EditLine *
63 .Fn el_init "const char *prog" "FILE *fin" "FILE *fout" "FILE *ferr"
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
75 .Fn el_parse "EditLine *e" "int argc" "char *argv[]"
76 .Ft int
77 .Fn el_set "EditLine *e" "int op" "..."
78 .Ft int
79 .Fn el_get "EditLine *e" "int op" "void *result"
80 .Ft int
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
87 .Fn el_insertstr "EditLine *e" "const char *str"
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"
94 .Ft int
95 .Fn history "History *h" "HistEvent *ev" "int op" "..."
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.
127 .Fa fin ,
128 .Fa fout
129 and
130 .Fa ferr
131 are the input, output, and error streams (respectively) to use.
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.
155 Returns the number of characters read if successful, -1 otherwise.
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
177 .Dq prog:
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 .
186 The return value is
187 -1 if the command is unknown,
188 0 if there was no error or
189 .Dq prog
190 didn't match, or
191 1 if the command returned an error.
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.
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.
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.
256 Refer to
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.
267 Refer to
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.
278 Refer to
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.
289 Refer to
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.
300 Refer to
301 .Xr editrc 5
302 for more information.
303 .It Dv EL_ADDFN , Xo
304 .Fa "const char *name" ,
305 .Fa "const char *help" ,
306 .Fa "unsigned char (*func)(EditLine *e, int ch)
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:
324 .Bl -tag -width "CC_REDISPLAY"
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.
335 .It Dv CC_REFRESH_BEEP
336 Refresh display, and beep.
337 .It Dv CC_CURSOR
338 Cursor moved, so update and perform
339 .Dv CC_REFRESH.
340 .It Dv CC_REDISPLAY
341 Redisplay entire input line.
342 This is useful if a key binding outputs extra information.
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 .
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
365 .Nm "" .
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.
371 .El
372 .It Fn el_get
373 Get
374 .Nm
375 parameters.
376 .Fa op
377 determines which parameter to retrieve into
378 .Fa result .
379 .Pp
380 The following values for
381 .Fa op
382 are supported, along with actual type of
383 .Fa result :
384 .Bl -tag -width 4n
385 .It Dv EL_PROMPT , Fa "char *(*f)(EditLine *)"
386 Return a pointer to the function that displays the prompt.
387 .It Dv EL_RPROMPT , Fa "char *(*f)(EditLine *)"
388 Return a pointer to the function that displays the rightside prompt.
389 .It Dv EL_EDITOR , Fa "const char *"
390 Return the name of the editor, which will be one of
391 .Dq emacs
392 or
393 .Dq vi .
394 .It Dv EL_SIGNAL , Fa "int *"
395 Return non-zero if
396 .Nm
397 has installed private signal handlers (see
398 .Fn el_get
399 above).
400 .It Dv EL_EDITMODE, Fa "int *"
401 Return non-zero if editing is enabled.
402 .El
403 .It Fn el_source
404 Initialise
405 .Nm
406 by reading the contents of
407 .Fa file .
408 .Fn el_parse
409 is called for each line in
410 .Fa file .
411 If
412 .Fa file
413 is
414 .Dv NULL ,
415 try
416 .Pa $PWD/.editrc
417 then
418 .Pa $HOME/.editrc .
419 Refer to
420 .Xr editrc 5
421 for details on the format of
422 .Fa file .
423 .It Fn el_resize
424 Must be called if the terminal size changes.
425 If
426 .Dv EL_SIGNAL
427 has been set with
428 .Fn el_set ,
429 then this is done automatically.
430 Otherwise, it's the responsibility of the application to call
431 .Fn el_resize
432 on the appropriate occasions.
433 .It Fn el_line
434 Return the editing information for the current line in a
435 .Fa LineInfo
436 structure, which is defined as follows:
437 .Bd -literal
438 typedef struct lineinfo {
439     const char *buffer;    /* address of buffer */
440     const char *cursor;    /* address of cursor */
441     const char *lastchar;  /* address of last character */
442 } LineInfo;
443 .Ed
444 .It Fn el_insertstr
445 Insert
446 .Fa str
447 into the line at the cursor.
448 Returns -1 if
449 .Fa str
450 is empty or won't fit, and 0 otherwise.
451 .It Fn el_deletestr
452 Delete
453 .Fa num
454 characters before the cursor.
455 .El
456 .Sh HISTORY LIST FUNCTIONS
457 The history functions use a common data structure,
458 .Fa History ,
459 which is created by
460 .Fn history_init
461 and freed by
462 .Fn history_end .
463 .Pp
464 The following functions are available:
465 .Bl -tag -width 4n
466 .It Fn history_init
467 Initialise the history list, and return a data structure
468 to be used by all other history list functions.
469 .It Fn history_end
470 Clean up and finish with
471 .Fa h ,
472 assumed to have been created with
473 .Fn history_init .
474 .It Fn history
475 Perform operation
476 .Fa op
477 on the history list, with optional arguments as needed by the
478 operation.
479 .Fa ev
480 is changed accordingly to operation.
481 The following values for
482 .Fa op
483 are supported, along with the required argument list:
484 .Bl -tag -width 4n
485 .It Dv H_SETSIZE , Fa "int size"
486 Set size of history to
487 .Fa size
488 elements.
489 .It Dv H_GETSIZE
490 Get number of events currently in history.
491 .It Dv H_END
492 Cleans up and finishes with
493 .Fa h ,
494 assumed to be created with
495 .Fn history_init .
496 .It Dv H_CLEAR
497 Clear the history.
498 .It Dv H_FUNC , Xo
499 .Fa "void *ptr" ,
500 .Fa "history_gfun_t first" ,
501 .Fa "history_gfun_t next" ,
502 .Fa "history_gfun_t last" ,
503 .Fa "history_gfun_t prev" ,
504 .Fa "history_gfun_t curr" ,
505 .Fa "history_sfun_t set" ,
506 .Fa "history_vfun_t clear" ,
507 .Fa "history_efun_t enter" ,
508 .Fa "history_efun_t add"
509 .Xc
510 Define functions to perform various history operations.
511 .Fa ptr
512 is the argument given to a function when it's invoked.
513 .It Dv H_FIRST
514 Return the first element in the history.
515 .It Dv H_LAST
516 Return the last element in the history.
517 .It Dv H_PREV
518 Return the previous element in the history.
519 .It Dv H_NEXT
520 Return the next element in the history.
521 .It Dv H_CURR
522 Return the current element in the history.
523 .It Dv H_SET
524 Set the cursor to point to the requested element.
525 .It Dv H_ADD , Fa "const char *str"
526 Append
527 .Fa str
528 to the current element of the history, or create an element with
529 .It Dv H_APPEND , Fa "const char *str"
530 Append
531 .Fa str
532 to the last new element of the history.
533 .It Dv H_ENTER , Fa "const char *str"
534 Add
535 .Fa str
536 as a new element to the history, and, if necessary,
537 removing the oldest entry to keep the list to the created size.
538 .It Dv H_PREV_STR , Fa "const char *str"
539 Return the closest previous event that starts with
540 .Fa str .
541 .It Dv H_NEXT_STR , Fa "const char *str"
542 Return the closest next event that starts with
543 .Fa str .
544 .It Dv H_PREV_EVENT , Fa "int e"
545 Return the previous event numbered
546 .Fa e .
547 .It Dv H_NEXT_EVENT , Fa "int e"
548 Return the next event numbered
549 .Fa e .
550 .It Dv H_LOAD , Fa "const char *file"
551 Load the history list stored in
552 .Fa file .
553 .It Dv H_SAVE , Fa "const char *file"
554 Save the history list to
555 .Fa file .
556 .El
557 .Pp
558 .Fn history
559 returns 0 if the operation
560 .Fa op
561 succeeds. Otherwise, -1 is returned and
562 .Fa ev
563 is updated to contain more details about the error.
564 .El
565 .\"XXX.Sh EXAMPLES
566 .\"XXX: provide some examples
567 .Sh SEE ALSO
568 .Xr editrc 5 ,
569 .Xr sh 1 ,
570 .Xr signal 3 ,
571 .Xr termcap 3
572 .Sh HISTORY
573 The
574 .Nm
575 library first appeared in
576 .Bx 4.4 .
577 .Dv CC_REDISPLAY
578 appeared in
579 .Nx 1.3 .
580 .Dv CC_REFRESH_BEEP ,
581 .Dv EL_EDITMODE
582 and the readline emulation appeared in
583 .Nx 1.4 .
584 .Dv EL_RPROMPT
585 appeared in
586 .Nx 1.5 .
587 .Sh AUTHORS
588 The
589 .Nm
590 library was written by Christos Zoulas.
591 Luke Mewburn wrote this manual and implemented
592 .Dv CC_REDISPLAY ,
593 .Dv CC_REFRESH_BEEP ,
594 .Dv EL_EDITMODE ,
595 and
596 .Dv EL_RPROMPT .
597 Jaromir Dolecek implemented the readline emulation.
598 .Sh BUGS
599 The tokenization functions are not publically defined in
600 .Fd <histedit.h>.
601 .Pp
602 At this time, it is the responsibility of the caller to
603 check the result of the
604 .Dv EL_EDITMODE
605 operation of
606 .Fn el_get
607 (after an
608 .Fn el_source
609 or
610 .Fn el_parse )
611 to determine if
612 .Nm
613 should be used for further input.
614 I.e.,
615 .Dv EL_EDITMODE
616 is purely an indication of the result of the most recent
617 .Xr editrc 5
618 .Ic edit
619 command.
Note: See TracBrowser for help on using the browser.