|
|
|
@ -10,195 +10,47 @@ INTRODUCTION *makecols* |
|
|
|
This plugin is a tool for converting lists into columns. |
|
|
|
|
|
|
|
Details follow on the exact semantics, but first, consider the following |
|
|
|
examples. An asterisk (*) is used to denote the cursor position. |
|
|
|
examples. It is assumed that you have selected the "Old text" column. |
|
|
|
|
|
|
|
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!'; |
|
|
|
1 3mcv 1 4 7 |
|
|
|
2 2 5 |
|
|
|
3 3 6 |
|
|
|
4 |
|
|
|
5 5mc 1 2 3 4 5 |
|
|
|
6 6 7 |
|
|
|
7 |
|
|
|
|
|
|
|
|
|
|
|
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. *cS* changes surroundings, placing the surrounded |
|
|
|
text on its own line(s) like |yS|. Details about the second argument can be |
|
|
|
found below in |surround-replacements|. Once again, examples are in order. |
|
|
|
MAPPINGS *makecols-mappings* |
|
|
|
|
|
|
|
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> |
|
|
|
Make columns is *mc* . This can be prefaced with the number of columns |
|
|
|
to make and suffixed with nothing, *v* , or *h* . However, the default is |
|
|
|
horizontal, so specifying *h* would be redundant. |
|
|
|
|
|
|
|
*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".) |
|
|
|
TARGETS *makecols-targets* |
|
|
|
|
|
|
|
Old text Command New text ~ |
|
|
|
Hello w*orld! ysiw) Hello (world)! |
|
|
|
The |mc| |mch| and |mcv| commands all take a *linewise* visual selection. |
|
|
|
They can be prefaced with a number to specify the number of columns the |
|
|
|
output should generate. |
|
|
|
|
|
|
|
As a special case, *yss* operates on the current line, ignoring leading |
|
|
|
whitespace. |
|
|
|
REPLACEMENTS *makecols-replacements* |
|
|
|
|
|
|
|
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 suppressed. In blockwise visual mode, this |
|
|
|
enables surrounding past the end of the line 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). |
|
|
|
|
|
|
|
*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. |
|
|
|
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. If replacing a |
|
|
|
tag, its attributes are kept in the new tag. End your input with > to discard |
|
|
|
the those attributes. If <C-T> is used, the tags will appear on lines by |
|
|
|
themselves. |
|
|
|
|
|
|
|
If s is used, a leading but not trailing space is added. This is useful for |
|
|
|
removing parentheses from a function call with csbs. |
|
|
|
|
|
|
|
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. |
|
|
|
All highlighted text will be removed and replaced by the generated output. |
|
|
|
|
|
|
|
Old text Command New text ~ |
|
|
|
print "Hello *world!" yss- <?php print "Hello world!" ?> |
|
|
|
CUSTOMIZING *makecols-customizing* |
|
|
|
|
|
|
|
Additionally, one can use a global variable for globally available |
|
|
|
replacements. |
|
|
|
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. |
|
|
|
let g:makecols_cols = 5 " default no of cols to 5 |
|
|
|
let g:makecols_orientation = "horz" " default sorting [horz|vert] |
|
|
|
|
|
|
|
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* |
|
|
|
ISSUES *makecols-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: |
lolson
9 years ago