*textobj-user.txt* Support for user-defined text objects
Version 0.3.9
Script ID: 2100
Copyright (C) 2007-2010 kana <http://whileimautomaton.net/>
License: So-called MIT/X 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 *textobj-user-contents*
Introduction |textobj-user-introduction|
Interface |textobj-user-interface|
Functions |textobj-user-functions|
Bugs |textobj-user-bugs|
Changelog |textobj-user-changelog|
==============================================================================
INTRODUCTION *textobj-user-introduction*
*textobj-user* is a Vim plugin to SUPPORT writing user-defined text objects,
especially, simple text objects which can be defined by regular expression.
Note that this plugin only provides functions to support writing user-defined
text objects, and this plugin does not provide any useful text objects. That
is your work.
Requirements:
- Vim 7.0 or later
Latest version:
http://github.com/kana/vim-textobj-user
Document in HTML format:
http://kana.github.com/config/vim/textobj-user.html
==============================================================================
INTERFACE *textobj-user-interface*
------------------------------------------------------------------------------
FUNCTIONS *textobj-user-function*
*textobj#user#move()*
textobj#user#move({pattern}, {flags}, {previous-mode})
Move the cursor to the appropriate object defined by {pattern}.
{flags} is a string, which can contain the following character flags:
char meaning ~
---- ------- ~
'b' search backward instead of forward.
'e' move to the end of the match.
{previous-mode} is a string representing the "previous" mode,
that is, which mode of mapping causes the calling of this function.
For example, if this function is called via a mapping for
Operator-pending mode, {previous-mode} must be 'o'.
char meaning ~
---- ------- ~
'n' Normal mode
'o' Operator-pending mode
'v' Visual mode
Return value is same as |searchpos()|.
*textobj#user#select()*
textobj#user#select({pattern}, {flags}, {prevous-mode})
Select the appropriate object defined by {pattern}.
If the cursor is already in the range of an object, select it.
If the cursor is not in the range of an object, select the nearest
object after the cursor.
{flags} is a string, which can contain the following character flags:
char meaning ~
---- ------- ~
'b' select the nearest object BEFORE the cursor if the
cursor is not in the range of an object.
For the detail of {previous-mode}, see |textobj#user#move()|.
Return value is not defined.
*textobj#user#select_pair()*
textobj#user#select_pair({pattern1}, {pattern2}, {flags}, {previous-mode})
Select the appropriate object which starts with {pattern1} and ends
with {pattern2}.
{flags} is a string, which can contain the following character flags:
char meaning ~
---- ------- ~
'a' select the range including {pattern1} and {pattern2},
like |at|.
'i' select the range excluding {pattern1} and {pattern2},
like |it|. This is the default behavior unless 'a' is
explicitly specified. If the cursor is not in a text
between {pattern1} and {pattern2}, this function does
nothing.
For the detail of {previous-mode}, see |textobj#user#move()|.
Return value is not defined.
*textobj#user#define()*
textobj#user#define({pattern}, {pattern1}, {pattern2}, {guideline})
Support function to define key mappings for the text object defined by
{pattern}, or {pattern1} and {pattern2}. {guideline} is a dictionary
consists of key-value pairs where key is a string to represent the
name of function and value is a list of strings (each string
represents {lhs} for corresponding key).
function name meaning ~
------------- ------- ~
'move-to-next' textobj#user#move({pattern}, '')
'move-to-prev' textobj#user#move({pattern}, 'b')
'move-to-next-end' textobj#user#move({pattern}, 'e')
'move-to-prev-end' textobj#user#move({pattern}, 'be')
'select' synonym for 'select-next'
'select-next' textobj#user#select({pattern}, '',
{previous-mode})
'select-prev' textobj#user#select({pattern}, 'b',
{previous-mode})
'select-pair-all' textobj#user#select_pair({pattern1},
{pattern2},
'a', {previous-mode})
'select-pair-inner' textobj#user#select_pair({pattern1},
{pattern2},
'i', {previous-mode})
Example: >
<
*textobj#user#plugin()*
textobj#user#plugin({plugin}, {obj-specs})
Define key mappings and a command to support writing a plugin which
provides various user-defined text objects.
Example: If textobj#user#plugin() is called like the following: >
<
(1) New command :TextobjFooDefaultKeyMappings will be defined.
This command defines the following key mappings as the default
ones for the new text objects (this command doesn't override
existing {lhs}s unless "!" is given): >
<
(2) New variable g:__textobj_foo will be defined. This is
a dictionary which contains various functions and values.
(3) Key mappings <Plug>(textobj-foo-...) which execute
appropriate actions will be defined if "*pattern*" or
"*{spec}-function*" is given for a {spec}. Otherwise,
<Plug>(textobj-foo-...) will not be defined.
(4) :TextobjFooDefaultKeyMappings will be executed unless
{specs} contains the key "*no-default-key-mappings" or the
variable g:textobj_foo_no_default_key_mappings is defined.
{plugin} is the name of a plugin. It must be a string which consits
of only lowercase alphabets.
{obj-specs} is a dictionary (and given value is cached by this
plugin, so you have to pass copied one if necessary). In this
dictionary, each key/value pair expresses one text object:
- each key is a string of the name of the text object, and
- each value (called as "specs") is a dictionary which denotes some
details of the text object.
The following specs are available:
"move-n" {lhs} or [{lhs}, ...]
A string which is a key sequence to move the cursor to the
next text object. If the value is a list of strings, each
string is mapped to move the cursor.
"move-p" {lhs} or [{lhs}, ...]
"move-N" {lhs} or [{lhs}, ...]
"move-P" {lhs} or [{lhs}, ...]
Like "move-n", but each string is treated as a key sequence to
move the cursor to the previous text object, the end of the
next text object, or the end of the previous text object.
"select" {lhs} or [{lhs}, ...]
Like "move-n", but each string is treated as a key sequence to
select the text object.
"select-a" {lhs} or [{lhs}, ...]
"select-i" {lhs} or [{lhs}, ...]
Like "select", but each string is treated as a key sequence
to select "a" text object or "inner" text object.
"*pattern*" {regexp} or [{regexp}, {regexp}]
A regular expression which matches to a text object. If the
value is a list of two regular expressions, it denotes that
the text object starts with the first regular expression and
ends with the second regular expression.
"*no-default-key-mappings*" anything
If this key exists, :Textobj{Plugin}DefaultKeyMappings will
not be executed when textobj#user#plugin() is called. The
corresponding value doesn't matter.
"*{spec}-function*" {fname}
If this key exists, use the function named {fname} instead of
the default algorithm based on regular expression to select
a text for {spec}.
The function must take no argument and it must return a list
to denote the area to be selected or 0 to denote that there is
nothing to select. The detail of a list is as follows:
[motion_type, start_position, end_position]
- "motion_type" denotes the default type of motion. Valid
values are "v", "V" or "\<C-v>". The meaning of the values
are characterwise, linewise or blockwise.
- "start_position" denotes the start position of the area to
be selected. The detail of this value is the same as
|getpos()|.
- "end_position" is like "start_position", but it denotes the
end position of the area to be selected.
Example definition: >
<
"*sfile*" {string}
Value must be expand('<sfile>'). This value is used to
calculate <SNR> prefix for script-local functions which are
specified "*{spec}-function*".
==============================================================================
BUGS *textobj-user-bugs*
- textobj#user#select() and textobj#user#select_pair() override the current
{Visual}, unlike built-in text objects such as iw/aw, is/as, and so forth.
- textobj#user#select() and textobj#user#select_pair() cannot be used with
[count].
- textobj#user#select_pair() with |o_CTRL-V| may not work properly.
==============================================================================
CHANGELOG *textobj-user-changelog*
0.3.9 2010-04-19T22:02:03+09:00 *textobj-user-changelog-0.3.9*
- |textobj#user#plugin()|: Fix not to define key mappings in Select
mode if appropriate. Now it works smoothly with plugins which
utilize and depend on the default behavior in Select mode.
0.3.8 2009-07-18T10:02:40+09:00 *textobj-user-changelog-0.3.8*
- Fix a bug that it was not possible to select any range which starts
with the end of a line.
- |textobj#user#plugin()|: Fix a bug that it did not accept
any function which is not script-local as a value for
"*{spec}-function*".
0.3.7 2008-10-24T02:25:59+09:00 *textobj-user-changelog-0.3.7*
- |textobj#user#select()|: Fix a bug that it didn't select an object
which: (1) matches to multiple lines and (2) contains the cursor.
- |textobj#user#select()|, |textobj#user#select_pair()|,
|textobj#user#plugin()| with "*{spec}-function*":
Support |o_v| and others. To use this feature, you have to apply
the following patch to Vim:
http://github.com/kana/vim/commits/hack/vimvar-motion_force
0.3.6 2008-08-31T03:17:55+09:00 *textobj-user-changelog-0.3.6*
- Remove unnecessary messages for some cases. They were just for
debugging.
0.3.5 2008-08-24T23:01:45+09:00 *textobj-user-changelog-0.3.5*
Incompatible changes with 0.3.4 or ealier:
- |textobj#user#plugin()|: Change the specification of functions for
"*{spec}-function*".
Other changes:
- |textobj#user#plugin()|: Add missing description of functions for
"*{spec}-function*".
0.3.4 2008-06-26T14:13:33+09:00 *textobj-user-changelog-0.3.4*
- |textobj#user#plugin()|:
- Add "*{spec}-function*" to customize the way to move the cursor or
to select a text by the given function instead of regular
expression based selection.
0.3.3 2008-06-11T21:16:53+09:00 *textobj-user-changelog-0.3.3*
- |textobj#user#plugin()|:
- Rename the spec "*pattern*" instead of "pattern".
- Fix incorrect processing on "*no-default-key-mappings*".
0.3.2 2008-06-11T02:53:41+09:00 *textobj-user-changelog-0.3.2*
- |textobj#user#plugin()|: Change the names of interface mappings for
the text object of which name is '-'.
Old: <Plug>(textobj-{plugin}---a)
New: <Plug>(textobj-{plugin}-a)
0.3.1 2008-06-08T22:05:02+09:00 *textobj-user-changelog-0.3.1*
- |textobj#user#plugin()|: Execute :Textobj{Plugin}DefaultKeyMappings
if necessary.
0.3 2008-06-04T21:16:02+09:00 *textobj-user-changelog-0.3*
- |textobj#user#plugin()|: New.
- |textobj#user#define()|: Now obsolete. Use textobj#user#define().
0.2.2 2008-06-02T06:26:12+09:00 *textobj-user-changelog-0.2.2*
- Fix wrong sentences in the document.
0.2.1 2008-05-22T00:17:24+09:00 *textobj-user-changelog-0.2.1*
- textobj#user#select_pair(): Fix the bug that it selects wrong text
in Operator-pending mode.
0.2 2008-01-07T08:44:14+09:00 *textobj-user-changelog-0.2*
- textobj#user#select(): Fix the wrong selecting in Operator-pending
mode.
- textobj#user#move(): Modify to be able to use in Visual and
Operator-pending mode.
0.1 2007-11-16T01:17:45+09:00 *textobj-user-changelog-0.1*
- Modify to be autoloaded.
- Change the names of all API.
0.0 2007-10-15T20:41:34+09:00 *textobj-user-changelog-0.0*
- First release.
==============================================================================
vim:tw=78:ts=8:ft=help:norl:fen:fdl=0:fdm=marker: