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