Permalink
Browse files

Rewrite the document for 1.x

  • Loading branch information...
1 parent 3ec42f8 commit 4e0f310993226b441aeb15580a9ebdc414e3feae @kana committed Mar 16, 2013
Showing with 361 additions and 118 deletions.
  1. +361 −118 doc/textobj-user.txt
View
479 doc/textobj-user.txt
@@ -27,9 +27,10 @@ License: MIT license {{{
CONTENTS *textobj-user-contents*
Introduction |textobj-user-introduction|
+Philosophy |textobj-user-philosophy|
Reference |textobj-user-reference|
Obsolete API |textobj-user-obsolete-api|
-Bugs |textobj-user-bugs|
+Known issues |textobj-user-known-issues|
Changelog |textobj-user-changelog|
@@ -38,14 +39,75 @@ Changelog |textobj-user-changelog|
==============================================================================
INTRODUCTION *textobj-user-introduction*
-*textobj-user* is a Vim plugin to create your own text objects.
+*textobj-user* is a Vim plugin to create your own text objects without pain.
It is hard to create text objects, because there are many pitfalls to deal
with. This plugin hides such details and provides a declarative way to define
-text objects. You can use regular expressions to define text objects if they
-are simple enough, or functions to define complex ones.
+text objects. You can use regular expressions to define simple text objects,
+or use functions to define complex ones. For example...
+
+ *textobj-user-example-simple*
+(a) Define "ad"/"id" to select a date such as "2013-03-16", and
+ define "at"/"it" to select a time such as "22:04:21":
+>
+ call textobj#user#define('datetime', {
+ \ 'date': {
+ \ 'pattern': '\<\d\d\d\d-\d\d-\d\d\>',
+ \ 'select': ['ad', 'id'],
+ \ },
+ \ 'time': {
+ \ 'pattern': '\<\d\d:\d\d:\d\d\>',
+ \ 'select': ['at', 'it'],
+ \ },
+ \ })
+<
+ *textobj-user-example-between*
+(b) Define "aP" to select a PHP code with "<?php" and "?>", and
+ define "iP" to select a PHP code without "<?php" and "?>":
+>
+ call textobj#user#define('php', {
+ \ 'code': {
+ \ 'pattern': ['<?php\>', '?>'],
+ \ 'select-a': 'aP',
+ \ 'select-i': 'iP',
+ \ },
+ \ })
+<
+ *textobj-user-example-complex*
+(c) Define "al" to select the current line, and
+ define "il" to select the current line without indentation:
+>
+ call textobj#user#define('line', {
+ \ '-': {
+ \ 'select-a-function': 'CurrentLineA',
+ \ 'select-a': 'aP',
+ \ 'select-i-function': 'CurrentLineI',
+ \ 'select-i': 'iP',
+ \ },
+ \ })
+
+ function! CurrentLineA()
+ normal! 0
+ let head_pos = getpos('.')
+ normal! $
+ let tail_pos = getpos('.')
+ return ['v', head_pos, tail_pos]
+ endfunction
+
+ function! CurrentLineI()
+ normal! ^
+ let head_pos = getpos('.')
+ normal! g_
+ let tail_pos = getpos('.')
+ let non_blank_char_exists_p = getline('.')[head_pos[2] - 1] !~# '\s'
+ return
+ \ non_blank_char_exists_p
+ \ ? ['v', head_pos, tail_pos]
+ \ : 0
+ endfunction
+<
-Note that this plugin is just a library to create text objects, so that it
-does not provide useful text objects. That is your work.
+You can define your own text objects like the above examples.
+See also |textobj-user-reference| for more details.
There are many text objects written with textobj-user. If you want to find
useful ones, or to know how they are implemented, see the following page:
@@ -65,8 +127,284 @@ http://vim-doc.heroku.com/view?https://raw.github.com/kana/vim-textobj-user/mast
==============================================================================
+PHILOSOPHY *textobj-user-philosophy*
+
+Suppose that you define custom text objects. Why do you define them?
+You must believe that they are useful and they boost your productivity.
+Such text objects are also useful for other users.
+If so, why don't you share them as a plugin?
+
+This is the reason why textobj-user provides just one function
+|textobj#user#define()|. It defines not only key mappings like aX/iX for
+custom text objects, but also everything that is necessary to share as
+a plugin. For example, one might prefer aY/iY to aX/iX for custom text
+objects. So that it's necessary to provides a way for such cusotmization,
+but it's somewhat tedious to define such stuffs by hand.
+
+
+
+
+==============================================================================
REFERENCE *textobj-user-reference*
+ *textobj#user#define()*
+textobj#user#define({plugin-name}, {specs})
+ Define custom text objects according to {specs}, and
+ define also utilities to easily share custom text objects as a plugin
+ which name is {plugin-name}.
+
+ {plugin-name} is a string which consists of English alphabets.
+ This name is used various key mappings, Ex commands, and variables.
+
+ {specs} is a |Dictionary| for definitions of custom text objects.
+ See also |textobj-user-specs| for details.
+
+ For example,
+>
+ call textobj#user#define('datetime', {
+ \ 'date': {
+ \ 'pattern': '\<\d\d\d\d-\d\d-\d\d\>',
+ \ 'select': ['ad', 'id'],
+ \ },
+ \ 'time': {
+ \ 'pattern': '\<\d\d:\d\d:\d\d\>',
+ \ 'select': ['at', 'it'],
+ \ },
+ \ })
+<
+ many stuffs are defined with the above definition:
+
+ *:Textobj{Plugin}DefineDefaultKeyMappings*
+ (a) An Ex command :TextobjDatetimeDeineDefaultKeyMappings is defined.
+ The Ex command defines default key mappings for custom text objects,
+ but it doesn't override existing key mappings unless "!" is given.
+
+ In this example, the Ex command maps "ad", "id", "at" and "it" to
+ custom text objects in Operator-pending mode and Visual mode. ({lhs}
+ is also mapped in Select mode if it starts with a non-printable
+ character such as <C-d>)
+
+ *<Plug>(textobj-{plugin}-{object}-{operation})*
+ (b) Interface key mappings such as <Plug>(textobj-datetime-date-a) are
+ defined in Operator-pending mode, Visual mode and Select mode. These
+ key mappings are defined for extra customization for users.
+
+ For example, one might prefer "aT" and "iT" to select a time, because
+ |at| and |it| are bound to the extremely useful text objects by
+ default, and it is usually a bad idea to override them. In this case,
+ interface key mappings are used as follows:
+>
+ xmap aT <Plug>(textobj-datetime-time-a)
+ omap aT <Plug>(textobj-datetime-time-a)
+ xmap iT <Plug>(textobj-datetime-time-i)
+ omap iT <Plug>(textobj-datetime-time-i)
+<
+ *g:textobj_{plugin}_no_default_key_mappings*
+ (c) Finally :TextobjDatetimeDeineDefaultKeyMappings is executed by
+ default to define default key mappings -- "ad", "id", "at" and "it".
+
+ As described in (b), sometimes users do not want to use default key
+ mappings such as "at" and "at". For such users, default key mappings
+ are not defined by this function if a variable
+ g:textobj_datetime_no_default_key_mappings is set to true.
+
+
+ *textobj-user-specs*
+Specification for a text object ~
+
+|textobj#user#define()| takes {specs} for custom text objects. {specs} is
+a |Dictionary|, and it is treated as a sequence of key-value pairs, where key
+is the name of a text object and value is the specification of a text object.
+
+The specification of a text object consists of various properties. Properties
+are expressed as a single dictionary. Each key is the name of a property.
+The following properties are available:
+
+"move-n" {lhs} or [{lhs}, ...]
+ The value must be a string or a list of strings. Each string is
+ treated as a {lhs} of a default key mapping to move the cursor to the
+ next text object.
+
+ A target text object is determined by
+ - the "pattern" property with a single regular expression, or
+ - the "move-n-function" property.
+
+"move-p" {lhs} or [{lhs}, ...]
+"move-N" {lhs} or [{lhs}, ...]
+"move-P" {lhs} or [{lhs}, ...]
+ Like "move-n", but {lhs} is used as a default key mapping 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 {lhs} is used as a default key mapping to select
+ the text object under the cursor. If there is no text object under
+ the cursor, the next text object is selected.
+
+ A target text object is determined by
+ - the "pattern" property with a single regular expression, or
+ - the "select-function" property.
+
+"select-a" {lhs} or [{lhs}, ...]
+"select-i" {lhs} or [{lhs}, ...]
+ Like "select", but {lhs} is used as a default key mapping to select
+ "a" text object or "inner" text object, like |ab|, |ip| and other
+ built-in text objects.
+
+ A target text object is determined by
+ - the "pattern" property with a pair of regular expressions,
+ - the "select-function-a" property, or
+ - the "select-function-i" property.
+
+"pattern" {regexp} or [{regexp}, {regexp}]
+ A single regular expression or a list of two regular expressions to
+ determine a target text object.
+
+ With a single regular expression:
+ A region matched to the regular expression is treated as
+ a target text object.
+
+ With a pair of regular expressions:
+ A region between two parts is treated as a target text object,
+ where the 1st part is matched to the 1st regular expression
+ and the 2nd part is matched to the 2nd regular expression.
+
+"{property}-function" {fname}
+ If this property is defined, the function named {fname} instead of the
+ "pattern" property is used to determine a target text object for
+ a "{property}" operation.
+
+ The function...
+ - Must take no argument, and
+ - Must return a list to denote the region occupied by a target text
+ object, or must return 0 to denote that there is no text object.
+
+ The format of a list a list to denote the region is as follows:
+
+ [region_type, start_position, end_position]
+
+ - "region_type" is a string to denote the type of a region.
+ Valid value Meaning ~
+ --------------------------- ~
+ "v" Characterwise
+ "V" Linewise
+ "\<C-v>" Blockwise
+ - "start_position" denotes the start position of a region.
+ The detail of this value is the same as |getpos()|.
+ - "end_position" is like "start_position", but it denotes the
+ end position of a region.
+
+ See |textobj-user-example-complex| for an example.
+
+"sfile" {string}
+ Value must be expand('<sfile>'). This value is used to
+ calculate <SNR> prefix for script-local functions which are
+ given to "{property}-function".
+
+
+ *textobj-user-migration-from-0.x-to-1.x*
+Migrate from version 0.x to version 1.x ~
+
+The API to define custom text objects is changed.
+Version 0.x uses |textobj#user#plugin()|, while
+version 1.x uses |textobj#user#define()|.
+Usage of both functions are roughly equivalent.
+Details of {specs} are different for both functions.
+To migrate from textobj#user#plugin() to textobj#user#define(),
+replace key names in {specs} according to the following table:
+
+textobj#user#plugin() textobj#user#define() ~
+------------------------------------------------------------------------ ~
+"move-n" Same as before.
+"move-p" Same as before.
+"move-N" Same as before.
+"move-P" Same as before.
+"select" Same as before.
+"select-a" Same as before.
+"select-i" Same as before.
+"*pattern*" "pattern"
+"*no-default-key-mappings*" No longer supported.
+"*{spec}-function*" "{spec}-function"
+"*sfile*" "sfile"
+
+Note that "*no-default-key-mappings*" is no longer supported.
+Because it is not useful and it seems not to be used by anyone.
+Use |g:textobj_{plugin}_no_default_key_mappings|
+to suppress default key mappings.
+
+
+
+
+==============================================================================
+OBSOLETE API *textobj-user-obsolete-api*
+
+ *textobj#user#move()*
+textobj#user#move({pattern}, {flags}, {previous-mode})
+ Note: This function is obsolete. It will be removed in sometime.
+
+ 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})
+ Note: This function is obsolete. It will be removed in sometime.
+
+ 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})
+ Note: This function is obsolete. It will be removed in sometime.
+
+ 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#plugin()*
textobj#user#plugin({plugin}, {obj-specs})
Define key mappings and a command to support writing a plugin which
@@ -211,129 +549,34 @@ textobj#user#plugin({plugin}, {obj-specs})
==============================================================================
-OBSOLETE API *textobj-user-obsolete-api*
-
- *textobj#user#move()*
-textobj#user#move({pattern}, {flags}, {previous-mode})
- Note: This function is obsolete. It will be removed in sometime.
-
- 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})
- Note: This function is obsolete. It will be removed in sometime.
-
- 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})
- Note: This function is obsolete. It will be removed in sometime.
-
- 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})
- Note: This function is obsolete. It will be removed in sometime.
- Use |textobj#user#plugin()| instead.
-
- 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: >
- call textobj#user#define('foo', '', '',
- \ {'move-to-next': 'gj',
- \ 'move-to-prev': 'gk',
- \ 'select': ['ig', 'ag']})
-<
+KNOWN ISSUES *textobj-user-known-issues*
+- Count is not supported to select a text object.
+- Unlike built-in text objects such as |aw|, |ip| and others,
+ visually selected region is not extended by repeating custom text objects.
+- Custom text objects with |o_CTRL-V| may not work properly.
-==============================================================================
-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.
+- See also: https://github.com/kana/vim-textobj-user/issues
==============================================================================
CHANGELOG *textobj-user-changelog*
+1.0.0 2013-03-16T22:48:38+09:00 *textobj-user-changelog-1.0.0*
+ - |textobj#user#define()| is completely rewritten to provide more
+ intuitive interface to define custom text objects as a plugin.
+ Usage of this function is no longer compatible with old versions.
+ It is highly recommended to use textobj#user#define() instead of
+ textobj#user#plugin().
+ - |textobj#user#plugin()| becomes obsolete now.
+ Use |textobj#user#define()| instead.
+ It is not difficult to migrate to new API.
+ See also |textobj-user-migration-from-0.x-to-1.x| for details.
+
0.3.12 2012-01-18T19:34:29+09:00 *textobj-user-changelog-0.3.12*
- |textobj#user#plugin()|: Fix the bug that "*sfile*" is not correctly
interpreted in a Unix-like environment on Microsoft Windows such as

0 comments on commit 4e0f310

Please sign in to comment.