Targets.vim

Introduction

Targets.vim is a Vim plugin that adds various [text objects][textobjects] to give you more targets to [operate][operator] on. It expands on the idea of simple commands like di' (delete inside the single quotes around the cursor) to give you more opportunities to craft powerful commands that can be [repeated][repeat] reliably. One major goal is to handle all corner cases correctly.

Table of Contents

<details> <summary>Click here to show.</summary> <!-- BEGIN-MARKDOWN-TOC -->

• Installation
• Examples
• Overview
  • Pair Text Objects
    • In Pair
    • A Pair
    • Inside Pair
    • Around Pair
    • Next and Last Pair
    • Pair Seek
  • Quote Text Objects
    • In Quote
    • A Quote
    • Inside Quote
    • Around Quote
    • Next and Last Quote
    • Quote Seek
  • Separator Text Objects
    • In Separator
    • A Separator
    • Inside Separator
    • Around Separator
    • Next and Last Separator
    • Separator Seek
  • Argument Text Objects
    • In Argument
    • An Argument
    • Inside Argument
    • Around Argument
    • Next and Last Argument
    • Argument Seek
  • Multi Text Objects
    • Any Block
    • Any Quote
• Settings
  • g:targets_aiAI
  • g:targets_mapped_aiAI
  • g:targets_nl
  • g:targets_seekRanges
  • g:targets_jumpRanges
  • g:targets_gracious
  • targets#mappings#extend
• Notes
• Issues
• Todos

</details> <!-- END-MARKDOWN-TOC -->

Installation

| Plugin Manager | Command | |------------------------|-------------------------------------------------------------------------------| | [NeoBundle][neobundle] | NeoBundle 'wellle/targets.vim' | | [Vundle][vundle] | Bundle 'wellle/targets.vim' | | [Vim-plug][vim-plug] | Plug 'wellle/targets.vim' | | [Pathogen][pathogen] | git clone git://github.com/wellle/targets.vim.git ~/.vim/bundle/targets.vim | | [Dein][dein] | call dein#add('wellle/targets.vim') |

Examples

The following examples are displayed as three lines each. The top line denotes cursor positions from where the presented command works. The middle line shows the contents of the example line that we're working on. The last line shows the part of the line that the command will operate on.

To change the text in the next pair of parentheses, use the cin) command

cursor position │    .....................
buffer line     │    This is example text (with a pair of parentheses).
selection       │                          └───────── cin) ─────────┘

To delete the item in a comma separated list under the cursor, use da,

cursor position │                                  .........
buffer line     │    Shopping list: oranges, apples, bananas, tomatoes
selection       │                                  └─ da, ─┘

Notice how the selection includes exactly one of the surrounding commas to leave a proper comma separated list behind.

Overview

Targets.vim comes with five kinds for text objects:

• Pair text objects
• Quote text objects
• Separator text objects
• Argument text objects
• Tag text objects

Each of those kinds is implemented by a targets source. Third party plugins can provide additional sources to add even more text objects which behave like the built in ones. See [plugins][Plugins] for details on how to implement your own targets source.

Pair Text Objects

These text objects are similar to the built in text objects such as i). Supported trigger characters:

• ( ) (work on parentheses)
• { } B (work on curly braces)
• [ ] (work on square brackets)
• < > (work on angle brackets)
• t (work on tags)

Pair text objects work over multiple lines and support seeking. See below for details about seeking.

The following examples will use parentheses, but they all work for each listed trigger character accordingly.

In Pair

i( i) i{ i} iB i[ i] i< i> it

• Select inside of pair characters.
• This overrides Vim's default text object to allow seeking for the next pair in the current line to the right or left when the cursor is not inside a pair. This behavior is similar to Vim's seeking behavior of di' when not inside of quotes, but it works both ways.
• Accepts a count to select multiple blocks.

      ............
a ( b ( cccccccc ) d ) e
   │   └── i) ──┘   │
   └───── 2i) ──────┘

A Pair

a( a) a{ a} aB a[ a] a< a> at

• Select a pair including pair characters.
• Overrides Vim's default text object to allow seeking.
• Accepts a count.

      ............
a ( b ( cccccccc ) d ) e
  │   └─── a) ───┘   │
  └────── 2a) ───────┘

Inside Pair

I( I) I{ I} IB I[ I] I< I> It

• Select contents of pair characters.
• Like inside of parentheses, but exclude whitespace at both ends. Useful for changing contents while preserving spacing.
• Accepts a count.

      ............
a ( b ( cccccccc ) d ) e
    │   └─ I) ─┘   │
    └──── 2I) ─────┘

Around Pair

A( A) A{ A} AB A[ A] A< A> At

• Select around pair characters.
• Like a pair, but include whitespace at one side of the pair. Prefers to select trailing whitespace, falls back to select leading whitespace.
• Accepts a count.

      ............
a ( b ( cccccccc ) d ) e
  │   └─── A) ────┘   │
  └────── 2A) ────────┘

Next and Last Pair

in( an( In( An( il( al( Il( Al( ...

Work directly on distant pairs without moving there separately.

All the above pair text objects can be shifted to the next pair by including the letter n. The command in) selects inside of the next pair. Use the letter l instead to work on the previous (last) pair. Uses a count to skip multiple pairs. Skipping works over multiple lines.

See our [Cheat Sheet][cheatsheet] for two charts summarizing all pair mappings.

Pair Seek

If any of the normal pair commands (not containing n or l) is executed when the cursor is not positioned inside a pair, it seeks for pairs before or after the cursor by searching for the appropriate delimiter on the current line. This is similar to using the explicit version containing n or l, but in only seeks on the current line.

Quote Text Objects

These text objects are similar to the built in text objects such as i'. Supported trigger characters:

• ' (work on single quotes)
• " (work on double quotes)
• ` (work on back ticks)

These quote text objects try to be smarter than the default ones. They count the quotation marks from the beginning of the line to decide which of these are the beginning of a quote and which ones are the end.

If you type ci" on the , in the example below, it will automatically skip and change world instead of changing , between hello and world.

buffer │ join("hello", "world")
proper │      └─────┘  └─────┘
false  │            └──┘

Quote text objects work over multiple lines and support seeking. See below for details about seeking.

The following examples will use single quotes, but they all work for each mentioned separator character accordingly.

In Quote

i' i" i`

• Select inside quote.
• This overrides Vim's default text object to allow seeking in both directions.

  ............
a ' bbbbbbbb ' c ' d ' e
   └── i' ──┘

A Quote

a' a" a`

• Select a quote.
• This overrides Vim's default text object to support seeking.
• Unlike Vim's quote text objects, this incudes no surrounding whitespace.

  ............
a ' bbbbbbbb ' c ' d ' e
  └─── a' ───┘

Inside Quote

I' I" I`

• Select contents of a quote.
• Like inside quote, but exclude whitespace at both ends. Useful for changing contents while preserving spacing.

  ............
a ' bbbbbbbb ' c ' d ' e
    └─ I' ─┘

Around Quote

A' A" A`

• Select around a quote.
• Like a quote, but include whitespace in one direction. Prefers to select trailing whitespace, falls back to select leading whitespace.

  ............
a ' bbbbbbbb ' c ' d ' e
  └─── A' ────┘

Next and Last Quote

in' In' An' il' Il' Al' ...

Work directly on distant quotes without moving there separately.

All the above pair text objects can be shifted to the next quote by including the letter n. The command in' selects inside of the next single quotes. Use the letter l instead to work on the previous (last) quote. Uses a count to skip multiple quotation characters.

See our [Cheat Sheet][cheatsheet] for a chart summarizing all quote mappings.

Quote Seek

If any of the normal quote commands (not containing n or l) is executed when the cursor is not positioned inside a quote, it seeks for quotes before or after the cursor by searching for the appropriate delimiter on the current line. This is similar to using the explicit version containing n or l.

Separator Text Objects

These text objects are based on single separator characters like the comma in one of our examples above. The text between two instances of the separator character can be operated on with these