usr.bin/vi/docs/quoting

   1 #       @(#)quoting     5.4 (Berkeley) 8/20/93
   2
   3 QUOTING IN EX/VI:
   4
   5 There are two escape characters in historic ex/vi, ^V (or whatever
   6 character the user specified as their literal next character) and
   7 backslashes.  There are two different areas in ex/vi where escaping
   8 is interesting: the command and text input modes, and within the ex
   9 commands themselves.  In the examples below, ^V is used as the
  10 typical literal next character.
  11
  12 1: Escaping characters in ex and vi command and text input modes.
  13    The set of characters that users might want to escape are as
  14    follows:
  15
  16    vi text input mode (a, i, o, etc.):
  17
  18         carriage return (^M)
  19         escape          (^[)
  20         autoindent characters
  21                         (^D, 0, ^, ^T)
  22         erase, word erase, and line erase
  23                         (^H, ^W, ^U)
  24         newline         (^J)                    (not historic practice)
  25         suspend         (^Z)                    (not historic practice)
  26         repaint         (^L)                    (not historic practice)
  27
  28    vi command line (:colon commands):
  29
  30         carriage return (^M)
  31         escape          (^[)
  32         erase, word erase, and line erase
  33                         (^H, ^W, ^U)
  34         newline         (^J)                    (not historic practice)
  35         suspend         (^Z)                    (not historic practice)
  36         repaint         (^L)                    (not historic practice)
  37
  38    ex text input mode (a, i, o, etc.):
  39
  40         carriage return (^M)
  41         erase, word erase, and line erase
  42                         (^H, ^W, ^U)
  43         newline         (^J)                    (not historic practice)
  44
  45    ex command line:
  46
  47         carriage return (^M)
  48         erase, word erase, and line erase
  49                         (^H, ^W, ^U)
  50         newline         (^J)                    (not historic practice)
  51         suspend         (^Z)
  52
  53    I intend to follow historic practice for all of these cases, which
  54    was that ^V was the only way to escape any of these characters, and
  55    that whatever character followed the ^V was taken literally, i.e.
  56    ^V^V is a single ^V.
  57
  58    The historic ex/vi disallowed the insertion of various control
  59    characters (^D, ^T, whatever) during various different modes, or,
  60    permitted the insertion of only a single one, or lots of other random
  61    behaviors (you can use ^D to enter a command in ex).  I have
  62    regularized this behavior in nvi, there are no characters that cannot
  63    be entered or which have special meaning other than the ones listed
  64    above.
  65
  66    One comment regarding the autoindent characters.  In historic vi,
  67    if you entered "^V0^D" autoindent erasure was still triggered,
  68    although it wasn't if you entered "0^V^D".  In nvi, if you escape
  69    either character, autoindent erasure is not triggered.
  70
  71    This doesn't permit whitespace in command names, but that wasn't
  72    historic practice and doesn't seem worth doing.
  73
  74    Fun facts to know and tell:
  75            The historic vi implementation for the 'r' command requires
  76            *three* ^V's to replace a single character with ^V.
  77
  78 2: Ex commands:
  79
  80    Ex commands are delimited by '|' or newline characters.  Within
  81    the commands, whitespace characters delimit the arguments.
  82
  83    I intend to treat ^V, followed by any character, as that literal
  84    character.
  85
  86    This is historic behavior in vi, although there are special
  87    cases where it's impossible to escape a character, generally
  88    a whitespace character.
  89
  90 3: Escaping characters in file names in ex commands:
  91
  92         :cd [directory]                         (directory)
  93         :chdir [directory]                      (directory)
  94         :edit [+cmd] [file]                     (file)
  95         :ex [+cmd] [file]                       (file)
  96         :file [file]                            (file)
  97         :next [file ...]                        (file ...)
  98         :read [!cmd | file]                     (file)
  99         :source [file]                          (file)
 100         :write [!cmd | file]                    (file)
 101         :wq [file]                              (file)
 102         :xit [file]                             (file)
 103
 104    I intend to treat a backslash in a file name, followed by any
 105    character, as that literal character.
 106
 107    This is historic behavior in vi.
 108
 109    In addition, since file names are also subject to word expansion,
 110    the rules for escape characters in section 3 of this document also
 111    apply.  This is NOT historic behavior in vi, making it impossible
 112    to insert a whitespace, newline or carriage return character into
 113    a file name.  This change could cause a problem if there were files
 114    with ^V's in their names, but I think that's unlikely.
 115
 116 4: Escaping characters in non-file arguments in ex commands:
 117
 118         :abbreviate word string                 (word, string)
 119 *       :edit [+cmd] [file]                     (+cmd)
 120 *       :ex [+cmd] [file]                       (+cmd)
 121         :k key                                  (key)
 122         :map word string                        (word, string)
 123         :mark key                               (key)
 124 *       :set [option ...]                       (option)
 125 *       :tag string                             (string)
 126         :unabbreviate word                      (word)
 127         :unmap word                             (word)
 128
 129    These commands use whitespace to delimit their arguments, and use
 130    ^V to escape those characters.  The exceptions are starred in the
 131    above list, and are discussed below.
 132
 133    In general, I intend to treat a ^V in any argument, followed by
 134    any character, as that literal character.  This will permit
 135    editing of files name "foo|", for example, by using the string
 136    "foo\^V|", where the literal next character protects the pipe
 137    from the ex command parser and the backslash protects it from the
 138    shell expansion.
 139
 140    This is backward compatible with historical vi, although there
 141    were a number of special cases where vi wasn't consistent.
 142
 143 4.1: The edit/ex commands:
 144
 145    The edit/ex commands are a special case because | symbols may
 146    occur in the "+cmd" field, for example:
 147
 148         :edit +10|s/abc/ABC/ file.c
 149
 150    In addition, the edit and ex commands have historically ignored
 151    literal next characters in the +cmd string, so that the following
 152    command won't work.
 153
 154         :edit +10|s/X/^V / file.c
 155
 156    I intend to handle the literal next character in edit/ex consistently
 157    with how it is handled in other commands.
 158
 159    More fun facts to know and tell:
 160         The acid test for the ex/edit commands:
 161
 162                 date > file1; date > file2
 163                 vi
 164                 :edit +1|s/./XXX/|w file1| e file2|1 | s/./XXX/|wq
 165
 166         No version of vi, of which I'm aware, handles it.
 167
 168 4.2: The set command:
 169
 170    The set command treats ^V's as literal characters, so the following
 171    command won't work.  Backslashes do work in this case, though, so
 172    the second version of the command does work.
 173
 174         set tags=tags_file1^V tags_file2
 175         set tags=tags_file1\ tags_file2
 176
 177    I intend to continue permitting backslashes in set commands, but
 178    to also permit literal next characters to work as well.  This is
 179    backward compatible, but will also make set consistent with the
 180    other commands.  I think it's unlikely to break any historic
 181    .exrc's, given that there are probably very few files with ^V's
 182    in their name.
 183
 184 4.3: The tag command:
 185
 186    The tag command ignores ^V's and backslashes; there's no way to
 187    get a space into a tag name.
 188
 189    I think this is a don't care, and I don't intend to fix it.
 190
 191 5: Regular expressions:
 192
 193         :global /pattern/ command
 194         :substitute /pattern/replace/
 195         :vglobal /pattern/ command
 196
 197    I intend to treat a backslash in the pattern, followed by the
 198    delimiter character or a backslash, as that literal character.
 199
 200    This is historic behavior in vi.  It would get rid of a fairly
 201    hard-to-explain special case if we could just use the character
 202    immediately following the backslash in all cases, or, if we
 203    changed nvi to permit using the literal next character as a
 204    pattern escape character, but that would probably break historic
 205    scripts.
 206
 207    There is an additional escaping issue for regular expressions.
 208    Within the pattern and replacement, the '|' character did not
 209    delimit ex commands.  For example, the following is legal.
 210
 211         :substitute /|/PIPE/|s/P/XXX/
 212
 213    This is a special case that I will support.
 214
 215 6: Ending anything with an escape character:
 216
 217    In all of the above rules, an escape character (either ^V or a
 218    backslash) at the end of an argument or file name is not handled
 219    specially, but used as a literal character.