*operator-user.txt*     Define your own operator easily

Version 0.0.5
Script ID: 2692
Copyright (C) 2009 kana <http://whileimautomaton.net/>
License: MIT license  {{{
    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.
}}}

CONTENTS                                        *operator-user-contents*

Introduction            |operator-user-introduction|
Interface               |operator-user-interface|
  Functions               |operator-user-functions|
Examples                |operator-user-examples|
Bugs                    |operator-user-bugs|
Changelog               |operator-user-changelog|




==============================================================================
INTRODUCTION                                    *operator-user-introduction*

*operator-user* is a Vim library plugin to provide an easy way to define your
own |operator|.  Though there are several pitfalls to define operators, you
don't have to take care of them with |operator#user#define()| which are
provided by this library plugin.

For example, the following code defines operator "_" to adjust the height of
the current window to the same as the target range:
>
        map _  <Plug>(operator-adjust)
        call operator#user#define('adjust', 'Op_adjust_window_height')
        function! Op_adjust_window_height(motion_wiseness)
          execute (line("']") - line("'[") + 1) 'wincmd' '_'
          normal! `[zt
        endfunction
<
You can use this operator as follows:

        10__    Adjust to 10 lines and show the current line at the top.
        _ip     Adjust to the same height of the paragraph under the cursor.

This operator is useful to adjust the visible content in the current window.

See also |operator-user-examples| for more examples and explanations.


Requirements:
- Vim 7.2 or later

Optionals:
- |grex| (vimscript#2773)
- |operator-replace| (vimscript#2782)
- |wwwsearch| (vimscript#2785)

Latest version:
http://github.com/kana/config/commits/vim-operator-user

Document in HTML format:
http://kana.github.com/config/vim/operator-user.html




==============================================================================
INTERFACE                                       *operator-user-interface*

------------------------------------------------------------------------------
FUNCTIONS                                       *operator-user-functions*

                                                *operator#user#define()*
operator#user#define({name}, {function}, [{extra} ...])
                        Define a new operator.

                        {name}               (string)
                                The name of the operator to be defined.

                                In Normal mode and Visual mode,
                                <Plug>(operator-{name}) is mapped to a magic
                                stuff to execute the operator.

                                In Operator-pending mode,
                                <Plug>(operator-{name}) is mapped to |g@| to
                                operate linewise like |cc|, |dd|, etc.

                        {function}   (string)
                                The name of a function to be called whenever
                                the operator is executed.

                        {extra}              (string)
                                An arbitrary Ex command to be executed after
                                setting 'operatorfunc' and before executing
                                the operator.

                                If multiple {extra}s are given, they are
                                joined together into one string.  A whitespace
                                is put in between them.  Then the string will
                                be used instead.

                                See also |operator-user-examples| how to use.

                                           *operator#user#define_ex_command()*
operator#user#define_ex_command({name}, {ex-command})
                        Define an operator-version of {ex-command}.

                        {name}               (string)
                                Same as the one for |operator#user#define()|.

                        {ex-command} (string)
                                An Ex command to be executed whenever the
                                operator is executed.  Range must not be
                                included.

                                This argument is used as follows:
>
                                        '[,']{ex-command}
<

                               *operator#user#visual_command_from_wise_name()*
operator#user#visual_command_from_wise_name({wise-name})
                        Return a "visual command" corresponding to
                        {wise-name}, where a "visual command" is a string
                        corresponding to one of the following commands: |v|,
                        |V| or |<C-v>|.

                        {wise-name}  (string)
                                The name of a wise of {motion} or {Visual}.
                                It can be one of the following values:
                                "char", "line", "block".

                        See |operator-user-examples-D| for usage.




==============================================================================
EXAMPLES                                        *operator-user-examples*

                                                *operator-user-examples-A*
(A) The following setting defines operator-version of |:right|, and map "L" to
execute the operator:
>
        map L  <Plug>(operator-align-right)
        call operator#user#define('align-right', 'Op_command_right')
        function! Op_command_right(motion_wiseness)
          '[,']right
        endfunction
<

                                                *operator-user-examples-B*
(B) The following setting defines a generic version of (A).
    This is also an example to use {extra} for |operator#user#define()|:
>
        map H  <Plug>(operator-align-left)
        map L  <Plug>(operator-align-right)
        map M  <Plug>(operator-align-center)

        call operator#user#define('align-left', 'Op_command',
        \                         'call Set_op_command("left")')
        call operator#user#define('align-right', 'Op_command',
        \                         'call Set_op_command("right")')
        call operator#user#define('align-center', 'Op_command',
        \                         'call Set_op_command("center")')

        let s:op_command_command = ''

        function! Set_op_command(command)
          let s:op_command_command = a:command
        endfunction

        function! Op_command(motion_wiseness)
          execute "'[,']" s:op_command_command
        endfunction
<

                                                *operator-user-examples-C*
(C) With |operator#user#define_ex_command()|, the example (B) can be
    simplified as follows:
>
        map H  <Plug>(operator-align-left)
        map L  <Plug>(operator-align-right)
        map M  <Plug>(operator-align-center)

        call operator#user#define_ex_command('align-left', 'left')
        call operator#user#define_ex_command('align-right', 'right')
        call operator#user#define_ex_command('align-center', 'center')
<

                                                *operator-user-examples-D*
(D) In 'operatorfunc', we usually have to convert the name of the wise of
{motion} into the corresponding command to start Visual mode.
With |operator#user#visual_command_from_wise_name()|,
This routine can be written as follows:
>
        call operator#user#define('void-change', 'OperatorVoidChange',
        function! OperatorVoidChange(motion_wise)
          let v = operator#user#visual_command_from_wise_name(a:motion_wise)
          execute 'normal!' '`[' . v . '`]"_c' 
        endfunction
<




==============================================================================
BUGS                                            *operator-user-bugs*

                                                *operator-user-bugs-A*
(A) |operator#user#define()| defines a key mapping "<Plug>(operator-{name}) to
    |g@|" in Operator-pending mode to select text linewise like |cc|, |dd|,
    etc.  But this behavior may be harmful in the following sense:

    If you define two operators "A" and "B", you can operate the cursor line
    with "AA" and "BB".  But you can ALSO operate the cursor line with "AB"
    and "BA".  These "{operator-A}{operator-B}" key combinations are not
    expected to work as if "{operator-A}{operator-A}", because there is no
    such default key binding.

                                                *operator-user-bugs-B*
(B) In Visual mode, any operator defined by |operator#user#define()| cannot
    handle |count| correctly.  It acts as if count is not given.

                                                *operator-user-bugs-C*
(C) |operator#user#define()| defines "named" key mappings
    "<Plug>(operator-{name})" to execute an operator, and you have to define
    other key mappings to type to execute the operator.  |operator-user|
    doesn't provide any official way to skip defining "named" key mappings.
    It is an intentional design.

    See also the following article for the details.
    The article is also useful if you want to write your own plulgin:
    ``Vim: Plugins should provide "named" key sequences to customize hotkeys,
    not variables'' <http://whileimautomaton.net/2008/09/27/02/27/35/diary>




==============================================================================
CHANGELOG                                       *operator-user-changelog*

0.0.6   2009-09-10T20:36:13+09:00              *operator-user-changelog-0.0.6*
        - Add links for scripts that use this plugin.
          See |operator-user-introduction|.

0.0.5   2009-09-08T07:28:56+09:00              *operator-user-changelog-0.0.5*
        - Add |operator#user#visual_command_from_wise_name()|.
        - Revise a bit of the document.

0.0.4   2009-09-07T20:18:31+09:00              *operator-user-changelog-0.0.4*
        - Fix a bug that it rarely fails to select the same text as a given
          {motion} in Normal mode.  It is caused by a bug in Vim; |v:count1|
          may be 0 in some cases.
        - Fix a bug that register designation ("a, "b, etc) doesn't work for
          user defiend operators.

0.0.3   2009-09-04T20:11:07+09:00              *operator-user-changelog-0.0.3*
        Incompatible change:
        - |operator#user#define()|, |operator#user#define_ex_command()|:
          Change the meaning of the first argument:

          Old versions:
                  The argument is {lhs} to execute the operator to be defined.

          New version:
                  The argument is {name} of the operator to be defined.
                  {lhs} to execute the operator is "<Plug>(operator-{name})".

          See also |operator-user-bugs-C| for the details.

0.0.2   2009-09-04T05:58:28+09:00              *operator-user-changelog-0.0.2*
        - Add |operator#user#define_ex_command()|.
        - Add a note on a bug.  See |operator-user-bugs-B| for the details.
        - Remove :DefineOperator.  It's useless as a part of this library.

0.0.1   2009-07-18T04:41:22+09:00              *operator-user-changelog-0.0.1*
        - Rename as "operator-user".  The old name "myoperator" is not good
          for further works.

0.0.0   2009-06-26T02:51:29+09:00              *operator-user-changelog-0.0.0*
        - Initial version.




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