vim-surround/doc/surround.txt

*surround.txt*  Plugin for deleting, changing, and adding "surroundings"

Author:  Tim Pope <http://tpo.pe/>
License: Same terms as Vim itself (see |license|)

This plugin is only available if 'compatible' is not set.

INTRODUCTION                                    *surround*

This plugin is a tool for dealing with pairs of "surroundings."  Examples
of surroundings include parentheses, quotes, and HTML tags.  They are
closely related to what Vim refers to as |text-objects|.  Provided
are mappings to allow for removing, changing, and adding surroundings.

Details follow on the exact semantics, but first, consider the following
examples.  An asterisk (*) is used to denote the cursor position.

  Old text                  Command     New text ~
  "Hello *world!"           ds"         Hello world!
  [123+4*56]/2              cs])        (123+456)/2
  "Look ma, I'm *HTML!"     cs"<q>      <q>Look ma, I'm HTML!</q>
  if *x>3 {                 ysW(        if ( x>3 ) {
  my $str = *whee!;         vlllls'     my $str = 'whee!';

While a few features of this plugin will work in older versions of Vim,
Vim 7 is recommended for full functionality.

MAPPINGS                                        *surround-mappings*

Delete surroundings is *ds* .  The next character given determines the target
to delete.  The exact nature of the target is explained in |surround-targets|
but essentially it is the last character of a |text-object|.  This mapping
deletes the difference between the "i"nner object and "a"n object.  This is
easiest to understand with some examples:

  Old text                  Command     New text ~
  "Hello *world!"           ds"         Hello world!
  (123+4*56)/2              ds)         123+456/2
  <div>Yo!*</div>           dst         Yo!

Change surroundings is *cs* .  It takes two arguments, a target like with
|ds|, and a replacement.  Details about the second argument can be found
below in |surround-replacements|.  Once again, examples are in order.

  Old text                  Command     New text ~
  "Hello *world!"           cs"'        'Hello world!'
  "Hello *world!"           cs"<q>      <q>Hello world!</q>
  (123+4*56)/2              cs)]        [123+456]/2
  (123+4*56)/2              cs)[        [ 123+456 ]/2
  <div>Yo!*</div>           cst<p>      <p>Yo!</p>

*ys* takes a valid Vim motion or text object as the first object, and wraps
it using the second argument as with |cs|.  (It's a stretch, but a good
mnemonic for "ys" is "you surround".)

  Old text                  Command     New text ~
  Hello w*orld!             ysiw)       Hello (world)!

As a special case, *yss* operates on the current line, ignoring leading
whitespace.

  Old text                  Command     New text ~
      Hello w*orld!         yssB            {Hello world!}

There is also *yS* and *ySS* which indent the surrounded text and place it
on a line of its own.

In visual mode, a simple "s" with an argument wraps the selection.  This is
referred to as the *vS* mapping, although ordinarily there will be
additional keystrokes between the v and s.  In linewise visual mode, the
surroundings are placed on separate lines and indented.  In blockwise visual
mode, each line is surrounded.

A "gS" in visual mode, known as *vgS* , behaves similarly.  In linewise visual
mode, the automatic indenting is surpressed.  In blockwise visual mode, this
enables surrounding past the end of the like with 'virtualedit' set (there
seems to be no way in Vim Script to differentiate between a jagged end of line
selection and a virtual block selected past the end of the line, so two maps
were needed).

Additionally, there is a legacy "s" or *vs* mapping which is basically the
same as |vS|.  Due to popular demand of wanting to use "s" as Vim does to mean
replacing the selection (also available as "c"), this mapping is going away.
If you were one of these people and would like to disable "s" with the current
release, indicate this to surround.vim by assigning the "s" mapping to
something else.
>
  xmap <Leader>s <Plug>Vsurround
<
                                                *i_CTRL-G_s* *i_CTRL-G_S*
Finally, there is an experimental insert mode mapping on <C-G>s and <C-S>.
Beware that the latter won't work on terminals with flow control (if you
accidentally freeze your terminal, use <C-Q> to unfreeze it).  The mapping
inserts the specified surroundings and puts the cursor between them.  If,
immediately after the mapping and before the replacement, a second <C-S> or
carriage return is pressed, the prefix, cursor, and suffix will be placed on
three separate lines.  <C-G>S (not <C-G>s) also exhibits this behavior.

TARGETS                                         *surround-targets*

The |ds| and |cs| commands both take a target as their first argument.  The
possible targets are based closely on the |text-objects| provided by Vim.
In order for a target to work, the corresponding text object must be
supported in the version of Vim used (Vim 7 adds several text objects, and
thus is highly recommended).  All targets are currently just one character.

Eight punctuation marks, (, ), {, }, [, ], <, and >, represent themselves
and their counterparts.  If the opening mark is used, contained whitespace is
also trimmed.  The targets b, B, r, and a are aliases for ), }, ], and > 
(the first two mirror Vim; the second two are completely arbitrary and
subject to change).

Three quote marks, ', ", `, represent themselves, in pairs.  They are only
searched for on the current line.

A t is a pair of HTML or XML tags.  See |tag-blocks| for details.  Remember
that you can specify a numerical argument if you want to get to a tag other
than the innermost one.

The letters w, W, and s correspond to a |word|, a |WORD|, and a |sentence|,
respectively.  These are special in that they have nothing to delete, and
used with |ds| they are a no-op.  With |cs|, one could consider them a
slight shortcut for ysi (cswb == ysiwb, more or less).

A p represents a |paragraph|.  This behaves similarly to w, W, and s above;
however, newlines are sometimes added and/or removed.

REPLACEMENTS                                    *surround-replacements*

A replacement argument is a single character, and is required by |cs|, |ys|,
and |vs|.  Undefined replacement characters (with the exception of alphabetic
characters) default to placing themselves at the beginning and end of the
destination, which can be useful for characters like / and |.

If either ), }, ], or > is used, the text is wrapped in the appropriate pair
of characters.  Similar behavior can be found with (, {, and [ (but not <),
which append an additional space to the inside.  Like with the targets above,
b, B, r, and a are aliases for ), }, ], and >.  To fulfill the common need for
code blocks in C-style languages, <C-}> (which is really <C-]>) adds braces on
lines separate from the content.

If t or < is used, Vim prompts for an HTML/XML tag to insert.  You may specify
attributes here and they will be stripped from the closing tag.  End your
input by pressing <CR> or >.  If <C-T> is used, the tags will appear on lines
by themselves.

A deprecated replacement of a LaTeX environment is provided on \ and l.  The
name of the environment and any arguments will be input from a prompt.  This
will be removed once a more fully functional customization system is
implemented.  The following shows the resulting environment from
csp\tabular}{lc<CR>
>
  \begin{tabular}{lc}
  \end{tabular}
<
CUSTOMIZING                                     *surround-customizing*

The following adds a potential replacement on "-" (ASCII 45) in PHP files.
(To determine the ASCII code to use, :echo char2nr("-")).  The carriage
return will be replaced by the original text.
>
  autocmd FileType php let b:surround_45 = "<?php \r ?>"
<
This can be used in a PHP file as in the following example.

  Old text                  Command     New text ~
  print "Hello *world!"     yss-        <?php print "Hello world!" ?>

Additionally, one can use a global variable for globally available
replacements.
>
  let g:surround_45 = "<% \r %>"
  let g:surround_61 = "<%= \r %>"
<
Advanced, experimental, and subject to change:  One can also prompt for
replacement text.  The syntax for this is to surround the replacement in pairs
of low numbered control characters.  If this sounds confusing, that's because
it is (but it makes the parsing easy).  Consider the following example for a
LaTeX environment on the "l" replacement.
>
  let g:surround_108 = "\\begin{\1environment: \1}\r\\end{\1\1}"
<
When this replacement is used,  the user is prompted with an "environment: "
prompt for input.  This input is inserted between each set of \1's.
Additional inputs up to \7 can be used.

Furthermore, one can specify a regular expression substitution to apply.
>
  let g:surround_108 = "\\begin{\1environment: \1}\r\\end{\1\r}.*\r\1}"
<
This will remove anything after the first } in the input when the text is
placed within the \end{} slot.  The first \r marks where the pattern begins,
and the second where the replacement text begins.

Here's a second example for creating an HTML <div>.  The substitution cleverly
prompts for an id, but only adds id="" if it is non-blank.  You may have to
read this one a few times slowly before you understand it.
>
  let g:surround_{char2nr("d")} = "<div\1id: \r..*\r id=\"&\"\1>\r</div>"
<
Inputting text replacements is a proof of concept at this point. The ugly,
unintuitive interface and the brevity of the documentation reflect this.

Finally, It is possible to always append a string to surroundings in insert
mode (and only insert mode).  This is useful with certain plugins and mappings
that allow you to jump to such markings.
>
  let g:surround_insert_tail = "<++>"
<
ISSUES                                          *surround-issues*

Vim could potentially get confused when deleting/changing occurs at the very
end of the line.  Please report any repeatable instances of this.

Do we need to use |inputsave()|/|inputrestore()| with the tag replacement?

Indenting is handled haphazardly.  Need to decide the most appropriate
behavior and implement it.  Right now one can do :let b:surround_indent = 1
(or the global equivalent) to enable automatic re-indenting by Vim via |=|;
should this be the default?

 vim:tw=78:ts=8:ft=help:norl: