contrib/libedit/editrc.5

   1 .\"     $NetBSD: editrc.5,v 1.33 2017/06/27 01:22:58 kre 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 May 22, 2016
  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 .Pp
  46 .Dl [prog:]command [arg ...]
  47 .Pp
  48 .Ar command
  49 is one of the
  50 .Xr editline 3
  51 builtin commands.
  52 Refer to
  53 .Sx BUILTIN COMMANDS
  54 for more information.
  55 .Pp
  56 .Ar prog
  57 is the program name string that a program defines when it calls
  58 .Xr el_init 3
  59 to set up
  60 .Xr editline 3 ,
  61 which is usually
  62 .Va argv[0] .
  63 .Ar command
  64 will be executed for any program which matches
  65 .Ar prog .
  66 .Pp
  67 .Ar prog
  68 may also be a
  69 .Xr regex 3
  70 style
  71 regular expression, in which case
  72 .Ar command
  73 will be executed for any program that matches the regular expression.
  74 .Pp
  75 If
  76 .Ar prog
  77 is absent,
  78 .Ar command
  79 is executed for all programs.
  80 .Sh BUILTIN COMMANDS
  81 The
  82 .Nm editline
  83 library has some builtin commands, which affect the way
  84 that the line editing and history functions operate.
  85 These are based on similar named builtins present in the
  86 .Xr tcsh 1
  87 shell.
  88 .Pp
  89 The following builtin commands are available:
  90 .Bl -tag -width 4n
  91 .It Ic bind Oo Fl aeklrsv Oc Op Ar key Op Ar command
  92 Without options and arguments, list all bound keys and macros, and
  93 the editor command or input string to which each one is bound.
  94 If only
  95 .Ar key
  96 is supplied, show the binding for that key or macro.
  97 If
  98 .Ar key command
  99 is supplied, bind the editor
 100 .Ar command
 101 to that key or macro.
 102 .Pp
 103 The options are as follows:
 104 .Bl -tag -width 4n
 105 .It Fl a
 106 List or change key bindings in the
 107 .Xr vi 1
 108 mode alternate (command mode) key map.
 109 .It Fl e
 110 Bind all keys to the standard GNU Emacs-like bindings.
 111 .It Fl k
 112 .Ar key
 113 is interpreted as a symbolic arrow key name, which may be one of
 114 .Sq up ,
 115 .Sq down ,
 116 .Sq left
 117 or
 118 .Sq right .
 119 .It Fl l
 120 List all editor commands and a short description of each.
 121 .It Fl r
 122 Remove the binding of the key or macro
 123 .Ar key .
 124 .It Fl s
 125 Define a keyboard macro rather than a key binding or command macro:
 126 .Ar command
 127 is taken as a literal string and appended to the input queue whenever
 128 .Ar key
 129 is typed.
 130 Bound keys and macros in
 131 .Ar command
 132 are themselves reinterpreted, and this continues for ten levels of
 133 interpretation.
 134 .It Fl v
 135 Bind all keys to the standard
 136 .Xr vi 1 Ns -like
 137 bindings.
 138 .El
 139 .Pp
 140 The
 141 .Xr editline 7
 142 manual documents all editor commands and contains more information
 143 about macros and the input queue.
 144 .Pp
 145 .Ar key
 146 and
 147 .Ar command
 148 can contain control characters of the form
 149 .Sm off
 150 .Sq No ^ Ar character
 151 .Sm on
 152 .Po
 153 e.g.\&
 154 .Sq ^A
 155 .Pc ,
 156 and the following backslashed escape sequences:
 157 .Pp
 158 .Bl -tag -compact -offset indent -width 4n
 159 .It Ic \ea
 160 Bell
 161 .It Ic \eb
 162 Backspace
 163 .It Ic \ee
 164 Escape
 165 .It Ic \ef
 166 Formfeed
 167 .It Ic \en
 168 Newline
 169 .It Ic \er
 170 Carriage return
 171 .It Ic \et
 172 Horizontal tab
 173 .It Ic \ev
 174 Vertical tab
 175 .Sm off
 176 .It Sy \e Ar nnn
 177 .Sm on
 178 The ASCII character corresponding to the octal number
 179 .Ar nnn .
 180 .El
 181 .Pp
 182 .Sq \e
 183 nullifies the special meaning of the following character,
 184 if it has any, notably
 185 .Sq \e
 186 and
 187 .Sq ^ .
 188 .It Ic echotc Oo Fl sv Oc Ar arg Ar ...
 189 Exercise terminal capabilities given in
 190 .Ar arg ... .
 191 If
 192 .Ar arg
 193 is
 194 .Sq baud ,
 195 .Sq cols ,
 196 .Sq lines ,
 197 .Sq rows ,
 198 .Sq meta ,
 199 or
 200 .Sq tabs ,
 201 the value of that capability is printed, with
 202 .Dq yes
 203 or
 204 .Dq no
 205 indicating that the terminal does or does not have that capability.
 206 .Pp
 207 .Fl s
 208 returns an empty string for non-existent capabilities, rather than
 209 causing an error.
 210 .Fl v
 211 causes messages to be verbose.
 212 .It Ic edit Op Li on | Li off
 213 Enable or disable the
 214 .Nm editline
 215 functionality in a program.
 216 .It Ic history Ar list | Ar size Dv n | Ar unique Dv n
 217 The
 218 .Ar list
 219 command lists all entries in the history.
 220 The
 221 .Ar size
 222 command sets the history size to
 223 .Dv n
 224 entries.
 225 The
 226 .Ar unique
 227 command controls if history should keep duplicate entries.
 228 If
 229 .Dv n
 230 is non zero, only keep unique history entries.
 231 If
 232 .Dv n
 233 is zero, then keep all entries (the default).
 234 .It Ic settc Ar cap Ar val
 235 Set the terminal capability
 236 .Ar cap
 237 to
 238 .Ar val ,
 239 as defined in
 240 .Xr termcap 5 .
 241 No sanity checking is done.
 242 .It Ic setty Oo Fl a Oc Oo Fl d Oc Oo Fl q Oc Oo Fl x Oc Oo Ar +mode Oc \
 243 Oo Ar -mode Oc Oo Ar mode Oc Oo Ar char=c Oc
 244 Control which tty modes that
 245 .Nm
 246 won't allow the user to change.
 247 .Fl d ,
 248 .Fl q
 249 or
 250 .Fl x
 251 tells
 252 .Ic setty
 253 to act on the
 254 .Sq edit ,
 255 .Sq quote
 256 or
 257 .Sq execute
 258 set of tty modes respectively; defaulting to
 259 .Fl x .
 260 .Pp
 261 Without other arguments,
 262 .Ic setty
 263 lists the modes in the chosen set which are fixed on
 264 .Po
 265 .Sq +mode
 266 .Pc
 267 or off
 268 .Po
 269 .Sq -mode
 270 .Pc .
 271 .Fl a
 272 lists all tty modes in the chosen set regardless of the setting.
 273 With
 274 .Ar +mode ,
 275 .Ar -mode
 276 or
 277 .Ar mode ,
 278 fixes
 279 .Ar mode
 280 on or off or removes control of
 281 .Ar mode
 282 in the chosen set.
 283 .Pp
 284 .Ic Setty
 285 can also be used to set tty characters to particular values using
 286 .Ar char=value .
 287 If
 288 .Ar value
 289 is empty
 290 then the character is set to
 291 .Dv _POSIX_VDISABLE .
 292 .It Ic telltc
 293 List the values of all the terminal capabilities (see
 294 .Xr termcap 5 ) .
 295 .El
 296 .Sh ENVIRONMENT
 297 .Bl -tag -width "~/.editrcXXX"
 298 .It Ev EDITRC
 299 Names the default configuration file for the
 300 .Xr editline 3
 301 library.
 302 .El
 303 .Sh FILES
 304 .Bl -tag -width "~/.editrcXXX"
 305 .It Pa ~/.editrc
 306 Last resort, if no other file is specified,
 307 user configuration file for the
 308 .Xr editline 3
 309 library.
 310 .El
 311 .Sh SEE ALSO
 312 .Xr editline 3 ,
 313 .Xr regex 3 ,
 314 .Xr termcap 5 ,
 315 .Xr editline 7
 316 .Sh AUTHORS
 317 .An -nosplit
 318 The
 319 .Nm editline
 320 library was written by
 321 .An Christos Zoulas ,
 322 and this manual was written by
 323 .An Luke Mewburn ,
 324 with some sections inspired by
 325 .Xr tcsh 1 .