libedit: Update to version 2012-12-13
[dragonfly.git] / lib / libedit / libedit / editrc.5
1 .\"     $NetBSD: editrc.5,v 1.26 2012/06/02 14:19:20 njoly Exp $
2 .\"
3 .\" Copyright (c) 1997-2000 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 .\"
17 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
18 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
19 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
20 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
21 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
22 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
23 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
24 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
25 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
26 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
27 .\" POSSIBILITY OF SUCH DAMAGE.
28 .\"
29 .Dd October 18, 2003
30 .Dt EDITRC 5
31 .Os
32 .Sh NAME
33 .Nm editrc
34 .Nd configuration file for editline library
35 .Sh SYNOPSIS
36 .Nm
37 .Sh DESCRIPTION
38 The
39 .Nm
40 file defines various settings to be used by the
41 .Xr editline 3
42 library.
43 .Pp
44 The format of each line is:
45 .Dl [prog:]command [arg [...]]
46 .Pp
47 .Ar command
48 is one of the
49 .Xr editline 3
50 builtin commands.
51 Refer to
52 .Sx BUILTIN COMMANDS
53 for more information.
54 .Pp
55 .Ar prog
56 is the program name string that a program defines when it calls
57 .Xr el_init 3
58 to set up
59 .Xr editline 3 ,
60 which is usually
61 .Va argv[0] .
62 .Ar command
63 will be executed for any program which matches
64 .Ar prog .
65 .Pp
66 .Ar prog
67 may also be a
68 .Xr regex 3
69 style
70 regular expression, in which case
71 .Ar command
72 will be executed for any program that matches the regular expression.
73 .Pp
74 If
75 .Ar prog
76 is absent,
77 .Ar command
78 is executed for all programs.
79 .Sh BUILTIN COMMANDS
80 The
81 .Nm editline
82 library has some builtin commands, which affect the way
83 that the line editing and history functions operate.
84 These are based on similar named builtins present in the
85 .Xr tcsh 1
86 shell.
87 .Pp
88 The following builtin commands are available:
89 .Bl -tag -width 4n
90 .It Ic bind Oo Fl a Oc Oo Fl e Oc Oo Fl k Oc Oo Fl l Oc Oo Fl r Oc \
91 Oo Fl s Oc Oo Fl v Oc Oo Ar key Oo Ar command Oc Oc
92 Without options, list all bound keys, and the editor command to which
93 each is bound.
94 If
95 .Ar key
96 is supplied, show the bindings for
97 .Ar key .
98 If
99 .Ar key command
100 is supplied, bind
101 .Ar command
102 to
103 .Ar key .
104 Options include:
105 .Bl -tag -width 4n
106 .It Fl e
107 Bind all keys to the standard GNU Emacs-like bindings.
108 .It Fl v
109 Bind all keys to the standard
110 .Xr vi 1 Ns -like
111 bindings.
112 .It Fl a
113 List or change key bindings in the
114 .Xr vi 1
115 mode alternate (command mode) key map.
116 .It Fl k
117 .Ar key
118 is interpreted as a symbolic arrow key name, which may be one of
119 .Sq up ,
120 .Sq down ,
121 .Sq left
122 or
123 .Sq right .
124 .It Fl l
125 List all editor commands and a short description of each.
126 .It Fl r
127 Remove a key's binding.
128 .It Fl s
129 .Ar command
130 is taken as a literal string and treated as terminal input when
131 .Ar key
132 is typed.
133 Bound keys in
134 .Ar command
135 are themselves reinterpreted, and this continues for ten levels of
136 interpretation.
137 .El
138 .Pp
139 .Ar command
140 may be one of the commands documented in
141 .Sx "EDITOR COMMANDS"
142 below, or another key.
143 .Pp
144 .Ar key
145 and
146 .Ar command
147 can contain control characters of the form
148 .Sm off
149 .Sq No ^ Ar character
150 .Sm on
151 .Po
152 e.g.
153 .Sq ^A
154 .Pc ,
155 and the following backslashed escape sequences:
156 .Pp
157 .Bl -tag -compact -offset indent -width 4n
158 .It Ic \ea
159 Bell
160 .It Ic \eb
161 Backspace
162 .It Ic \ee
163 Escape
164 .It Ic \ef
165 Formfeed
166 .It Ic \en
167 Newline
168 .It Ic \er
169 Carriage return
170 .It Ic \et
171 Horizontal tab
172 .It Ic \ev
173 Vertical tab
174 .Sm off
175 .It Sy \e Ar nnn
176 .Sm on
177 The ASCII character corresponding to the octal number
178 .Ar nnn .
179 .El
180 .Pp
181 .Sq \e
182 nullifies the special meaning of the following character,
183 if it has any, notably
184 .Sq \e
185 and
186 .Sq ^ .
187 .It Ic echotc Oo Fl sv Oc Ar arg Ar ...
188 Exercise terminal capabilities given in
189 .Ar arg Ar ... .
190 If
191 .Ar arg
192 is
193 .Sq baud ,
194 .Sq cols ,
195 .Sq lines ,
196 .Sq rows ,
197 .Sq meta ,
198 or
199 .Sq tabs ,
200 the value of that capability is printed, with
201 .Dq yes
202 or
203 .Dq no
204 indicating that the terminal does or does not have that capability.
205 .Pp
206 .Fl s
207 returns an empty string for non-existent capabilities, rather than
208 causing an error.
209 .Fl v
210 causes messages to be verbose.
211 .It Ic edit Op Li on | Li off
212 Enable or disable the
213 .Nm editline
214 functionality in a program.
215 .It Ic history Ar list | Ar size Dv n | Ar unique Dv n
216 The
217 .Ar list
218 command lists all entries in the history.
219 The
220 .Ar size
221 command sets the history size to
222 .Dv n
223 entries.
224 The
225 .Ar unique
226 command controls if history should keep duplicate entries.
227 If
228 .Dv n
229 is non zero, only keep unique history entries.
230 If
231 .Dv n
232 is zero, then keep all entries (the default).
233 .It Ic telltc
234 List the values of all the terminal capabilities (see
235 .Xr termcap 5 ) .
236 .It Ic settc Ar cap Ar val
237 Set the terminal capability
238 .Ar cap
239 to
240 .Ar val ,
241 as defined in
242 .Xr termcap 5 .
243 No sanity checking is done.
244 .It Ic setty Oo Fl a Oc Oo Fl d Oc Oo Fl q Oc Oo Fl x Oc Oo Ar +mode Oc \
245 Oo Ar -mode Oc Oo Ar mode Oc Oo Ar char=c Oc
246 Control which tty modes that
247 .Nm
248 won't allow the user to change.
249 .Fl d ,
250 .Fl q
251 or
252 .Fl x
253 tells
254 .Ic setty
255 to act on the
256 .Sq edit ,
257 .Sq quote
258 or
259 .Sq execute
260 set of tty modes respectively; defaulting to
261 .Fl x .
262 .Pp
263 Without other arguments,
264 .Ic setty
265 lists the modes in the chosen set which are fixed on
266 .Po
267 .Sq +mode
268 .Pc
269 or off
270 .Po
271 .Sq -mode
272 .Pc .
273 .Fl a
274 lists all tty modes in the chosen set regardless of the setting.
275 With
276 .Ar +mode ,
277 .Ar -mode
278 or
279 .Ar mode ,
280 fixes
281 .Ar mode
282 on or off or removes control of
283 .Ar mode
284 in the chosen set.
285 .Pp
286 .Ic Setty
287 can also be used to set tty characters to particular values using
288 .Ar char=value .
289 If
290 .Ar value
291 is empty
292 then the character is set to
293 .Dv _POSIX_VDISABLE .
294 .El
295 .Sh EDITOR COMMANDS
296 The following editor commands are available for use in key bindings:
297 .\" Section automatically generated with makelist
298 .Bl -tag -width 4n
299 .It Ic vi-paste-next
300 Vi paste previous deletion to the right of the cursor.
301 .It Ic vi-paste-prev
302 Vi paste previous deletion to the left of the cursor.
303 .It Ic vi-prev-space-word
304 Vi move to the previous space delimited word.
305 .It Ic vi-prev-word
306 Vi move to the previous word.
307 .It Ic vi-next-space-word
308 Vi move to the next space delimited word.
309 .It Ic vi-next-word
310 Vi move to the next word.
311 .It Ic vi-change-case
312 Vi change case of character under the cursor and advance one character.
313 .It Ic vi-change-meta
314 Vi change prefix command.
315 .It Ic vi-insert-at-bol
316 Vi enter insert mode at the beginning of line.
317 .It Ic vi-replace-char
318 Vi replace character under the cursor with the next character typed.
319 .It Ic vi-replace-mode
320 Vi enter replace mode.
321 .It Ic vi-substitute-char
322 Vi replace character under the cursor and enter insert mode.
323 .It Ic vi-substitute-line
324 Vi substitute entire line.
325 .It Ic vi-change-to-eol
326 Vi change to end of line.
327 .It Ic vi-insert
328 Vi enter insert mode.
329 .It Ic vi-add
330 Vi enter insert mode after the cursor.
331 .It Ic vi-add-at-eol
332 Vi enter insert mode at end of line.
333 .It Ic vi-delete-meta
334 Vi delete prefix command.
335 .It Ic vi-end-word
336 Vi move to the end of the current space delimited word.
337 .It Ic vi-to-end-word
338 Vi move to the end of the current word.
339 .It Ic vi-undo
340 Vi undo last change.
341 .It Ic vi-command-mode
342 Vi enter command mode (use alternative key bindings).
343 .It Ic vi-zero
344 Vi move to the beginning of line.
345 .It Ic vi-delete-prev-char
346 Vi move to previous character (backspace).
347 .It Ic vi-list-or-eof
348 Vi list choices for completion or indicate end of file if empty line.
349 .It Ic vi-kill-line-prev
350 Vi cut from beginning of line to cursor.
351 .It Ic vi-search-prev
352 Vi search history previous.
353 .It Ic vi-search-next
354 Vi search history next.
355 .It Ic vi-repeat-search-next
356 Vi repeat current search in the same search direction.
357 .It Ic vi-repeat-search-prev
358 Vi repeat current search in the opposite search direction.
359 .It Ic vi-next-char
360 Vi move to the character specified next.
361 .It Ic vi-prev-char
362 Vi move to the character specified previous.
363 .It Ic vi-to-next-char
364 Vi move up to the character specified next.
365 .It Ic vi-to-prev-char
366 Vi move up to the character specified previous.
367 .It Ic vi-repeat-next-char
368 Vi repeat current character search in the same search direction.
369 .It Ic vi-repeat-prev-char
370 Vi repeat current character search in the opposite search direction.
371 .It Ic em-delete-or-list
372 Delete character under cursor or list completions if at end of line.
373 .It Ic em-delete-next-word
374 Cut from cursor to end of current word.
375 .It Ic em-yank
376 Paste cut buffer at cursor position.
377 .It Ic em-kill-line
378 Cut the entire line and save in cut buffer.
379 .It Ic em-kill-region
380 Cut area between mark and cursor and save in cut buffer.
381 .It Ic em-copy-region
382 Copy area between mark and cursor to cut buffer.
383 .It Ic em-gosmacs-transpose
384 Exchange the two characters before the cursor.
385 .It Ic em-next-word
386 Move next to end of current word.
387 .It Ic em-upper-case
388 Uppercase the characters from cursor to end of current word.
389 .It Ic em-capitol-case
390 Capitalize the characters from cursor to end of current word.
391 .It Ic em-lower-case
392 Lowercase the characters from cursor to end of current word.
393 .It Ic em-set-mark
394 Set the mark at cursor.
395 .It Ic em-exchange-mark
396 Exchange the cursor and mark.
397 .It Ic em-universal-argument
398 Universal argument (argument times 4).
399 .It Ic em-meta-next
400 Add 8th bit to next character typed.
401 .It Ic em-toggle-overwrite
402 Switch from insert to overwrite mode or vice versa.
403 .It Ic em-copy-prev-word
404 Copy current word to cursor.
405 .It Ic em-inc-search-next
406 Emacs incremental next search.
407 .It Ic em-inc-search-prev
408 Emacs incremental reverse search.
409 .It Ic ed-end-of-file
410 Indicate end of file.
411 .It Ic ed-insert
412 Add character to the line.
413 .It Ic ed-delete-prev-word
414 Delete from beginning of current word to cursor.
415 .It Ic ed-delete-next-char
416 Delete character under cursor.
417 .It Ic ed-kill-line
418 Cut to the end of line.
419 .It Ic ed-move-to-end
420 Move cursor to the end of line.
421 .It Ic ed-move-to-beg
422 Move cursor to the beginning of line.
423 .It Ic ed-transpose-chars
424 Exchange the character to the left of the cursor with the one under it.
425 .It Ic ed-next-char
426 Move to the right one character.
427 .It Ic ed-prev-word
428 Move to the beginning of the current word.
429 .It Ic ed-prev-char
430 Move to the left one character.
431 .It Ic ed-quoted-insert
432 Add the next character typed verbatim.
433 .It Ic ed-digit
434 Adds to argument or enters a digit.
435 .It Ic ed-argument-digit
436 Digit that starts argument.
437 .It Ic ed-unassigned
438 Indicates unbound character.
439 .It Ic ed-tty-sigint
440 Tty interrupt character.
441 .It Ic ed-tty-dsusp
442 Tty delayed suspend character.
443 .It Ic ed-tty-flush-output
444 Tty flush output characters.
445 .It Ic ed-tty-sigquit
446 Tty quit character.
447 .It Ic ed-tty-sigtstp
448 Tty suspend character.
449 .It Ic ed-tty-stop-output
450 Tty disallow output characters.
451 .It Ic ed-tty-start-output
452 Tty allow output characters.
453 .It Ic ed-newline
454 Execute command.
455 .It Ic ed-delete-prev-char
456 Delete the character to the left of the cursor.
457 .It Ic ed-clear-screen
458 Clear screen leaving current line at the top.
459 .It Ic ed-redisplay
460 Redisplay everything.
461 .It Ic ed-start-over
462 Erase current line and start from scratch.
463 .It Ic ed-sequence-lead-in
464 First character in a bound sequence.
465 .It Ic ed-prev-history
466 Move to the previous history line.
467 .It Ic ed-next-history
468 Move to the next history line.
469 .It Ic ed-search-prev-history
470 Search previous in history for a line matching the current.
471 .It Ic ed-search-next-history
472 Search next in history for a line matching the current.
473 .It Ic ed-prev-line
474 Move up one line.
475 .It Ic ed-next-line
476 Move down one line.
477 .It Ic ed-command
478 Editline extended command.
479 .El
480 .\" End of section automatically generated with makelist
481 .Sh SEE ALSO
482 .Xr editline 3 ,
483 .Xr regex 3 ,
484 .Xr termcap 5
485 .Sh AUTHORS
486 The
487 .Nm editline
488 library was written by Christos Zoulas,
489 and this manual was written by Luke Mewburn,
490 with some sections inspired by
491 .Xr tcsh 1 .