1  .\"	$NetBSD: editrc.5,v 1.24 2009/04/11 22:17:52 wiz 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 Op Ar command 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 or
198  .Sq tabs ,
199  the value of that capability is printed, with
200  .Dq yes
201  or
202  .Dq no
203  indicating that the terminal does or does not have that capability.
204  .Pp
205  .Fl s
206  returns an empty string for non-existent capabilities, rather than
207  causing an error.
208  .Fl v
209  causes messages to be verbose.
210  .It Ic edit Op Li on | Li off
211  Enable or disable the
212  .Nm editline
213  functionality in a program.
214  .It Ic history Ar list | Ar size Dv n | Ar unique Dv n
215  The
216  .Ar list
217  command lists all entries in the history.
218  The
219  .Ar size
220  command sets the history size to
221  .Dv n
222  entries.
223  The
224  .Ar unique
225  command controls if history should keep duplicate entries.
226  If
227  .Dv n
228  is non zero, only keep unique history entries.
229  If
230  .Dv n
231  is zero, then keep all entries (the default).
232  .It Ic telltc
233  List the values of all the terminal capabilities (see
234  .Xr termcap 5 ) .
235  .It Ic settc Ar cap Ar val
236  Set the terminal capability
237  .Ar cap
238  to
239  .Ar val ,
240  as defined in
241  .Xr termcap 5 .
242  No sanity checking is done.
243  .It Ic setty Oo Fl a Oc Oo Fl d Oc Oo Fl q Oc Oo Fl x Oc Oo Ar +mode Oc \
244  Oo Ar -mode Oc Oo Ar mode Oc Oo Ar char=c Oc
245  Control which tty modes that
246  .Nm
247  won't allow the user to change.
248  .Fl d ,
249  .Fl q
250  or
251  .Fl x
252  tells
253  .Ic setty
254  to act on the
255  .Sq edit ,
256  .Sq quote
257  or
258  .Sq execute
259  set of tty modes respectively; defaulting to
260  .Fl x .
261  .Pp
262  Without other arguments,
263  .Ic setty
264  lists the modes in the chosen set which are fixed on
265  .Po
266  .Sq +mode
267  .Pc
268  or off
269  .Po
270  .Sq -mode
271  .Pc .
272  .Fl a
273  lists all tty modes in the chosen set regardless of the setting.
274  With
275  .Ar +mode ,
276  .Ar -mode
277  or
278  .Ar mode ,
279  fixes
280  .Ar mode
281  on or off or removes control of
282  .Ar mode
283  in the chosen set.
284  .Pp
285  .Ic Setty
286  can also be used to set tty characters to particular values using
287  .Ar char=value .
288  If
289  .Ar value
290  is empty
291  then the character is set to
292  .Dv _POSIX_VDISABLE .
293  .El
294  .Sh EDITOR COMMANDS
295  The following editor commands are available for use in key bindings:
296  .\" Section automatically generated with makelist
297  .Bl -tag -width 4n
298  .It Ic vi-paste-next
299  Vi paste previous deletion to the right of the cursor.
300  .It Ic vi-paste-prev
301  Vi paste previous deletion to the left of the cursor.
302  .It Ic vi-prev-space-word
303  Vi move to the previous space delimited word.
304  .It Ic vi-prev-word
305  Vi move to the previous word.
306  .It Ic vi-next-space-word
307  Vi move to the next space delimited word.
308  .It Ic vi-next-word
309  Vi move to the next word.
310  .It Ic vi-change-case
311  Vi change case of character under the cursor and advance one character.
312  .It Ic vi-change-meta
313  Vi change prefix command.
314  .It Ic vi-insert-at-bol
315  Vi enter insert mode at the beginning of line.
316  .It Ic vi-replace-char
317  Vi replace character under the cursor with the next character typed.
318  .It Ic vi-replace-mode
319  Vi enter replace mode.
320  .It Ic vi-substitute-char
321  Vi replace character under the cursor and enter insert mode.
322  .It Ic vi-substitute-line
323  Vi substitute entire line.
324  .It Ic vi-change-to-eol
325  Vi change to end of line.
326  .It Ic vi-insert
327  Vi enter insert mode.
328  .It Ic vi-add
329  Vi enter insert mode after the cursor.
330  .It Ic vi-add-at-eol
331  Vi enter insert mode at end of line.
332  .It Ic vi-delete-meta
333  Vi delete prefix command.
334  .It Ic vi-end-word
335  Vi move to the end of the current space delimited word.
336  .It Ic vi-to-end-word
337  Vi move to the end of the current word.
338  .It Ic vi-undo
339  Vi undo last change.
340  .It Ic vi-command-mode
341  Vi enter command mode (use alternative key bindings).
342  .It Ic vi-zero
343  Vi move to the beginning of line.
344  .It Ic vi-delete-prev-char
345  Vi move to previous character (backspace).
346  .It Ic vi-list-or-eof
347  Vi list choices for completion or indicate end of file if empty line.
348  .It Ic vi-kill-line-prev
349  Vi cut from beginning of line to cursor.
350  .It Ic vi-search-prev
351  Vi search history previous.
352  .It Ic vi-search-next
353  Vi search history next.
354  .It Ic vi-repeat-search-next
355  Vi repeat current search in the same search direction.
356  .It Ic vi-repeat-search-prev
357  Vi repeat current search in the opposite search direction.
358  .It Ic vi-next-char
359  Vi move to the character specified next.
360  .It Ic vi-prev-char
361  Vi move to the character specified previous.
362  .It Ic vi-to-next-char
363  Vi move up to the character specified next.
364  .It Ic vi-to-prev-char
365  Vi move up to the character specified previous.
366  .It Ic vi-repeat-next-char
367  Vi repeat current character search in the same search direction.
368  .It Ic vi-repeat-prev-char
369  Vi repeat current character search in the opposite search direction.
370  .It Ic em-delete-or-list
371  Delete character under cursor or list completions if at end of line.
372  .It Ic em-delete-next-word
373  Cut from cursor to end of current word.
374  .It Ic em-yank
375  Paste cut buffer at cursor position.
376  .It Ic em-kill-line
377  Cut the entire line and save in cut buffer.
378  .It Ic em-kill-region
379  Cut area between mark and cursor and save in cut buffer.
380  .It Ic em-copy-region
381  Copy area between mark and cursor to cut buffer.
382  .It Ic em-gosmacs-transpose
383  Exchange the two characters before the cursor.
384  .It Ic em-next-word
385  Move next to end of current word.
386  .It Ic em-upper-case
387  Uppercase the characters from cursor to end of current word.
388  .It Ic em-capitol-case
389  Capitalize the characters from cursor to end of current word.
390  .It Ic em-lower-case
391  Lowercase the characters from cursor to end of current word.
392  .It Ic em-set-mark
393  Set the mark at cursor.
394  .It Ic em-exchange-mark
395  Exchange the cursor and mark.
396  .It Ic em-universal-argument
397  Universal argument (argument times 4).
398  .It Ic em-meta-next
399  Add 8th bit to next character typed.
400  .It Ic em-toggle-overwrite
401  Switch from insert to overwrite mode or vice versa.
402  .It Ic em-copy-prev-word
403  Copy current word to cursor.
404  .It Ic em-inc-search-next
405  Emacs incremental next search.
406  .It Ic em-inc-search-prev
407  Emacs incremental reverse search.
408  .It Ic ed-end-of-file
409  Indicate end of file.
410  .It Ic ed-insert
411  Add character to the line.
412  .It Ic ed-delete-prev-word
413  Delete from beginning of current word to cursor.
414  .It Ic ed-delete-next-char
415  Delete character under cursor.
416  .It Ic ed-kill-line
417  Cut to the end of line.
418  .It Ic ed-move-to-end
419  Move cursor to the end of line.
420  .It Ic ed-move-to-beg
421  Move cursor to the beginning of line.
422  .It Ic ed-transpose-chars
423  Exchange the character to the left of the cursor with the one under it.
424  .It Ic ed-next-char
425  Move to the right one character.
426  .It Ic ed-prev-word
427  Move to the beginning of the current word.
428  .It Ic ed-prev-char
429  Move to the left one character.
430  .It Ic ed-quoted-insert
431  Add the next character typed verbatim.
432  .It Ic ed-digit
433  Adds to argument or enters a digit.
434  .It Ic ed-argument-digit
435  Digit that starts argument.
436  .It Ic ed-unassigned
437  Indicates unbound character.
438  .It Ic ed-tty-sigint
439  Tty interrupt character.
440  .It Ic ed-tty-dsusp
441  Tty delayed suspend character.
442  .It Ic ed-tty-flush-output
443  Tty flush output characters.
444  .It Ic ed-tty-sigquit
445  Tty quit character.
446  .It Ic ed-tty-sigtstp
447  Tty suspend character.
448  .It Ic ed-tty-stop-output
449  Tty disallow output characters.
450  .It Ic ed-tty-start-output
451  Tty allow output characters.
452  .It Ic ed-newline
453  Execute command.
454  .It Ic ed-delete-prev-char
455  Delete the character to the left of the cursor.
456  .It Ic ed-clear-screen
457  Clear screen leaving current line at the top.
458  .It Ic ed-redisplay
459  Redisplay everything.
460  .It Ic ed-start-over
461  Erase current line and start from scratch.
462  .It Ic ed-sequence-lead-in
463  First character in a bound sequence.
464  .It Ic ed-prev-history
465  Move to the previous history line.
466  .It Ic ed-next-history
467  Move to the next history line.
468  .It Ic ed-search-prev-history
469  Search previous in history for a line matching the current.
470  .It Ic ed-search-next-history
471  Search next in history for a line matching the current.
472  .It Ic ed-prev-line
473  Move up one line.
474  .It Ic ed-next-line
475  Move down one line.
476  .It Ic ed-command
477  Editline extended command.
478  .El
479  .\" End of section automatically generated with makelist
480  .Sh SEE ALSO
481  .Xr editline 3 ,
482  .Xr regex 3 ,
483  .Xr termcap 5
484  .Sh AUTHORS
485  The
486  .Nm editline
487  library was written by Christos Zoulas,
488  and this manual was written by Luke Mewburn,
489  with some sections inspired by
490  .Xr tcsh 1 .