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