vim/bundle/surround/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 is explained in |surround-targets|
  32 but essentially it is the last character of a |text-object|.  This mapping
  33 deletes the difference between the "i"nner object and "a"n 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 a 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 and indented.  In blockwise visual
  72 mode, each line is surrounded.
  73
  74 A "gS" in visual mode, known as *vgS* , behaves similarly.  In linewise visual
  75 mode, the automatic indenting is surpressed.  In blockwise visual mode, this
  76 enables surrounding past the end of the like with 'virtualedit' set (there
  77 seems to be no way in Vim Script to differentiate between a jagged end of line
  78 selection and a virtual block selected past the end of the line, so two maps
  79 were needed).
  80
  81 Additionally, there is a legacy "s" or *vs* mapping which is basically the
  82 same as |vS|.  Due to popular demand of wanting to use "s" as Vim does to mean
  83 replacing the selection (also available as "c"), this mapping is going away.
  84 If you were one of these people and would like to disable "s" with the current
  85 release, indicate this to surround.vim by assigning the "s" mapping to
  86 something else.
  87 >
  88   xmap <Leader>s <Plug>Vsurround
  89 <
  90                                                 *i_CTRL-G_s* *i_CTRL-G_S*
  91 Finally, there is an experimental insert mode mapping on <C-G>s and <C-S>.
  92 Beware that the latter won't work on terminals with flow control (if you
  93 accidentally freeze your terminal, use <C-Q> to unfreeze it).  The mapping
  94 inserts the specified surroundings and puts the cursor between them.  If,
  95 immediately after the mapping and before the replacement, a second <C-S> or
  96 carriage return is pressed, the prefix, cursor, and suffix will be placed on
  97 three separate lines.  <C-G>S (not <C-G>s) also exhibits this behavior.
  98
  99 TARGETS                                         *surround-targets*
 100
 101 The |ds| and |cs| commands both take a target as their first argument.  The
 102 possible targets are based closely on the |text-objects| provided by Vim.
 103 In order for a target to work, the corresponding text object must be
 104 supported in the version of Vim used (Vim 7 adds several text objects, and
 105 thus is highly recommended).  All targets are currently just one character.
 106
 107 Eight punctuation marks, (, ), {, }, [, ], <, and >, represent themselves
 108 and their counterparts.  If the opening mark is used, contained whitespace is
 109 also trimmed.  The targets b, B, r, and a are aliases for ), }, ], and >
 110 (the first two mirror Vim; the second two are completely arbitrary and
 111 subject to change).
 112
 113 Three quote marks, ', ", `, represent themselves, in pairs.  They are only
 114 searched for on the current line.
 115
 116 A t is a pair of HTML or XML tags.  See |tag-blocks| for details.  Remember
 117 that you can specify a numerical argument if you want to get to a tag other
 118 than the innermost one.
 119
 120 The letters w, W, and s correspond to a |word|, a |WORD|, and a |sentence|,
 121 respectively.  These are special in that they have nothing to delete, and
 122 used with |ds| they are a no-op.  With |cs|, one could consider them a
 123 slight shortcut for ysi (cswb == ysiwb, more or less).
 124
 125 A p represents a |paragraph|.  This behaves similarly to w, W, and s above;
 126 however, newlines are sometimes added and/or removed.
 127
 128 REPLACEMENTS                                    *surround-replacements*
 129
 130 A replacement argument is a single character, and is required by |cs|, |ys|,
 131 and |vs|.  Undefined replacement characters (with the exception of alphabetic
 132 characters) default to placing themselves at the beginning and end of the
 133 destination, which can be useful for characters like / and |.
 134
 135 If either ), }, ], or > is used, the text is wrapped in the appropriate pair
 136 of characters.  Similar behavior can be found with (, {, and [ (but not <),
 137 which append an additional space to the inside.  Like with the targets above,
 138 b, B, r, and a are aliases for ), }, ], and >.  To fulfill the common need for
 139 code blocks in C-style languages, <C-}> (which is really <C-]>) adds braces on
 140 lines separate from the content.
 141
 142 If t or < is used, Vim prompts for an HTML/XML tag to insert.  You may specify
 143 attributes here and they will be stripped from the closing tag.  End your
 144 input by pressing <CR> or >.  If <C-T> is used, the tags will appear on lines
 145 by themselves.
 146
 147 A deprecated replacement of a LaTeX environment is provided on \ and l.  The
 148 name of the environment and any arguments will be input from a prompt.  This
 149 will be removed once a more fully functional customization system is
 150 implemented.  The following shows the resulting environment from
 151 csp\tabular}{lc<CR>
 152 >
 153   \begin{tabular}{lc}
 154   \end{tabular}
 155 <
 156 CUSTOMIZING                                     *surround-customizing*
 157
 158 The following adds a potential replacement on "-" (ASCII 45) in PHP files.
 159 (To determine the ASCII code to use, :echo char2nr("-")).  The carriage
 160 return will be replaced by the original text.
 161 >
 162   autocmd FileType php let b:surround_45 = "<?php \r ?>"
 163 <
 164 This can be used in a PHP file as in the following example.
 165
 166   Old text                  Command     New text ~
 167   print "Hello *world!"     yss-        <?php print "Hello world!" ?>
 168
 169 Additionally, one can use a global variable for globally available
 170 replacements.
 171 >
 172   let g:surround_45 = "<% \r %>"
 173   let g:surround_61 = "<%= \r %>"
 174 <
 175 Advanced, experimental, and subject to change:  One can also prompt for
 176 replacement text.  The syntax for this is to surround the replacement in pairs
 177 of low numbered control characters.  If this sounds confusing, that's because
 178 it is (but it makes the parsing easy).  Consider the following example for a
 179 LaTeX environment on the "l" replacement.
 180 >
 181   let g:surround_108 = "\\begin{\1environment: \1}\r\\end{\1\1}"
 182 <
 183 When this replacement is used,  the user is prompted with an "environment: "
 184 prompt for input.  This input is inserted between each set of \1's.
 185 Additional inputs up to \7 can be used.
 186
 187 Furthermore, one can specify a regular expression substitution to apply.
 188 >
 189   let g:surround_108 = "\\begin{\1environment: \1}\r\\end{\1\r}.*\r\1}"
 190 <
 191 This will remove anything after the first } in the input when the text is
 192 placed within the \end{} slot.  The first \r marks where the pattern begins,
 193 and the second where the replacement text begins.
 194
 195 Here's a second example for creating an HTML <div>.  The substitution cleverly
 196 prompts for an id, but only adds id="" if it is non-blank.  You may have to
 197 read this one a few times slowly before you understand it.
 198 >
 199   let g:surround_{char2nr("d")} = "<div\1id: \r..*\r id=\"&\"\1>\r</div>"
 200 <
 201 Inputting text replacements is a proof of concept at this point. The ugly,
 202 unintuitive interface and the brevity of the documentation reflect this.
 203
 204 Finally, It is possible to always append a string to surroundings in insert
 205 mode (and only insert mode).  This is useful with certain plugins and mappings
 206 that allow you to jump to such markings.
 207 >
 208   let g:surround_insert_tail = "<++>"
 209 <
 210 ISSUES                                          *surround-issues*
 211
 212 Vim could potentially get confused when deleting/changing occurs at the very
 213 end of the line.  Please report any repeatable instances of this.
 214
 215 Do we need to use |inputsave()|/|inputrestore()| with the tag replacement?
 216
 217 Indenting is handled haphazardly.  Need to decide the most appropriate
 218 behavior and implement it.  Right now one can do :let b:surround_indent = 1
 219 (or the global equivalent) to enable automatic re-indenting by Vim via |=|;
 220 should this be the default?
 221
 222  vim:tw=78:ts=8:ft=help:norl: