diff --git a/plugin/surround.vim b/plugin/surround.vim index acbb480..be04510 100644 --- a/plugin/surround.vim +++ b/plugin/surround.vim @@ -1,105 +1,178 @@ " surround.vim - Surroundings " Maintainer: Tim Pope " $Id$ +" Help is below; it may be read here, or :call SurroundHelp() to install it as +" a help file. + +" *surround.txt* Plugin for deleting, changing, and adding "surroundings" " -" Usage: +" Author: Tim Pope *surround-author* +" License: Same terms as Vim itself (see |license|) " -" "ds" is a mapping which deletes the surroundings of a text object--the -" difference between the "inner" object and "an" object. See the :help on -" text-objects for details. This is easiest to understand with some examples; -" in the following, * represents the cursor position. +" This plugin is only available if 'compatible' is not set. " -" Old Keystroke New -" "Hello *world!" ds" Hello world! -" (123+4*56)/2 ds) 123+456/2 -"
Yo!
dst Yo! +" Introduction: *surround* " -" "cs" does as above, but rather than remove the surroundings, it replaces -" them with something else. It takes two arguments. Once again, examples are -" in order. (Details about the second argument, the replacement character, -" are below). +" 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. " -" Old Keystroke New -" "Hello *world!" cs"' 'Hello world!' -" "Hello *world!" cs" Hello world! -" (123+4*56)/2 cs)] [123+456]/2 -" (123+4*56)/2 cs)[ [ 123+456 ]/2 -"
Yo!
cst

Yo!

+" Details follow on the exact semantics, but first, consider the following +" examples. An asterisk (*) is used to denote the cursor position. " -" "ys" takes a motion or text object as the first object, and wraps it using -" the second argument as with "cs". +" Old text Command New text ~ +" "Hello *world!" ds" Hello world! +" [123+4*56]/2 cs]) (123+456)/2 +" "Look ma, I'm *HTML!" cs" Look ma, I'm HTML! +" if *x>3 { ysW( if ( x>3 ) { +" my $str = *whee!; vlllls' my $str = 'whee!'; " -" Old Keystroke New -" Hello w*orld! ysiw) Hello (world)! +" While a few features of this plugin will work in older versions of Vim, +" Vim 7 is recommended for full functionality. " -" As a special case, "yss" operates on the current line, ignoring leading +" Mappings: *surround-mappings* +" +" Delete surroundings is *ds*. The next character given determines the target +" to delete. The exact nature of the target are explained in +" |surround-targets| but essentially it is the last character of a +" |text-object|. This mapping deletes the difference between the "inner" +" object and "an" 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 +"
Yo!*
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" Hello world! +" (123+4*56)/2 cs)] [123+456]/2 +" (123+4*56)/2 cs)[ [ 123+456 ]/2 +"
Yo!*
cst

Yo!

+" +" *ys* takes an valid Vim motion or text object as the first object, and wraps +" it using the second argument as with |cs|. (Unfortunately there's no good +" mnemonic for "ys"). +" +" 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 Keystroke New -" Hello w*orld! yssB {Hello world!} -" -" In visual mode, a simple "s" with an argument wraps the selection. -" Note that "s" already has a valid meaning in visual mode, but it is -" identical to "c". If you have muscle memory for "s" and would like to use a -" different key, add your own mapping and the existing one will be disabled. -" -" vmap S VSurround +" Old text Command New text ~ +" Hello w*orld! yssB {Hello world!} " +" 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. Note that "s" already has a +" valid meaning in visual mode, but it is identical to "c". If you have +" muscle memory for "s" and would like to use a different key, add your own +" mapping and the existing one will be disabled. +" > +" vmap S Vsurround +" < " Finally, there is an experimental insert mode mapping on . Beware that " this won't work on terminals with flow control (if you accidentally freeze -" your terminal, use to unfreeze it). This inserts the surrounding -" characters and puts the cursor between them. If, immediately after -" and before the replacement carriage return is pressed, the prefix, cursor, -" and suffix will be placed on three separate lines. +" your terminal, use to unfreeze it). The mapping inserts the specified +" surroundings and puts the cursor between them. If, immediately after +" and before the replacement, carriage return is pressed, the prefix, cursor, +" and suffix will be placed on three separate lines. If this is a common use +" case you can add a mapping for it as well. +" > +" imap Isurround +" < +" Targets: *surround-targets* " -" Replacements: +" 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. " -" A replacement argument is a single character. The default behavior is to -" insert that character before and after the text. +" Eight punctuation marks, (, ), {, }, [, ], <, and >, represent themselves +" and their counterpart. 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). " -" If ")", "]", "}", or ">" are used, the text is wrapped in the appropriate -" open/close pair of characters. "(", "[", and "{" behave similarly but add -" an additional space to the inside. "B" and "b" are synonymous with "}" and -" ")". +" Three quote marks, ', ", `, represent themselves, in pairs. They are only +" searched for on the current line. " -" If "t" or "<" is used, Vim prompts for an HTML/XML tag to insert. You may +" A t is a pair of HTML or XML tags. See |tag-blocks| for details. +" +" The letters w, W, and s correspond to a |word|, a |WORD|, and a |sentence|, +" respectively. These are special in that they have nothing do 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 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 >. +" +" 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 "" or ">". +" End your input by pressing or >. " -" Customizing: +" An experimental replacement of a LaTeX environment is provided on \ and l. +" The name of the environment and any arguments will be input from a prompt. +" Opening and closing delimiters are not automatically placed on lines of +" their own; you must arrange for this to happen. The following shows the +" resulting environment from csp\tabular}{lc +" > +" \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 newline will " be replaced by the original text. -" -" autocmd FileType php let b:surround_45 = "" -" +" > +" autocmd FileType php let b:surround_45 = "" +" < " This can be used in a PHP file as in the following example. " -" Old Keystroke New -" print "Hello *world!" yss- +" Old text Command New text ~ +" print "Hello *world!" yss- " " Additionally, one can use a global variable for globally available " replacements. -" -" let g:surround_45 = "<% \n %>" -" -" Issues: +" > +" let g:surround_45 = "<% \n %>" +" < +" Issues: *surround-issues* " " Vim could potentially get confused when deleting/changing occurs at the very -" end of the line. Pleae report any repeatable instances of this. +" end of the line. Please report any repeatable instances of this. " -" Do we need to use inputsave() / inputrestore() with the tag replacement? +" Do we need to use |inputsave()|/|inputrestore()| with the tag replacement? " -" Customization isn't very flexible. Need a system that allows for prompting -" similar to with tags. +" Customization isn't very flexible. Need a system that allows for prompting, +" like with HTML tags and LaTeX environments. " -" Reindenting is handled haphazardly. Need to decide the most appropriate +" 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 reindenting by Vim; should -" this be the default? +" (or the global equivalent) to enable automatic re-indenting by Vim via |=|; +" should this be the default? " -" It would be nice if . would work to repeat an operation. +" It would be nice if |.| would work to repeat an operation. " ============================================================================ @@ -114,6 +187,36 @@ let g:loaded_surround = 1 let s:cpo_save = &cpo set cpo&vim +function! SurroundHelp() " {{{1 + if !isdirectory(s:dir."/doc/") && exists("*mkdir") + call mkdir(s:dir."/doc/") + endif + let old_hidden = &hidden + let old_cpo = &cpo + set hidden + set cpo&vim + exe "split ".fnamemodify(s:dir."/doc/surround.txt",":~") + setlocal noai modifiable noreadonly + %d_ + exe "0r ".fnamemodify(s:file,":~") + norm "_d}}"_dG + a + vim:tw=78:ts=8:ft=help:norl: +. + 1d_ + %s/^" \=// + silent! %s/^\(\u\l\+\):\(\s\+\*\)/\U\1 \2/ + setlocal noreadonly + write + bwipe! + let &hidden = old_hidden + let &cpo = old_cpo + exe "helptags ".fnamemodify(s:dir."/doc",":~") + help surround +endfunction +let s:file = expand(":p") +let s:dir = expand(":p:h:h") " }}}1 + " Input functions {{{1 function! s:getchar() @@ -435,7 +538,7 @@ function! s:opfunc(type) " {{{1 let &selection = sel_save endfunction " }}}1 -function! s:closematch(str) +function! s:closematch(str) " {{{1 " Close an open (, {, [, or < on the command line. let tail = matchstr(a:str,'.[^\[\](){}<>]*$') if tail =~ '^\[.\+' @@ -449,32 +552,28 @@ function! s:closematch(str) else return "" endif -endfunction +endfunction " }}}1 -function! s:closedcmd() - let cm = s:closematch() - return getcmdline() . cm -endfunction +nnoremap Dsurround :call dosurround(inputtarget()) +nnoremap Csurround :call changesurround() +nnoremap Ysurround :set opfunc=opfuncg@ +nnoremap Yssurround :call opfunc(v:count1) +vnoremap Vsurround :call opfunc(visualmode()) +inoremap Isurround =insert() -nnoremap DSurround :call dosurround(inputtarget()) -nnoremap CSurround :call changesurround() -nnoremap YSurround :set opfunc=opfuncg@ -nnoremap YSSurround :call opfunc(v:count1) -vnoremap VSurround :call opfunc(visualmode()) -inoremap ISurround =insert() - - -nmap ds DSurround -nmap cs CSurround -nmap ys YSurround -nmap yss YSSurround -if !hasmapto("VSurround","v") - vmap s VSurround +if !exists("g:surround_no_mappings") || ! g:surround_no_mappings + nmap ds Dsurround + nmap cs Csurround + nmap ys Ysurround + nmap yss Yssurround + if !hasmapto("Vsurround","v") + vmap s Vsurround + endif + if !hasmapto("Isurround","i") + imap Isurround + endif endif -if !hasmapto("ISurround","i") - imap ISurround -endif - let &cpo = s:cpo_save +" vim:set ft=vim sw=4 sts=4 et: