home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Spezial / SPEZIAL2_97.zip / SPEZIAL2_97.iso / ANWEND / EDITOR / NVI179B / NVI179B.ZIP / docs / internals / input < prev    next >
Text File  |  1994-07-01  |  9KB  |  351 lines
  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.