Text Objects

When we write a page of text, that page is typically made up of several paragraphs of text. Each of those paragraphs is made up of several sentences, and finally each of those sentences is made up of words. Likewise when we code, depending on the language we might have blocks of code, chunks of code wrapped in parentheses, etc.

Each of these nouns represents a logical grouping (or object) of text, and Neovim understands (more or less) what each of them are, providing a "higher-level" abstraction that provides some pretty powerful capabilities.

Our goal for the moment is to simply introduce text objects and provide some examples, then we will get into more details about how to work with them shortly.

Words

The first text objects we will review are some of the most common, words. Neovim provides not one, but two definitions for words, and distinguishes between them using the notation "word" and "WORD".

word

A sequence of letters, digits, and underscores, separated by either non-word characters or whitespace.

WORD

A sequence of non-blank characters, separate by whitespace.

To help distinguish between the two definitions consider the following line of text:

one two three-four five/six

• The words in this sentence are:

one, two, three, four, five, and six

• The WORDs in this sentence are:

one, two, three-four, and five/six

From these definitions we can see that (as we might expect) both types of words encompass characters separated by whitespace, where words take a more conservative approach and consider only "word-characters", while WORDs take a more liberal approach and consider most types of characters.

To further demonstrate these two text objects, let's start from the following buffer, and visually-select a word and a WORD:

Note that in Step 1 the word selected the text up to, but not including, the quotation mark. On the other hand, the WORD selected the entire sequence of text, from the start of the line to the space. The ability to choose between word and WORD provides additional flexibility to fine-tune which text is ultimately selected.

Sentences

Sentences are the next higher-order logical chunk of text that we work with, and Neovim is able to identify those as well. In Neovim, a sentence is defined as:

sentence

a sequence of words and WORDs that end with a ".", "!", or '?', followed by either a space, tab, or EOL.

To help demonstrate, let's visually-select a sentence in the following text:

Note that the cursor is initially positioned in the middle of the sentence, then the selected text extends both back to the start of the sentence, as well as forward to the end of the sentence. The content of the sentence additionally consists of both types of word.

Paragraphs

As you might expect, the next logical progression after sentences are paragraphs.

paragraph:

sequences of sentences that begin and end with empty lines.

Let's take a look at paragraph in action:

As with sentences, this example starts with the cursor in the middle of the paragraph, then after selecting the paragraph the selection extends from the start of the paragraph (which is currently not visible), to the end of the paragraph. Text objects do not take into account whether or not the object is visible or not, they are purely concerned with the text itself.

Quotes

Now that we have reviewed the common components of prose, let's look at the remaining text-objects, which allow us to pin-point specific groups of text within sentences and paragraphs, as well as within programming code. In the first example, we look at quotes.

quotes

sequences of text contained within quotes "", ', or `

Quotes are common in prose, as well as in programming languages, so the ability to pin-point those areas of text can be very convenient.

Let's take a look at a few examples to see how these work:

We start with the cursor on the e of I've, then in Step 1 selected the quoted text. Note that Neovim was smart enough to extend past the apostrophe in I've and select the entire quoted chunk of text. In Step 3 we move the cursor to between the two quoted chunks of text, and select again. In this case, Neovim selected all of the text between the two chunks of quoted text. Finally, after moving the cursor into the second chunk of quoted text in Step 4, the text inside of the second chunk of quoted text is selected in Step 5.

Blocks

In many ways blocks extend the concept of quotes. Just as specific chunks of text can be surrounded by quotation marks, they can also be surrounded by parentheses, brackets, etc. In Neovim, these section are called blocks:

block

sequences of text contained within {}, [], <>, or ()

While parenthesis are common in prose, the various types of brackets are common in programming language, and convey different meanings depending on the language. In any case, Neovim has the ability to isolate those blocks of text. As a simple example, let's look at the following snippet of Python code:

In this example, the cursor starts at the top of the buffer, which contains the opening bracket [. In Step 1 we instruct Neovim to select the contents of that block with the command vi[. Similar operations can be use to work with each of the other types of blocks.

Tags

Finally, Neovim defines an additional text-object, which comes in handy when working with XML or HTML tags.

Let's take a quick look:

In this example, the cursor starts on a line containing an HTML tag, and the tag text-object allows us to quickly move the cursor inside the tag and select the associated text, which can be very convenient when working with these types of files. As mentioned previously we also had the option to select the text around the tag, as demonstrated in Step 2.

This section was intended to provide just an introduction to the concept of text-objects, to provide useful background as we continue to learn the fundamentals of Neovim. If you would like to learn more about working with text objects, jump forward to our text objects section.