operator-surround.txt

*operator-surround.txt*                 operator mappings to deal with surrounds

Author : rhysd <lin90162@yahoo.co.jp>

CONTENTS         *operator-surround-contents*

Introduction     |operator-surround-introduction|
Usage            |operator-surround-usage|
Policy           |operator-surround-policy|
Install          |operator-surround-install|
Dependency       |operator-surround-dependency|
Mappings         |operator-surround-mappings|
Variables        |operator-surround-variables|
Setup Example    |operator-surround-setup-example|
    |vim-surround| Compatible Setting  |operator-surround-vim-surround-compatible|
Repository Page  |operator-surround-repository-page|
License          |operator-surround-license|


==============================================================================
INTRODUCTION                                    *operator-surround-introduction*

*operator-surround* provides Vim operator mappings to deal with surrounds like
() , '', "" and so on.  In addition, when both ends of the text-object are the
same characters, |operator-surround| recognizes them as a surround (this
behavior is customizable with some variables).
Definitions of blocks are very customizable with |g:operator#surround#blocks|.


==============================================================================
USAGE                                                  *operator-surround-usage*

First, set |operator-surround-mappings| to your favorite mappings.  These
mappings append/delete/replace the |text-objects| you specified.

To append surrounds, use |<Plug>(operator-surround-append)|.  For example, if
you map it to |sa|, |saiw(| surrounds current inner word with ().  |iw| is a
text object for inner words.
>
    hoge -> (hoge)
<
To delete surrounds, use |<Plug>(operator-surround-delete)|.  For example, if
you map it to |sd|, |sdiW| deletes a surround which is included in a word.
>
    (hoge) -> hoge
<
To replace surrounds, use |<Plug>(operator-surround-replace)|.  For example,
if you map it to |sr|, |sriW'| replaces a surround which is included in a word
with ''.
>
    "hoge" -> 'hoge'
<
Default blocks are (), [], {}, <>, "", '', ``, (  ) and {  }.


==============================================================================
POLICY (or why I don't use |vim-surround|)              *operator-surround-policy*

- Simplicity

    All should be done with operator mappings.

- Extensibility

    The behavior should be highly customizable with |g:operator#surround#blocks|
    and text objects like vim-textobj-multiblock, vim-textobj-between or
    vim-textobj-anyblock.

- Well-tested

c.f.
https://github.com/osyo-manga/vim-textobj-multiblock
https://github.com/thinca/vim-textobj-between
https://github.com/rhysd/vim-textobj-anyblock


==============================================================================
INSTALL                                              *operator-surround-install*

Using Vim plugin package manager is recommended.  I use |neobundle|, and
|vundle| seems the most famous.
If you want to install manually, it is not recommended, copy files and
directories in autoload, doc and plugin directories to your vim config
directory.  Vim config directory is usually $HOME/vimfiles on Windows or
~/.vim in other operating systems.


==============================================================================
DEPENDENCY                                        *operator-surround-dependency*

|operator-user| (required)
    https://github.com/kana/vim-operator-user


==============================================================================
MAPPINGS                                             *operator-surround-mappings*

These mappings are for |mapmode-x| and |mapmode-n|.

<Plug>(operator-surround-append)              *<Plug>(operator-surround-append)*

    Operator mapping to surround the text-object.  After you specify text
    object, you must input some key sequence.  If the sequence is defined in
    |g:operator#surround#blocks|, the block would be appended.  Otherwise, the
    input would be appended to the both ends of the text-object.

<Plug>(operator-surround-delete)              *<Plug>(operator-surround-delete)*

    Operator mapping to delete the surround in the text-object.  If the
    text-object is a block defined in |g:operator#surround#blocks| like
    '(hoge)' or if the text object's both ends are the same sequence like
    '!?hoge!?', the surrounds would be deleted.  For example, '(' and ')' for
    '(hoge)', '!?' and '!?' for '!?hoge!?'.

<Plug>(operator-surround-replace)            *<Plug>(operator-surround-replace)*

    Operator mapping to replace surround with other surround in the
    text-object.  This mapping's process is the same sequence as 'first, do
    <Plug>(operator-surround-delete) and second, do
    <Plug>(operator-surround-append)'.


==============================================================================
VARIABLES                                          *operator-surround-variables*

g:operator#surround#blocks                          *g:operator#surround#blocks*
                                                    *b:operator#surround#blocks*

    Block definitions.  This is |Dictionary| of |List| which elements represent
    a block.  This value has higher priority than default blocks so you can
    define your own blocks.

    For example, below is default definitions:
>
    \ {
    \   '-' : [
    \       { 'block' : ['(', ')'], 'motionwise' : ['char', 'line', 'block'], 'keys' : ['(', ')'] },
    \       { 'block' : ['[', ']'], 'motionwise' : ['char', 'line', 'block'], 'keys' : ['[', ']'] },
    \       { 'block' : ['{', '}'], 'motionwise' : ['char', 'line', 'block'], 'keys' : ['{', '}'] },
    \       { 'block' : ['<', '>'], 'motionwise' : ['char', 'line', 'block'], 'keys' : ['<', '>'] },
    \       { 'block' : ['"', '"'], 'motionwise' : ['char', 'line', 'block'], 'keys' : ['"'] },
    \       { 'block' : ["'", "'"], 'motionwise' : ['char', 'line', 'block'], 'keys' : ["'"] },
    \       { 'block' : ['`', '`'], 'motionwise' : ['char', 'line', 'block'], 'keys' : ['`'] },
    \       { 'block' : ['( ', ' )'], 'motionwise' : ['char', 'line', 'block'], 'keys' : [' (', ' )'] },
    \       { 'block' : ['{ ', ' }'], 'motionwise' : ['char', 'line', 'block'], 'keys' : [' {', ' }'] },
    \   ],
    \ }
<
    The keys of |g:operator#surround#blocks| ('-' in above example) mean
    filetypes.  If you specify 'ruby', it means its blocks is available only
    in Ruby sources.  '-' is a special key and it means its blocks are
    available in any filetypes.
    The values of |g:operator#surround#blocks| represent block definitions.
    They are |Dictionary| and must have following keys; block, motionwise and
    keys.

      - block
        'block' means a surround which is consisted with the pair of the
        begin of it and the end of it.

      - motionwise
        Key motionwise represents that which kind of a text object, the block is
        available.  'char' means characterwise, 'line' means linewise and
        'block' means blockwise.  In above example, ['(', ')'] block is
        used in all kinds of objects.

      - keys
        'keys' are input you specify in |<Plug>(operator-surround-append)|
        or |<Plug>(operator-surround-replace)|.  If your input is equivalent to
        any of these values, the block is selected.  Length of input can be
        more than 1.  In above example, if you input '<Space>(', ['( ', ' )']
        block would be selected.

    You can also define buffer local version |b:operator#surround#blocks|.
    It is used only in the buffer and has higher priority than
    |g:operator#surround#blocks|.

g:operator#surround#default_blocks          *g:operator#surround#default_blocks*

    The default blocks.  This variable is readonly.  If you will modify this
    variable, an exception will be thrown.  The value is shown in
    |g:operator#surround#blocks|.

    The default block definitions are:
>
    \ {
    \   '-' : [
    \       { 'block' : ['(', ')'], 'motionwise' : ['char', 'line', 'block'], 'keys' : ['(', ')'] },
    \       { 'block' : ['[', ']'], 'motionwise' : ['char', 'line', 'block'], 'keys' : ['[', ']'] },
    \       { 'block' : ['{', '}'], 'motionwise' : ['char', 'line', 'block'], 'keys' : ['{', '}'] },
    \       { 'block' : ['<', '>'], 'motionwise' : ['char', 'line', 'block'], 'keys' : ['<', '>'] },
    \       { 'block' : ['"', '"'], 'motionwise' : ['char', 'line', 'block'], 'keys' : ['"'] },
    \       { 'block' : ["'", "'"], 'motionwise' : ['char', 'line', 'block'], 'keys' : ["'"] },
    \       { 'block' : ['`', '`'], 'motionwise' : ['char', 'line', 'block'], 'keys' : ['`'] },
    \       { 'block' : ['( ', ' )'], 'motionwise' : ['char', 'line', 'block'], 'keys' : [' (', ' )'] },
    \       { 'block' : ['{ ', ' }'], 'motionwise' : ['char', 'line', 'block'], 'keys' : [' {', ' }'] },
    \   ],
    \ }
<
                                    *g:operator#surround#uses_input_if_no_block*
g:operator#surround#uses_input_if_no_block

    If the value is non-zero, use not only block definitions but also input
    sequence when appending and replacing surrounds.  For example, if you
    input ! and ! is not any keys in block definitions, the text-object would
    be surrounded with !.
    The default value is 1.

                          *g:operator#surround#recognizes_both_ends_as_surround*
g:operator#surround#recognizes_both_ends_as_surround

    If the value is non-zero, if the both ends of the text-object are the same
    sequence, the sequence is recognized as a surround.  For example, if
    '!?hoge!?' is a text-object, the both ends of it are the same sequence
    '!?'.  Then it is recognized as a surround.
    The default value is 1.

g:operator#surround#no_default_blocks    *g:operator#surround#no_default_blocks*

    If the value is non-zero, default block definitions defined in
    |g:operator#surround#default_blocks| are not used.

    The default value is 0.

g:operator#surround#ignore_space              *g:operator#surround#ignore_space*

    If the value is non-zero, surroundings ignores white spaces when they are
    added with <Plug>(operator-surround-append) or
    <Plug>(operator-surround-replace).
    The default value is 1.


==============================================================================
SETUP EXAMPLE                                  *operator-surround-setup-example*

Below is an example of setting for .vimrc.  Note that these mappings overwrite
|s| mapping.
>
    " add ```...``` surround when filetype is markdown
    let g:operator#surround#blocks = {
        \ 'markdown' : [
    \       { 'block' : ["```\n", "\n```"], 'motionwise' : ['line'], 'keys' : ['`'] },
        \ ] }

    " operator mappings
    map <silent>sa <Plug>(operator-surround-append)
    map <silent>sd <Plug>(operator-surround-delete)
    map <silent>sr <Plug>(operator-surround-replace)


    " delete or replace most inner surround using vim-textobj-multiblock or
    " vim-textobj-anyblock

    " if you use vim-textobj-multiblock
    nmap <silent>sdd <Plug>(operator-surround-delete)<Plug>(textobj-multiblock-a)
    nmap <silent>srr <Plug>(operator-surround-replace)<Plug>(textobj-multiblock-a)
    " if you use vim-textobj-anyblock
    nmap <silent>sdd <Plug>(operator-surround-delete)<Plug>(textobj-anyblock-a)
    nmap <silent>srr <Plug>(operator-surround-replace)<Plug>(textobj-anyblock-a)

    " delete or replace the object which is put between the same character
    " using vim-textobj-between

    " if you use vim-textobj-between
    nmap <silent>sdb <Plug>(operator-surround-delete)<Plug>(textobj-between-a)
    nmap <silent>srb <Plug>(operator-surround-replace)<Plug>(textobj-between-a)
<

------------------------------------------------------------------------------
|vim-surround| COMPATIBLE SETTING      *operator-surround-vim-surround-compatible*

If you use |operator-surround| as an alternative to |vim-surround|.  You may
want to use |operator-surround| with the same mappings as |vim-surround|.
But I don't recommend this setting because the feature of |operator-surround|
is not the one of |vim-surround|.
I think this setting can't take the advantage of |operator-surround|.  And note
that these mappings overwrite some Vim's default mappings (for example, y in
visual mode).
>
    map <silent>ys <Plug>(operator-surround-append)
    map <silent>ds <Plug>(operator-surround-delete)
    map <silent>cs <Plug>(operator-surround-replace)
    nmap <silent>yss V<Plug>(operator-surround-append)
    nmap <silent>dss V<Plug>(operator-surround-delete)
    nmap <silent>css V<Plug>(operator-surround-replace)
<

==============================================================================
REPOSITORY PAGE                              *operator-surround-repository-page*

The latest version of |operator-surround| is available at
https://github.com/rhysd/vim-operator-surround

Contributions (pull requests) are welcome.  None of them are too short.
Especially, English check is very helpful because I'm poor at English :(


==============================================================================
LICENSE                                              *operator-surround-license*

|operator-surround| is distributed under MIT license.

  Copyright (c) 2013 rhysd

  Permission is hereby granted, free of charge, to any person obtaining
  a copy of this software and associated documentation files (the
  "Software"), to deal in the Software without restriction, including
  without limitation the rights to use, copy, modify, merge, publish,
  distribute, sublicense, and/or sell copies of the Software, and to
  permit persons to whom the Software is furnished to do so, subject to
  the following conditions:
  The above copyright notice and this permission notice shall be
  included in all copies or substantial portions of the Software.

  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
  IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
  CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
  TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
  SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.


==============================================================================
vim:tw=78:ts=8:ft=help:norl:et:fen:fdl=0: