https://github.com/paradigm/TextObjectify

TextObjectify is a Vim plugin which improves text-objects
https://github.com/paradigm/TextObjectify

Last synced: 2 months ago
JSON representation

TextObjectify is a Vim plugin which improves text-objects

• Host: GitHub
• URL: https://github.com/paradigm/TextObjectify
• Owner: paradigm
• Created: 2013-04-06T22:02:39.000Z (almost 12 years ago)
• Default Branch: master
• Last Pushed: 2013-11-13T19:13:05.000Z (about 11 years ago)
• Last Synced: 2024-08-01T16:44:13.046Z (5 months ago)
• Language: VimL
• Size: 151 KB
• Stars: 100
• Watchers: 2
• Forks: 6
• Open Issues: 8
• Metadata Files:
  • Readme: README.md

Awesome Lists containing this project

• my-awesome-github-stars - paradigm/TextObjectify - TextObjectify is a Vim plugin which improves text-objects (Vim Script)

README

        
TextObjectify

=============

Description

-----------

Vim's text-objects are an extremely powerful tool.  However, there are some

peculiar lackings in how they operate out-of-the-box.  The TextObjectify plugin

attempts to rectify these peculiarities as well as add the ability to allow the

user to create custom text-objects or even create text-objects on-the-fly

if a object is provided that does not already exist.

The peculiarities that TextObjectify attempts to resolve have to do with the

mutually-exclusive functionality of the parenthesis-like text-objects and the

quote-like text-objects.  The parenthesis-like text-objects are all able to

operate on objects that cover multiple lines; however, the cursor must be

on/within the object for it to work.  The quote-like text-objects only work

on a single line.  However, with the quote-like text-objects, the cursor will

seek ahead and jump to a text object if the cursor is not already within one.

For example, consider a buffer that contains nothing but the following:

    """

    some example code.

    section is multiple lines

    """

    if (getinput() == "yes") {

        print "this is an example"

        counter += 1

    }

If the cursor is on the `p` in `print` and the user types

    vi{

The area between the { and } characters will be selected.  However, if the

cursor is on the `s` in `some` and the user types

    vi"

nothing will happen, because quote-like text-objects do not work on multiple

lines.  With TextObjectify, the two lines between the triple quote sets will be

selected - the parenthesis-style text-object functionality will apply.

If the cursor is on the `p` in `print` and the user types

    vi"

the string `this is an example` will be selected, because quote-style

text-objects seek forward on the same line when looking for an object.

However, if the cursor is on the `i` in `if` and the user types

    vi(

nothing will happen, because parenthesis-like text-objects do not seek if

they are not in already within a text-object.  With TextObjectify, the region

between the parenthesis will be selected.

In addition to improving how existing text-objects function, TextObjectify

allows user to create custom text-objects.  To serve as examples,

TextObjectify comes with two custom text objects: `` will operate over the

entire buffer and `V` will operate over a block of viml.  With default

TextObjectify, if a user types

    "+ya

the entire buffer will be stored within the quoteplus register.

Consider a buffer that contains the following:

    if nr2char(getchar()) == g:quitmap

        echo "Quitting example"

        return 0

    endif

If the cursor is on any of the lines shown and the user enters `viV`, the

`echo` and `return` lines will be selected.

Moreover, TextObjectify has the ability to create text-objects on-the-fly if

an object is requested that is not provided by Vim out of the box and is not

one of TextObjectify's custom text objects.  Whatever character is provided

becomes the delimiter for either side.  For example, if the buffer contains the

following:

    LaTeX documents can show colors such as red, blue, green, and yellow.

    Additionally, they can show pretty mathematics such as $\int x^2dx$.

If the user would like to select an area between commas, there is no need to

plan ahead and create such a custom text-object.  The user can simply enter

"vi," and TextObjectify will create a text-object with commas as delimiters

on either side.  Similarly, the user could type "ci$" to change the area

between the dollar signs without having to create a custom text-object ahead

of time.

Setup

-----

TextObjectify can be installed like most other Vim plugins.  On a Unixy system

without a plugin manager, the textobjectify.vim file should be located at:

    ~/.vim/plugin/textobjectify.vim

On a Unixy system with pathogen, the textobjectify.vim file should be located at:

    ~/.vim/bundle/textobjectify/plugin/textobjectify.vim

On a Windows system without a plugin manager, the textobjectify.vim file should be located at:

    %USERPROFILE%\vimfiles\plugin\textobjectify.vim

On a Windows system with pathogen, the textobjectify.vim file should be located at:

    %USERPROFILE%\vimfiles\bundle\textobjectify\plugin\textobjectify.vim

If you are using a plugin manager other than pathogen, see its documentation

for how to install TextObjectify - it should be comparable to other plugins.

If you would like the documentation to also be installed, include textobjectify.txt

into the relevant directory described above, replacing `plugin` with `doc`.

TextObjectify should have same defaults and be useful without any additional

configuration.  However, to get the most out of TextObjectify, it is

recommended that you configure it to your own tastes.

Configuration

-------------

There are a handful of global variables which can be set to tweak how

TextObjectify operates.  The main one is g:textobjectify which contains

information on how to treat all custom text-objects or modifications of

existing text-objects.  The others tweak how on-the-fly text-objects

function.

All TextObjectify objects have the following attributes:

- 'left':  Regex for the left delimiter

- 'right': Regex for the right delimiter

- 'same':  Set to 1 to have object prioritize same-line objects over multi-line

  objects.  That is, if the situation is ambiguous, act like quote-like

  text-objects normally do.  Otherwise, set to 0 to have the object act like

  parenthesis-like text-objects normally do.

- 'seek': Sets whether or not to search for a text-object if the cursor is

  not already within one.  if 'seek' is 0, no seeking is done, i.e., if the

  cursor is not already within the text-object abort.  if 'seek' is 1, search

  forward for a text-object if the cursor is not already in one.  If 'seek'

  is 2, search backward for a text-object if the cursor is not already in

  one.  The parenthesis-style text-objects come in pairs - TextObjectify

  defaults to having the left item of the pairs search forward and the right

  item search backwards.

- 'line': If set to '1', it will force the object to act as though it is

  selected linewise.  The `V` text-object which TextObjectify comes with acts

  this way.

g:textobjectify is a Dictionary.  Each key is the character which is used

to select the object.  The values are Dictionaries with the above five

attributes.  For example, the default g:textobjectify is:

    let g:textobjectify = {

                \'(': {'left': '(', 'right': ')', 'same': 0, 'seek': 1, 'line': 0},

                \')': {'left': '(', 'right': ')', 'same': 0, 'seek': 2, 'line': 0},

                \'{': {'left': '{', 'right': '}', 'same': 0, 'seek': 1, 'line': 0},

                \'}': {'left': '{', 'right': '}', 'same': 0, 'seek': 2, 'line': 0},

                \'[': {'left': '\[', 'right': '\]', 'same': 0, 'seek': 1, 'line': 0},

                \']': {'left': '\[', 'right': '\]', 'same': 0, 'seek': 2, 'line': 0},

                \'<': {'left': '<', 'right': '>', 'same': 0, 'seek': 1, 'line': 0},

                \'>': {'left': '<', 'right': '>', 'same': 0, 'seek': 2, 'line': 0},

                \'"': {'left': '"', 'right': '"', 'same': 1, 'seek': 1, 'line': 0},

                \"'": {'left': "'", 'right': "'", 'same': 1, 'seek': 1, 'line': 0},

                \'`': {'left': '`', 'right': '`', 'same': 1, 'seek': 1, 'line': 0},

                \'V': {'left': '^\s*\(if\|for\|function\|try\|while\)\>',

                    \'right': '^\s*end', 'same': 0, 'seek': 1, 'line': 1},

                \"\": {'left': '\%^', 'right': '\%$', 'same': 0, 'seek': 0,

                \'line': 0},

                \}

This sets how the parenthesis-like text-objects, the quote-like

text-objects, and the two new text-objects operate.  This is a good

reference if you want to make your own.

To create modify or create a new text-object, copy the above lines into your

vimrc and adjust accordingly.  Note that if you create a g:textobjectify in

your vimrc it overwrites all of TextObjectify's default values.  Thus if you

create an empty g:textobjectify all objects default will act as they would

without TextObjectify installed - quote-like text-objects will not act on

multiple lines, etc.

By default, TextObjectify will create new text-objects on-the-fly if a

mapping is called that does not correspond to an existing text-object (either

one of Vim's defaults or one provided by TextObjectify).  To disable this, set

g:textobjectify_onthefly to 0.

The 'same', 'seek' and 'line' attributes of on-the-fly text-objects can be

customized by setting the g:textobjectify_onthefly_same,

g:textobjectify_onthefly_seek, and g:textobjectify_onthefly_line variables

to the desired value.  Otherwise, they default to 0, 1, and 0, respectively.

Changelog

---------

0.1 (2013-04-06):

 - initial release