Much improved documentation
This commit is contained in:
Tim Pope
parent
62021e986e
commit
1edeffcc0d
@ -1,105 +1,178 @@
|
|||||||
" surround.vim - Surroundings
|
" surround.vim - Surroundings
|
||||||
" Maintainer: Tim Pope <vimNOSPAM@tpope.info>
|
" Maintainer: Tim Pope <vimNOSPAM@tpope.info>
|
||||||
" $Id$
|
" $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 <vimNOSPAM@tpope.info> *surround-author*
|
||||||
|
" License: Same terms as Vim itself (see |license|)
|
||||||
"
|
"
|
||||||
" "ds" is a mapping which deletes the surroundings of a text object--the
|
" This plugin is only available if 'compatible' is not set.
|
||||||
" 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.
|
|
||||||
"
|
"
|
||||||
" Old Keystroke New
|
" Introduction: *surround*
|
||||||
" "Hello *world!" ds" Hello world!
|
|
||||||
" (123+4*56)/2 ds) 123+456/2
|
|
||||||
" <div>Yo!</div> dst Yo!
|
|
||||||
"
|
"
|
||||||
" "cs" does as above, but rather than remove the surroundings, it replaces
|
" This plugin is a tool for dealing with pairs of "surroundings." Examples
|
||||||
" them with something else. It takes two arguments. Once again, examples are
|
" of surroundings include parentheses, quotes, and HTML tags. They are
|
||||||
" in order. (Details about the second argument, the replacement character,
|
" closely related to what Vim refers to as |text-objects|. Provided
|
||||||
" are below).
|
" are mappings to allow for removing, changing, and adding surroundings.
|
||||||
"
|
"
|
||||||
" Old Keystroke New
|
" Details follow on the exact semantics, but first, consider the following
|
||||||
" "Hello *world!" cs"' 'Hello world!'
|
" examples. An asterisk (*) is used to denote the cursor position.
|
||||||
" "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 motion or text object as the first object, and wraps it using
|
" Old text Command New text ~
|
||||||
" the second argument as with "cs".
|
" "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!';
|
||||||
"
|
"
|
||||||
" Old Keystroke New
|
" While a few features of this plugin will work in older versions of Vim,
|
||||||
" Hello w*orld! ysiw) Hello (world)!
|
" 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
|
||||||
|
" <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 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.
|
" whitespace.
|
||||||
"
|
"
|
||||||
" Old Keystroke New
|
" Old text Command New text ~
|
||||||
" Hello w*orld! yssB {Hello world!}
|
" 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 <Plug>VSurround
|
|
||||||
"
|
"
|
||||||
|
" 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 <Plug>Vsurround
|
||||||
|
" <
|
||||||
" Finally, there is an experimental insert mode mapping on <C-S>. Beware that
|
" Finally, there is an experimental insert mode mapping on <C-S>. Beware that
|
||||||
" this won't work on terminals with flow control (if you accidentally freeze
|
" this won't work on terminals with flow control (if you accidentally freeze
|
||||||
" your terminal, use <C-Q> to unfreeze it). This inserts the surrounding
|
" your terminal, use <C-Q> to unfreeze it). The mapping inserts the specified
|
||||||
" characters and puts the cursor between them. If, immediately after <C-S>
|
" surroundings and puts the cursor between them. If, immediately after <C-S>
|
||||||
" and before the replacement carriage return is pressed, the prefix, cursor,
|
" and before the replacement, carriage return is pressed, the prefix, cursor,
|
||||||
" and suffix will be placed on three separate lines.
|
" 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 <C-Z> <Plug>Isurround<CR>
|
||||||
|
" <
|
||||||
|
" 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
|
" Eight punctuation marks, (, ), {, }, [, ], <, and >, represent themselves
|
||||||
" insert that character before and after the text.
|
" 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
|
" Three quote marks, ', ", `, represent themselves, in pairs. They are only
|
||||||
" open/close pair of characters. "(", "[", and "{" behave similarly but add
|
" searched for on the current line.
|
||||||
" an additional space to the inside. "B" and "b" are synonymous with "}" and
|
|
||||||
" ")".
|
|
||||||
"
|
"
|
||||||
" 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.
|
" specify attributes here and they will be stripped from the closing tag.
|
||||||
" End your input by pressing "<CR>" or ">".
|
" End your input by pressing <CR> 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<CR>
|
||||||
|
" >
|
||||||
|
" \begin{tabular}{lc}
|
||||||
|
" \end{tabular}
|
||||||
|
" <
|
||||||
|
" Customizing: *surround-customizing*
|
||||||
"
|
"
|
||||||
" The following adds a potential replacement on "-" (ASCII 45) in PHP files.
|
" The following adds a potential replacement on "-" (ASCII 45) in PHP files.
|
||||||
" (To determine the ASCII code to use, :echo char2nr("-")). The newline will
|
" (To determine the ASCII code to use, :echo char2nr("-")). The newline will
|
||||||
" be replaced by the original text.
|
" be replaced by the original text.
|
||||||
"
|
" >
|
||||||
" autocmd FileType php let b:surround_45 = "<?php \n ?>"
|
" autocmd FileType php let b:surround_45 = "<?php \n ?>"
|
||||||
"
|
" <
|
||||||
" This can be used in a PHP file as in the following example.
|
" This can be used in a PHP file as in the following example.
|
||||||
"
|
"
|
||||||
" Old Keystroke New
|
" Old text Command New text ~
|
||||||
" print "Hello *world!" yss- <?php print "Hello world!" ?>
|
" print "Hello *world!" yss- <?php print "Hello world!" ?>
|
||||||
"
|
"
|
||||||
" Additionally, one can use a global variable for globally available
|
" Additionally, one can use a global variable for globally available
|
||||||
" replacements.
|
" replacements.
|
||||||
"
|
" >
|
||||||
" let g:surround_45 = "<% \n %>"
|
" let g:surround_45 = "<% \n %>"
|
||||||
"
|
" <
|
||||||
" Issues:
|
" Issues: *surround-issues*
|
||||||
"
|
"
|
||||||
" Vim could potentially get confused when deleting/changing occurs at the very
|
" 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
|
" Customization isn't very flexible. Need a system that allows for prompting,
|
||||||
" similar to with tags.
|
" 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
|
" 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
|
" (or the global equivalent) to enable automatic re-indenting by Vim via |=|;
|
||||||
" this be the default?
|
" 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
|
let s:cpo_save = &cpo
|
||||||
set cpo&vim
|
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("<sfile>:p")
|
||||||
|
let s:dir = expand("<sfile>:p:h:h") " }}}1
|
||||||
|
|
||||||
" Input functions {{{1
|
" Input functions {{{1
|
||||||
|
|
||||||
function! s:getchar()
|
function! s:getchar()
|
||||||
@ -435,7 +538,7 @@ function! s:opfunc(type) " {{{1
|
|||||||
let &selection = sel_save
|
let &selection = sel_save
|
||||||
endfunction " }}}1
|
endfunction " }}}1
|
||||||
|
|
||||||
function! s:closematch(str)
|
function! s:closematch(str) " {{{1
|
||||||
" Close an open (, {, [, or < on the command line.
|
" Close an open (, {, [, or < on the command line.
|
||||||
let tail = matchstr(a:str,'.[^\[\](){}<>]*$')
|
let tail = matchstr(a:str,'.[^\[\](){}<>]*$')
|
||||||
if tail =~ '^\[.\+'
|
if tail =~ '^\[.\+'
|
||||||
@ -449,32 +552,28 @@ function! s:closematch(str)
|
|||||||
else
|
else
|
||||||
return ""
|
return ""
|
||||||
endif
|
endif
|
||||||
endfunction
|
endfunction " }}}1
|
||||||
|
|
||||||
function! s:closedcmd()
|
nnoremap <silent> <Plug>Dsurround :<C-U>call <SID>dosurround(<SID>inputtarget())<CR>
|
||||||
let cm = s:closematch()
|
nnoremap <silent> <Plug>Csurround :<C-U>call <SID>changesurround()<CR>
|
||||||
return getcmdline() . cm
|
nnoremap <silent> <Plug>Ysurround :set opfunc=<SID>opfunc<CR>g@
|
||||||
endfunction
|
nnoremap <silent> <Plug>Yssurround :<C-U>call <SID>opfunc(v:count1)<CR>
|
||||||
|
vnoremap <silent> <Plug>Vsurround :<C-U>call <SID>opfunc(visualmode())<CR>
|
||||||
|
inoremap <silent> <Plug>Isurround <C-R>=<SID>insert()<CR>
|
||||||
|
|
||||||
nnoremap <silent> <Plug>DSurround :<C-U>call <SID>dosurround(<SID>inputtarget())<CR>
|
if !exists("g:surround_no_mappings") || ! g:surround_no_mappings
|
||||||
nnoremap <silent> <Plug>CSurround :<C-U>call <SID>changesurround()<CR>
|
nmap ds <Plug>Dsurround
|
||||||
nnoremap <silent> <Plug>YSurround :set opfunc=<SID>opfunc<CR>g@
|
nmap cs <Plug>Csurround
|
||||||
nnoremap <silent> <Plug>YSSurround :<C-U>call <SID>opfunc(v:count1)<CR>
|
nmap ys <Plug>Ysurround
|
||||||
vnoremap <silent> <Plug>VSurround :<C-U>call <SID>opfunc(visualmode())<CR>
|
nmap yss <Plug>Yssurround
|
||||||
inoremap <silent> <Plug>ISurround <C-R>=<SID>insert()<CR>
|
if !hasmapto("<Plug>Vsurround","v")
|
||||||
|
vmap s <Plug>Vsurround
|
||||||
|
endif
|
||||||
nmap ds <Plug>DSurround
|
if !hasmapto("<Plug>Isurround","i")
|
||||||
nmap cs <Plug>CSurround
|
imap <C-S> <Plug>Isurround
|
||||||
nmap ys <Plug>YSurround
|
endif
|
||||||
nmap yss <Plug>YSSurround
|
|
||||||
if !hasmapto("<Plug>VSurround","v")
|
|
||||||
vmap s <Plug>VSurround
|
|
||||||
endif
|
endif
|
||||||
if !hasmapto("<Plug>ISurround","i")
|
|
||||||
imap <C-S> <Plug>ISurround
|
|
||||||
endif
|
|
||||||
|
|
||||||
|
|
||||||
let &cpo = s:cpo_save
|
let &cpo = s:cpo_save
|
||||||
|
|
||||||
|
" vim:set ft=vim sw=4 sts=4 et:
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user