usr.bin/vi/docs/input

   1 #       @(#)input       5.4 (Berkeley) 8/26/93
   2
   3 MAPS, EXECUTABLE BUFFERS AND INPUT IN EX/VI:
   4
   5 The basic rule is that input in ex/vi is a stack.  Every time a key which
   6 gets expanded is encountered, it is expanded and the expansion is treated
   7 as if it were input from the user.  So, maps and executable buffers are
   8 simply pushed onto the stack from which keys are returned.  The exception
   9 is that if the "remap" option is turned off, only a single map expansion
  10 is done.  I intend to be fully backward compatible with this.
  11
  12 Historically, if the mode of the editor changed (ex to vi or vice versa),
  13 any queued input was silently discarded.  I don't see any reason to either
  14 support or not support this semantic.  I intend to retain the queued input,
  15 mostly because it's simpler than throwing it away.
  16
  17 Historically, neither the initial command on the command line (the + flag)
  18 or the +cmd associated with the ex and edit commands was subject to mapping.
  19 Also, while the +cmd appears to be subject to "@buffer" expansion, once
  20 expanded it doesn't appear to work correctly.  I don't see any reason to
  21 either support or not support these semantics, so, for consistency, I intend
  22 to pass both the initial command and the command associated with ex and edit
  23 commands through the standard mapping and @ buffer expansion.
  24
  25 One other difference between the historic ex/vi and nex/nvi is that nex
  26 displays the executed buffers as it executes them.  This means that if
  27 the file is:
  28
  29         set term=xterm
  30         set term=yterm
  31         set term=yterm
  32
  33 the user will see the following during a typical edit session:
  34
  35         nex testfile
  36         testfile: unmodified: line 3
  37         :1,$yank a
  38         :@a
  39         :set term=zterm
  40         :set term=yterm
  41         :set term=xterm
  42         :q!
  43
  44 This seems like a feature and unlikely to break anything, so I don't
  45 intend to match historic practice in this area.
  46
  47 The rest of this document is a set of conclusions as to how I believe
  48 the historic maps and @ buffers work.  The summary is as follows:
  49
  50 1: For buffers that are cut in "line mode", or buffers that are not cut
  51    in line mode but which contain portions of more than a single line, a
  52    trailing <newline> character appears in the input for each line in the
  53    buffer when it is executed.  For buffers not cut in line mode and which
  54    contain portions of only a single line, no additional characters
  55    appear in the input.
  56 2: Executable buffers that execute other buffers don't load their
  57    contents until they execute them.
  58 3: Maps and executable buffers are copied when they are executed --
  59    they can be modified by the command but that does not change their
  60    actions.
  61 4: Historically, executable buffers are discarded if the editor
  62    switches between ex and vi modes.
  63 5: Executable buffers inside of map commands are expanded normally.
  64    Maps inside of executable buffers are expanded normally.
  65 6: If an error is encountered while executing a mapped command or buffer,
  66    the rest of the mapped command/buffer is discarded.  No user input
  67    characters are discarded.
  68
  69 Individual test cases follow.  Note, in the test cases, control characters
  70 are not literal and will have to be replaced to make the test cases work.
  71
  72 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  73 1: For buffers that are cut in "line mode", or buffers that are not cut
  74    in line mode but which contain portions of more than a single line, a
  75    trailing <newline> character appears in the input for each line in the
  76    buffer when it is executed.  For buffers not cut in line mode and which
  77    contain portions of only a single line, no additional characters
  78    appear in the input.
  79
  80 ===   test file   ===
  81 3Gw
  82 w
  83 line 1 foo bar baz
  84 line 2 foo bar baz
  85 line 3 foo bar baz
  86 === end test file ===
  87
  88    If the first line is loaded into 'a' and executed:
  89
  90 1G"ayy@a
  91
  92    The cursor ends up on the '2', a result of pushing "3Gw^J" onto
  93    the stack.
  94
  95    If the first two lines are loaded into 'a' and executed:
  96
  97 1G2"ayy@a
  98
  99    The cursor ends up on the 'f' in "foo" in the fifth line of the
 100    file, a result of pushing "3Gw^Jw^J" onto the stack.
 101
 102    If the first line is loaded into 'a', but not using line mode,
 103    and executed:
 104
 105 1G"ay$@a
 106
 107    The cursor ends up on the '1', a result of pushing "3Gw" onto
 108    the stack
 109
 110    If the first two lines are loaded into 'a', but not using line mode,
 111    and executed:
 112
 113 1G2"ay$@a
 114
 115    The cursor ends up on the 'f' in "foo" in the fifth line of the
 116    file, a result of pushing "3Gw^Jw^J" onto the stack.
 117
 118 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
 119 2: Executable buffers that execute other buffers don't load their
 120    contents until they execute them.
 121
 122 ===   test file   ===
 123 cwLOAD B^[
 124 line 1 foo bar baz
 125 line 2 foo bar baz
 126 line 3 foo bar baz
 127 @a@b
 128 "byy
 129 === end test file ===
 130
 131    The command is loaded into 'e', and then executed.  'e' executes
 132    'a', which loads 'b', then 'e' executes 'b'.
 133
 134 5G"eyy6G"ayy1G@e
 135
 136    The output should be:
 137
 138 ===   output file   ===
 139 cwLOAD B^[
 140 LOAD B 1 foo bar baz
 141 line 2 foo bar baz
 142 line 3 foo bar baz
 143 @a@b
 144 "byy
 145 === end output file ===
 146
 147 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
 148 3: Maps and executable buffers are copied when they are executed --
 149    they can be modified by the command but that does not change their
 150    actions.
 151
 152    Executable buffers:
 153
 154 ===   test file   ===
 155 line 1 foo bar baz
 156 line 2 foo bar baz
 157 line 3 foo bar baz
 158 @a@b
 159 "eyy
 160 cwEXECUTE B^[
 161 === end test file ===
 162
 163 4G"eyy5G"ayy6G"byy1G@eG"ep
 164
 165    The command is loaded into 'e', and then executed.  'e' executes
 166    'a', which loads 'e', then 'e' executes 'b' anyway.
 167
 168    The output should be:
 169
 170 ===   output file   ===
 171 line 1 foo bar baz
 172 EXECUTE B 2 foo bar baz
 173 line 3 foo bar baz
 174 @a@b
 175 "eyy
 176 cwEXECUTE B^[
 177 line 1 foo bar baz
 178 === end output file ===
 179
 180    Maps:
 181
 182 ===   test file   ===
 183 Cine 1 foo bar baz
 184 line 2 foo bar baz
 185 line 3 foo bar baz
 186 === end test file ===
 187
 188    Entering the command ':map = :map = rB^V^MrA^M1G==' shows that
 189    the first time the '=' is entered the '=' map is set and the
 190    character is changed to 'A', the second time the character is
 191    changed to 'B'.
 192
 193 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
 194 4: Historically, executable buffers are discarded if the editor
 195    switches between ex and vi modes.
 196
 197 ===   test file   ===
 198 line 1 foo bar baz
 199 line 2 foo bar baz
 200 line 3 foo bar baz
 201 cwCHANGE^[Q:set
 202 set|visual|1Gwww
 203 === end test file ===
 204
 205 vi testfile
 206 4G"ayy@a
 207
 208 ex testfile
 209 $p
 210 yank a
 211 @a
 212
 213    In vi, the command is loaded into 'a' and then executed.  The command
 214    subsequent to the 'Q' is (historically, silently) discarded.
 215
 216    In ex, the command is loaded into 'a' and then executed.  The command
 217    subsequent to the 'visual' is (historically, silently) discarded.  The
 218    first set command is output by ex, although refreshing the screen usually
 219    causes it not to be seen.
 220
 221 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
 222 5: Executable buffers inside of map commands are expanded normally.
 223    Maps inside of executable buffers are expanded normally.
 224
 225    Buffers inside of map commands:
 226
 227 ===   test file   ===
 228 line 1 foo bar baz
 229 line 2 foo bar baz
 230 line 3 foo bar baz
 231 cwREPLACE BY A^[
 232 === end test file ===
 233
 234 4G"ay$:map x @a
 235 1Gx
 236
 237    The output should be:
 238
 239 ===   output file   ===
 240 REPLACE BY A 1 foo bar baz
 241 line 2 foo bar baz
 242 line 3 foo bar baz
 243 cwREPLACE BY A^[
 244 === end output file ===
 245
 246    Maps commands inside of executable buffers:
 247
 248 ===   test file   ===
 249 line 1 foo bar baz
 250 line 2 foo bar baz
 251 line 3 foo bar baz
 252 X
 253 === end test file ===
 254
 255 :map X cwREPLACE BY XMAP^[
 256 4G"ay$1G@a
 257
 258    The output should be:
 259
 260 ===   output file   ===
 261 REPLACE BY XMAP 1 foo bar baz
 262 line 2 foo bar baz
 263 line 3 foo bar baz
 264 X
 265 === end output file ===
 266
 267    Here's a test that does both, repeatedly.
 268
 269 ===   test file   ===
 270 line 1 foo bar baz
 271 line 2 foo bar baz
 272 line 3 foo bar baz
 273 X
 274 Y
 275 cwREPLACED BY C^[
 276 blank line
 277 === end test file ===
 278
 279 :map x @a
 280 4G"ay$
 281 :map X @b
 282 5G"by$
 283 :map Y @c
 284 6G"cy$
 285 1Gx
 286
 287    The output should be:
 288
 289 ===   output file   ===
 290 REPLACED BY C 1 foo bar baz
 291 line 2 foo bar baz
 292 line 3 foo bar baz
 293 X
 294 Y
 295 cwREPLACED BY C^[
 296 blank line
 297 === end output file ===
 298
 299 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
 300 6: If an error is encountered while executing a mapped command or
 301    a buffer, the rest of the mapped command/buffer is discarded.  No
 302    user input characters are discarded.
 303
 304 ===   test file   ===
 305 line 1 foo bar baz
 306 line 2 foo bar baz
 307 line 3 foo bar baz
 308 :map = 10GcwREPLACMENT^V^[^[
 309 === end test file ===
 310
 311    The above mapping fails, however, if the 10G is changed to 1, 2,
 312    or 3G, it will succeed.
 313
 314 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=