doc/surround.txt

   1 *surround.txt*  Plugin for deleting, changing, and adding "surroundings"
   2
   3 Author:  Tim Pope <vimNOSPAM@tpope.info>        *surround-author*
   4 License: Same terms as Vim itself (see |license|)
   5
   6 This plugin is only available if 'compatible' is not set.
   7
   8 INTRODUCTION                                    *surround*
   9
  10 This plugin is a tool for dealing with pairs of "surroundings."  Examples
  11 of surroundings include parentheses, quotes, and HTML tags.  They are
  12 closely related to what Vim refers to as |text-objects|.  Provided
  13 are mappings to allow for removing, changing, and adding surroundings.
  14
  15 Details follow on the exact semantics, but first, consider the following
  16 examples.  An asterisk (*) is used to denote the cursor position.
  17
  18   Old text                  Command     New text ~
  19   "Hello *world!"           ds"         Hello world!
  20   [123+4*56]/2              cs])        (123+456)/2
  21   "Look ma, I'm *HTML!"     cs"<q>      <q>Look ma, I'm HTML!</q>
  22   if *x>3 {                 ysW(        if ( x>3 ) {
  23   my $str = *whee!;         vlllls'     my $str = 'whee!';
  24
  25 While a few features of this plugin will work in older versions of Vim,
  26 Vim 7 is recommended for full functionality.
  27
  28 MAPPINGS                                        *surround-mappings*
  29
  30 Delete surroundings is *ds* .  The next character given determines the target
  31 to delete.  The exact nature of the target are explained in |surround-targets|
  32 but essentially it is the last character of a |text-object|.  This mapping
  33 deletes the difference between the "inner" object and "an" object.  This is
  34 easiest to understand with some examples:
  35
  36   Old text                  Command     New text ~
  37   "Hello *world!"           ds"         Hello world!
  38   (123+4*56)/2              ds)         123+456/2
  39   <div>Yo!*</div>           dst         Yo!
  40
  41 Change surroundings is *cs* .  It takes two arguments, a target like with
  42 |ds|, and a replacement.  Details about the second argument can be found
  43 below in |surround-replacements|.  Once again, examples are in order.
  44
  45   Old text                  Command     New text ~
  46   "Hello *world!"           cs"'        'Hello world!'
  47   "Hello *world!"           cs"<q>      <q>Hello world!</q>
  48   (123+4*56)/2              cs)]        [123+456]/2
  49   (123+4*56)/2              cs)[        [ 123+456 ]/2
  50   <div>Yo!*</div>           cst<p>      <p>Yo!</p>
  51
  52 *ys* takes an valid Vim motion or text object as the first object, and wraps
  53 it using the second argument as with |cs|.  (Unfortunately there's no good
  54 mnemonic for "ys".)
  55
  56   Old text                  Command     New text ~
  57   Hello w*orld!             ysiw)       Hello (world)!
  58
  59 As a special case, *yss* operates on the current line, ignoring leading
  60 whitespace.
  61
  62   Old text                  Command     New text ~
  63       Hello w*orld!         yssB            {Hello world!}
  64
  65 There is also *yS* and *ySS* which indent the surrounded text and place it
  66 on a line of its own.
  67
  68 In visual mode, a simple "s" with an argument wraps the selection.  This is
  69 referred to as the *vs* mapping, although ordinarily there will be
  70 additional keystrokes between the v and s.  In linewise visual mode, the
  71 surroundings are placed on separate lines.  In blockwise visual mode, each
  72 line is surrounded.
  73
  74 An "S" in visual mode (*vS*) behaves similarly but always places the
  75 surroundings on separate lines.  Additionally, the surrounded text is
  76 indented.  In blockwise visual mode, using "S" instead of "s" instead skips
  77 trailing whitespace.
  78
  79 Note that "s" and "S" already have valid meaning in visual mode, but it is
  80 identical to "c".  If you have muscle memory for "s" and would like to use a
  81 different key, add your own mapping and the existing one will be disabled.
  82 >
  83   vmap <Leader>s <Plug>Vsurround
  84   vmap <Leader>S <Plug>VSurround
  85 <
  86                                                 *i_CTRL-G_s* *i_CTRL-G_S*
  87 Finally, there is an experimental insert mode mapping on <C-G>s and <C-S>.
  88 Beware that the latter won't work on terminals with flow control (if you
  89 accidentally freeze your terminal, use <C-Q> to unfreeze it).  The mapping
  90 inserts the specified surroundings and puts the cursor between them.  If,
  91 immediately after the mapping and before the replacement, a second <C-S> or
  92 carriage return is pressed, the prefix, cursor, and suffix will be placed on
  93 three separate lines.  <C-G>S (not <C-G>s) also exhibits this behavior.
  94
  95 TARGETS                                         *surround-targets*
  96
  97 The |ds| and |cs| commands both take a target as their first argument.  The
  98 possible targets are based closely on the |text-objects| provided by Vim.
  99 In order for a target to work, the corresponding text object must be
 100 supported in the version of Vim used (Vim 7 adds several text objects, and
 101 thus is highly recommended).  All targets are currently just one character.
 102
 103 Eight punctuation marks, (, ), {, }, [, ], <, and >, represent themselves
 104 and their counterpart.  If the opening mark is used, contained whitespace is
 105 also trimmed.  The targets b, B, r, and a are aliases for ), }, ], and >
 106 (the first two mirror Vim; the second two are completely arbitrary and
 107 subject to change).
 108
 109 Three quote marks, ', ", `, represent themselves, in pairs.  They are only
 110 searched for on the current line.
 111
 112 A t is a pair of HTML or XML tags.  See |tag-blocks| for details.  Remember
 113 that you can specify a numerical argument if you want to get to a tag other
 114 than the innermost one.
 115
 116 The letters w, W, and s correspond to a |word|, a |WORD|, and a |sentence|,
 117 respectively.  These are special in that they have nothing to delete, and
 118 used with |ds| they are a no-op.  With |cs|, one could consider them a
 119 slight shortcut for ysi (cswb == ysiwb, more or less).
 120
 121 A p represents a |paragraph|.  This behaves similarly to w, W, and s above;
 122 however, newlines are sometimes added and/or removed.
 123
 124 REPLACEMENTS                                    *surround-replacements*
 125
 126 A replacement argument is a single character, and is required by |cs|, |ys|,
 127 and |vs|.  Undefined replacement characters (with the exception of alphabetic
 128 characters) default to placing themselves at the beginning and end of the
 129 destination, which can be useful for characters like / and |.
 130
 131 If either ), }, ], or > is used, the text is wrapped in the appropriate pair
 132 of characters.  Similar behavior can be found with (, {, and [ (but not <),
 133 which append an additional space to the inside.  Like with the targets above,
 134 b, B, r, and a are aliases for ), }, ], and >.  To fulfill the common need for
 135 code blocks in C-style languages, <C-}> (which is really <C-]>) adds braces on
 136 lines separate from the content.
 137
 138 If t or < is used, Vim prompts for an HTML/XML tag to insert.  You may specify
 139 attributes here and they will be stripped from the closing tag.  End your
 140 input by pressing <CR> or >.  If <C-T> is used, the tags will appear on lines
 141 by themselves.
 142
 143 A deprecated replacement of a LaTeX environment is provided on \ and l.  The
 144 name of the environment and any arguments will be input from a prompt.  This
 145 will be removed once a more fully functional customization system is
 146 implemented.  The following shows the resulting environment from
 147 csp\tabular}{lc<CR>
 148 >
 149   \begin{tabular}{lc}
 150   \end{tabular}
 151 <
 152 CUSTOMIZING                                     *surround-customizing*
 153
 154 The following adds a potential replacement on "-" (ASCII 45) in PHP files.
 155 (To determine the ASCII code to use, :echo char2nr("-")).  The carriage
 156 return will be replaced by the original text.
 157 >
 158   autocmd FileType php let b:surround_45 = "<?php \r ?>"
 159 <
 160 This can be used in a PHP file as in the following example.
 161
 162   Old text                  Command     New text ~
 163   print "Hello *world!"     yss-        <?php print "Hello world!" ?>
 164
 165 Additionally, one can use a global variable for globally available
 166 replacements.
 167 >
 168   let g:surround_45 = "<% \r %>"
 169   let g:surround_61 = "<%= \r %>"
 170 <
 171 Advanced, experimental, and subject to change:  One can also prompt for
 172 replacement text.  The syntax for this is to surround the replacement in pairs
 173 of low numbered control characters.  If this sounds confusing, that's because
 174 it is (but it makes the parsing easy).  Consider the following example for a
 175 LaTeX environment on the "l" replacement.
 176 >
 177   let g:surround_108 = "\\begin{\1environment: \1}\r\\end{\1\1}"
 178 <
 179 When this replacement is used,  the user is prompted with an "environment: "
 180 prompt for input.  This input is inserted between each set of \1's.
 181 Additional inputs up to \7 can be used.
 182
 183 Furthermore, one can specify a regular expression substitution to apply.
 184 >
 185   let g:surround_108 = "\\begin{\1environment: \1}\r\\end{\1\r}.*\r\1}"
 186 <
 187 This will remove anything after the first } in the input when the text is
 188 placed within the \end{} slot.  The first \r marks where the pattern begins,
 189 and the second where the replacement text begins.
 190
 191 Here's a second example for creating an HTML <div>.  The substitution cleverly
 192 prompts for an id, but only adds id="" if it is non-blank.  You may have to
 193 read this one a few times slowly before you understand it.
 194 >
 195   let g:surround_{char2nr("d")} = "<div\1id: \r..*\r id=\"&\"\1>\r</div>"
 196 <
 197 Inputting text replacements is a proof of concept at this point. The ugly,
 198 unintuitive interface and the brevity of the documentation reflect this.
 199
 200 Finally, It is possible to always append a string to surroundings in insert
 201 mode (and only insert mode).  This is useful with certain plugins and mappings
 202 that allow you to jump to such markings.
 203 >
 204   let g:surround_insert_tail = "<++>"
 205 <
 206 ISSUES                                          *surround-issues*
 207
 208 Vim could potentially get confused when deleting/changing occurs at the very
 209 end of the line.  Please report any repeatable instances of this.
 210
 211 Do we need to use |inputsave()|/|inputrestore()| with the tag replacement?
 212
 213 Indenting is handled haphazardly.  Need to decide the most appropriate
 214 behavior and implement it.  Right now one can do :let b:surround_indent = 1
 215 (or the global equivalent) to enable automatic re-indenting by Vim via |=|;
 216 should this be the default?
 217
 218  vim:tw=78:ts=8:ft=help:norl: