*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:
>
<
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-exmaples| 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:
>
<
*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:
>
<
*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()|:
>
<
*operator-user-examples-C*
(C) With |operator#user#define_ex_command()|, the example (B) can be
simplified as follows:
>
<
*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:
>
<
==============================================================================
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: