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 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= 351
Indexes created Fri Jun 05 00:26:10 UTC 2026