contrib/nvi/docs/internals/input

   1 #       @(#)input       5.5 (Berkeley) 7/2/94
   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 7: Characters in executable buffers are remapped.
  69 8: Characters in executable buffers are not quoted.
  70
  71 Individual test cases follow.  Note, in the test cases, control characters
  72 are not literal and will have to be replaced to make the test cases work.
  73
  74 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  75 1: For buffers that are cut in "line mode", or buffers that are not cut
  76    in line mode but which contain portions of more than a single line, a
  77    trailing <newline> character appears in the input for each line in the
  78    buffer when it is executed.  For buffers not cut in line mode and which
  79    contain portions of only a single line, no additional characters
  80    appear in the input.
  81
  82 ===   test file   ===
  83 3Gw
  84 w
  85 line 1 foo bar baz
  86 line 2 foo bar baz
  87 line 3 foo bar baz
  88 === end test file ===
  89
  90    If the first line is loaded into 'a' and executed:
  91
  92 1G"ayy@a
  93
  94    The cursor ends up on the '2', a result of pushing "3Gw^J" onto
  95    the stack.
  96
  97    If the first two lines are loaded into 'a' and executed:
  98
  99 1G2"ayy@a
 100
 101    The cursor ends up on the 'f' in "foo" in the fifth line of the
 102    file, a result of pushing "3Gw^Jw^J" onto the stack.
 103
 104    If the first line is loaded into 'a', but not using line mode,
 105    and executed:
 106
 107 1G"ay$@a
 108
 109    The cursor ends up on the '1', a result of pushing "3Gw" onto
 110    the stack
 111
 112    If the first two lines are loaded into 'a', but not using line mode,
 113    and executed:
 114
 115 1G2"ay$@a
 116
 117    The cursor ends up on the 'f' in "foo" in the fifth line of the
 118    file, a result of pushing "3Gw^Jw^J" onto the stack.
 119
 120 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
 121 2: Executable buffers that execute other buffers don't load their
 122    contents until they execute them.
 123
 124 ===   test file   ===
 125 cwLOAD B^[
 126 line 1 foo bar baz
 127 line 2 foo bar baz
 128 line 3 foo bar baz
 129 @a@b
 130 "byy
 131 === end test file ===
 132
 133    The command is loaded into 'e', and then executed.  'e' executes
 134    'a', which loads 'b', then 'e' executes 'b'.
 135
 136 5G"eyy6G"ayy1G@e
 137
 138    The output should be:
 139
 140 ===   output file   ===
 141 cwLOAD B^[
 142 LOAD B 1 foo bar baz
 143 line 2 foo bar baz
 144 line 3 foo bar baz
 145 @a@b
 146 "byy
 147 === end output file ===
 148
 149 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
 150 3: Maps and executable buffers are copied when they are executed --
 151    they can be modified by the command but that does not change their
 152    actions.
 153
 154    Executable buffers:
 155
 156 ===   test file   ===
 157 line 1 foo bar baz
 158 line 2 foo bar baz
 159 line 3 foo bar baz
 160 @a@b
 161 "eyy
 162 cwEXECUTE B^[
 163 === end test file ===
 164
 165 4G"eyy5G"ayy6G"byy1G@eG"ep
 166
 167    The command is loaded into 'e', and then executed.  'e' executes
 168    'a', which loads 'e', then 'e' executes 'b' anyway.
 169
 170    The output should be:
 171
 172 ===   output file   ===
 173 line 1 foo bar baz
 174 EXECUTE B 2 foo bar baz
 175 line 3 foo bar baz
 176 @a@b
 177 "eyy
 178 cwEXECUTE B^[
 179 line 1 foo bar baz
 180 === end output file ===
 181
 182    Maps:
 183
 184 ===   test file   ===
 185 Cine 1 foo bar baz
 186 line 2 foo bar baz
 187 line 3 foo bar baz
 188 === end test file ===
 189
 190    Entering the command ':map = :map = rB^V^MrA^M1G==' shows that
 191    the first time the '=' is entered the '=' map is set and the
 192    character is changed to 'A', the second time the character is
 193    changed to 'B'.
 194
 195 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
 196 4: Historically, executable buffers are discarded if the editor
 197    switches between ex and vi modes.
 198
 199 ===   test file   ===
 200 line 1 foo bar baz
 201 line 2 foo bar baz
 202 line 3 foo bar baz
 203 cwCHANGE^[Q:set
 204 set|visual|1Gwww
 205 === end test file ===
 206
 207 vi testfile
 208 4G"ayy@a
 209
 210 ex testfile
 211 $p
 212 yank a
 213 @a
 214
 215    In vi, the command is loaded into 'a' and then executed.  The command
 216    subsequent to the 'Q' is (historically, silently) discarded.
 217
 218    In ex, the command is loaded into 'a' and then executed.  The command
 219    subsequent to the 'visual' is (historically, silently) discarded.  The
 220    first set command is output by ex, although refreshing the screen usually
 221    causes it not to be seen.
 222
 223 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
 224 5: Executable buffers inside of map commands are expanded normally.
 225    Maps inside of executable buffers are expanded normally.
 226
 227    Buffers inside of map commands:
 228
 229 ===   test file   ===
 230 line 1 foo bar baz
 231 line 2 foo bar baz
 232 line 3 foo bar baz
 233 cwREPLACE BY A^[
 234 === end test file ===
 235
 236 4G"ay$:map x @a
 237 1Gx
 238
 239    The output should be:
 240
 241 ===   output file   ===
 242 REPLACE BY A 1 foo bar baz
 243 line 2 foo bar baz
 244 line 3 foo bar baz
 245 cwREPLACE BY A^[
 246 === end output file ===
 247
 248    Maps commands inside of executable buffers:
 249
 250 ===   test file   ===
 251 line 1 foo bar baz
 252 line 2 foo bar baz
 253 line 3 foo bar baz
 254 X
 255 === end test file ===
 256
 257 :map X cwREPLACE BY XMAP^[
 258 4G"ay$1G@a
 259
 260    The output should be:
 261
 262 ===   output file   ===
 263 REPLACE BY XMAP 1 foo bar baz
 264 line 2 foo bar baz
 265 line 3 foo bar baz
 266 X
 267 === end output file ===
 268
 269    Here's a test that does both, repeatedly.
 270
 271 ===   test file   ===
 272 line 1 foo bar baz
 273 line 2 foo bar baz
 274 line 3 foo bar baz
 275 X
 276 Y
 277 cwREPLACED BY C^[
 278 blank line
 279 === end test file ===
 280
 281 :map x @a
 282 4G"ay$
 283 :map X @b
 284 5G"by$
 285 :map Y @c
 286 6G"cy$
 287 1Gx
 288
 289    The output should be:
 290
 291 ===   output file   ===
 292 REPLACED BY C 1 foo bar baz
 293 line 2 foo bar baz
 294 line 3 foo bar baz
 295 X
 296 Y
 297 cwREPLACED BY C^[
 298 blank line
 299 === end output file ===
 300
 301 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
 302 6: If an error is encountered while executing a mapped command or
 303    a buffer, the rest of the mapped command/buffer is discarded.  No
 304    user input characters are discarded.
 305
 306 ===   test file   ===
 307 line 1 foo bar baz
 308 line 2 foo bar baz
 309 line 3 foo bar baz
 310 :map = 10GcwREPLACMENT^V^[^[
 311 === end test file ===
 312
 313    The above mapping fails, however, if the 10G is changed to 1, 2,
 314    or 3G, it will succeed.
 315
 316 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
 317 7: Characters in executable buffers are remapped.
 318
 319 ===   test file   ===
 320 abcdefghijklmnnop
 321 ggg
 322 === end test file ===
 323
 324 :map g x
 325 2G"ay$1G@a
 326
 327    The output should be:
 328
 329 ===   output file   ===
 330 defghijklmnnop
 331 ggg
 332 === end output file ===
 333
 334 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
 335 8: Characters in executable buffers are not quoted.
 336
 337 ===   test file   ===
 338 iFOO^[
 339
 340 === end test file ===
 341
 342 1G"ay$2G@a
 343
 344    The output should be:
 345
 346 ===   output file   ===
 347 iFOO^[
 348 FOO
 349 === end output file ===
 350 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=