README.md

vim-textobj-user - Create your own text objects

vim-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 simple text objects, or use functions to define complex ones.

Examples

Simple text objects defined by a pattern

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#plugin('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'],
\   },
\ })

Simple text objects surrounded by a pair of patterns

Define aP to select a PHP code with <?php and ?>, and define iP to select a PHP code without <?php and ?>:

call textobj#user#plugin('php', {
\   'code': {
\     'pattern': ['<?php\>', '?>'],
\     'select-a': 'aP',
\     'select-i': 'iP',
\   },
\ })

Complex text objects defined by functions

Define al to select the current line, and define il to select the current line without indentation:

call textobj#user#plugin('line', {
\   '-': {
\     'select-a-function': 'CurrentLineA',
\     'select-a': 'al',
\     'select-i-function': 'CurrentLineI',
\     'select-i': 'il',
\   },
\ })

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

Further reading

You can define your own text objects like the above examples. See also the reference manual for more details.

There are many text objects written with vim-textobj-user. If you want to find useful ones, or to know how they are implemented, see a list of text objects implemented with vim-textobj-user.