diff --git a/doc/surround.txt b/doc/surround.txt new file mode 100644 index 0000000..d24c874 --- /dev/null +++ b/doc/surround.txt @@ -0,0 +1,183 @@ +*surround.txt* Plugin for deleting, changing, and adding "surroundings" + +Author: Tim Pope *surround-author* +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" Look ma, I'm HTML! + 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 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 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. In blockwise visual mode, each +line is surrounded. + +An "S" in visual mode (*vS*) behaves similarly but always places the +surroundings on separate lines. Additionally, the surrounded text is +indented. In blockwise visual mode, using "S" instead of "s" instead skips +trailing whitespace. + +Note that "s" and "S" already have 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 + vmap S VSurround +< + *i_CTRL-G_s* *i_CTRL-G_S* +Finally, there is an experimental insert mode mapping on s and . +Beware that the latter won't work on terminals with flow control (if you +accidentally freeze your terminal, use 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 or +carriage return is pressed, the prefix, cursor, and suffix will be placed on +three separate lines. S (not 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 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). + +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 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 (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 >. + +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 >. As an experimental feature, if +is used, the tags will appear on lines by themselves. + +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. +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 carriage +return will be replaced by the original text. +> + autocmd FileType php let b:surround_45 = "" +< +This can be used in a PHP file as in the following example. + + Old text Command New text ~ + print "Hello *world!" yss- + +Additionally, one can use a global variable for globally available +replacements. +> + let g:surround_45 = "<% \r %>" + let g:surround_61 = "<%= \r %>" +< +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? + +Customization isn't very flexible. Need a system that allows for prompting, +like with HTML tags and LaTeX environments. + +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? + +It would be nice if |.| would work to repeat an operation. + vim:tw=78:ts=8:ft=help:norl: diff --git a/plugin/surround.vim b/plugin/surround.vim index 3a9e751..4a6a244 100644 --- a/plugin/surround.vim +++ b/plugin/surround.vim @@ -1,192 +1,14 @@ " surround.vim - Surroundings -" Maintainer: Tim Pope +" Author: Tim Pope " GetLatestVimScripts: 1697 1 :AutoInstall: surround.vim " $Id$ -" Help is below; it may be read here. Alternatively, after the plugin is -" installed and running, :call SurroundHelp() to install a proper help file. - -" *surround.txt* Plugin for deleting, changing, and adding "surroundings" " -" Author: Tim Pope *surround-author* -" License: Same terms as Vim itself (see |license|) +" See surround.txt for help. This can be accessed by doing " -" This plugin is only available if 'compatible' is not set. +" :helptags ~/.vim/doc +" :help surround " -" 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" Look ma, I'm HTML! -" 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 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 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. In blockwise visual mode, each -" line is surrounded. -" -" An "S" in visual mode (*vS*) behaves similarly but always places the -" surroundings on separate lines. Additionally, the surrounded text is -" indented. In blockwise visual mode, using "S" instead of "s" instead skips -" trailing whitespace. -" -" Note that "s" and "S" already have 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 -" vmap S VSurround -" < -" *i_CTRL-G_s* *i_CTRL-G_S* -" Finally, there is an experimental insert mode mapping on s and . -" Beware that the latter won't work on terminals with flow control (if you -" accidentally freeze your terminal, use 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 or -" carriage return is pressed, the prefix, cursor, and suffix will be placed on -" three separate lines. S (not 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 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). -" -" 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 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 (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 >. -" -" 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 >. As an experimental feature, if , or -" is used, the tags will appear on lines by themselves. -" -" 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. -" 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 carriage -" return will be replaced by the original text. -" > -" autocmd FileType php let b:surround_45 = "" -" < -" This can be used in a PHP file as in the following example. -" -" Old text Command New text ~ -" print "Hello *world!" yss- -" -" Additionally, one can use a global variable for globally available -" replacements. -" > -" let g:surround_45 = "<% \r %>" -" let g:surround_61 = "<%= \r %>" -" < -" 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? -" -" Customization isn't very flexible. Need a system that allows for prompting, -" like with HTML tags and LaTeX environments. -" -" 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? -" -" It would be nice if |.| would work to repeat an operation. +" Licensed under the same terms as Vim itself. " ============================================================================ @@ -201,36 +23,6 @@ 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()