*submode.txt* Create your own submodes
Version 0.0.0
Script ID: 2467
Copyright (C) 2008 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 *submode-contents*
Introduction |submode-introduction|
Interface |submode-interface|
Functions |submode-functions|
Variables |submode-variables|
Bugs |submode-bugs|
Changelog |submode-changelog|
==============================================================================
INTRODUCTION *submode-introduction*
*submode* is a Vim plugin to provide the way to define "submodes" to the
built-in |vim-modes|. For example, whenever you type |g-| and/or |g+| to
undo/redo many times, don't you want to type "g++--++..." instead
"g+g+g-g-g+g+..."? With this plugin, you can define such interface with the
following settings:
>
<
The above settings mean:
- Define a new submode named "undo/redo".
- Define "g-" and "g+" as key sequences to enter the submode "undo/redo" from
Normal mode. Aditionally, they does undo/redo before entering the submode
"undo/redo".
- In the submode "undo/redo", "-" and "+" do undo/redo.
- In the submode "undo/redo", "<Esc>" leaves the submode.
*submode-leaving*
By default, <Esc> is automatically defined as a key to leave any submode.
So you don't have to explicitly define like the above example.
There are also 2 ways to leave submodes:
- Type any key sequence which is not mapped in the submode.
- Don't type any key for a long time. See |submode-variables| to configure
the details of this time out.
Requirements:
- Vim 7.2 or later
Latest version:
http://github.com/kana/config/commits/vim-submode
Document in HTML format:
http://kana.github.com/config/vim/submode.html
==============================================================================
INTERFACE *submode-interface*
------------------------------------------------------------------------------
COMMANDS *submode-commands*
:SubmodeRestoreOptions *:SubmodeRestoreOptions*
Ex command version of |submode#restore_options()|.
------------------------------------------------------------------------------
FUNCTIONS *submode-functions*
*submode#enter_with()*
submode#enter_with({submode}, {modes}, {options}, {lhs}, [{rhs}])
Define a key mapping to enter the {submode} from
{modes}. If {rhs} is given, it will be executed
whenever entering the {submode} by {lhs}.
See |submode#map()| for the details of arguments.
*submode#leave_with()*
submode#leave_with({submode}, {modes}, {options}, {lhs})
Define a key mapping ({lhs}) to leave the {submode} in
{modes}.
See |submode#map()| for the details of arguments.
*submode#map()*
submode#map({submode}, {modes}, {options}, {lhs}, {rhs})
Define a key mapping ({lhs} to {rhs}) in the {submode}
in {modes}.
{submode} String
The name of the submode. It is recommended to
use only the following characters:
Alphabets A-Z, a-z
Digits 0-9
Some symbols -, _, /
{modes} String
A sequence of letters which specifies the
modes to define a key mapping. The meanings
of letters are as follows:
c Command-line mode
i Insert mode
n Normal mode
s Select mode only
v Visual mode and Select mode
x Visual mode only
Note that Operator-pending mode and
|language-mapping| are not supported, because
the both modes are always leaved by 1 key
sequence, so that submdoes can't be built on
the both modes.
{options} String
A sequence of letters which specifies some
options for a key mapping to be defined. The
meanings of letters are as follows:
b Same as |:map-<buffer>|.
e Same as |:map-<expr>|.
r {rhs} may be remapped.
If this letter is not included,
{rhs} will be never remapped.
s Same as |:map-<silent>|.
u Same as |:map-<unique>|.
x After executing {rhs}, leave the
submode. This matters only for
|submode#map()|.
{lhs} String
A key sequence to type.
To denote a special key such as <Esc>, write
it in <>-escaped form instead of the character
as is. For example, use '<Esc>' instead of
"\<Esc>".
{rhs} String
A key sequence to be executed by typing {lhs}.
See also {lhs} for other notes.
submode#restore_options() *submode#restore_options()*
Restore options overriden by this plugin.
This plugin overrides some options before entering
a submode and restores the options after leaving
a submode. <C-c> can be used to leave a submode, but
it disturbs to restore the options. Call this
function if you do so.
*submode#unmap()*
submode#unmap({submode}, {modes}, {options}, {lhs})
Delete a key mapping ({lhs} to something) in the
{submode} in {modes}.
See |submode#map()| for the details of arguments.
Note that only "b" matters for {options} and other
letters are just ignored.
------------------------------------------------------------------------------
VARIABLES *submode-variables*
g:submode_keyseqs_to_leave list of strings (default: ['<Esc>'])
The default key sequences to leave a submode.
g:submode_timeout boolean (default: same as 'timeout')
If this value is true, time out on submodes is enabled. Otherwise,
time out is disabled. If time out is enabled, not typing any key in
a submode for a long time causes to leave the submode.
If this variable is not defined, the value of 'timeout' is used
instead.
g:submode_timeoutlen number (default: same as 'timeoutlen')
The time in milliseconds that is waited for typing keys in a submode.
If this variable is not defined, the value of 'timeoutlen' is used
instead.
==============================================================================
BUGS *submode-bugs*
LIMITATIONS ~
- In {rhs} of a key mapping for a submode, <SID> cannot be used. Because key
mappings for a submode is defined by this plugin, not callers.
- To behave the same as Normal mode and Visual mode, any unbound key sequence
should be ignored in a submode, but it's impossible to implement.
PROBLEMS ~
- Missing [count] support in a submode.
- Unmap mappings for a submode properly. The current inplementation just
replaces rhs with <Nop>, but it may cause some problems.
- Add commands like |:map| and others to deal with submode mappings for
readability.
- There are many bugs around the world.
==============================================================================
CHANGELOG *submode-changelog*
0.0.0 2008-11-27T01:58:43+09:00 *submode-changelog-0.0.0*
- Initial version.
==============================================================================
vim:tw=78:ts=8:ft=help:norl:fen:fdl=0:fdm=marker: