Text objects ​

Text objects are like motions in that they define a range over which an operator may act. Unlike motions, text objects can set both a beginning and an endpoint. In visual state, text objects alter both ends of the selection.

Text objects are not directly usable in normal state. Instead, they are bound in the two keymaps evil-inner-text-ojects-map and evil-outer-text-objects-map, which are available in visual and operator-pending state under the keys i and a respectively.

Emacs Lisp Autofunction: (evil-define-text-object OBJECT (COUNT) DOC [[KEY VALUE]...] BODY...) ​

Define a text object command `OBJECT'. `BODY' should return a range (BEG END) to the right of point if `COUNT' is positive, and to the left of it if negative.

Optional keyword arguments:

  • :type - determines how the range applies after an operator (inclusive, line, block, and exclusive, or a self-defined motion type).
  • :extend-selection - if non-nil (default), the text object always enlarges the current selection. Otherwise, it replaces the current selection.

For eample, this is a text object which selects the next three characters after the current location:

emacs-lisp
(evil-define-text-object foo (count)
  "Select three characters."
  (list (point) (+ 3 (point))))

For convenience, Evil provides several functions returning a list of positions which can be used for defining text objects. All of them follow the convention that a positive `count' selects text after the current location, while negative `count' selects text before it.

> Note: The `thingatpt' library is used quite extensively in Evil to define text objects, and this dependency leaks through in the following functions. A `thing' in this context is any symbol for which there is a function called forward-THING [1] which moves past a number of `things'.

Emacs Lisp Autofunction: (evil-select-inner-object THING BEG END TYPE [COUNT LINE]) ​

Return an inner text object range of `COUNT' objects. If `COUNT' is positive, return objects following point; if `COUNT' is negative, return objects preceding point. If one is unspecified, the other is used with a negative argument. `THING' is a symbol understood by `thing-at-point'. `BEG', `END' and `TYPE' specify the current selection. If `LINE' is non-nil, the text object should be linewise, otherwise it is character wise.

Emacs Lisp Autofunction: (evil-select-an-object THING BEG END TYPE COUNT [LINE]) ​

Return an outer text object range of `COUNT' objects. If `COUNT' is positive, return objects following point; if `COUNT' is negative, return objects preceding point. If one is unspecified, the other is used with a negative argument. `THING' is a symbol understood by `thing-at-point'. `BEG', `END' and `TYPE' specify the current selection. If `LINE' is non-nil, the text object should be linewise, otherwise it is character wise.

Emacs Lisp Autofunction: (evil-select-paren OPEN CLOSE BEG END TYPE COUNT [INCLUSIVE]) ​

Return a range (BEG END) of `COUNT' delimited text objects. `OPEN' and `CLOSE' specify the opening and closing delimiter, respectively. `BEG' `END' `TYPE' are the currently selected (visual) range. If `INCLUSIVE' is non-nil, `OPEN' and `CLOSE' are included in the range; otherwise they are excluded.

The types of `OPEN' and `CLOSE' specify which kind of THING is used for parsing with evil-select-block. If `OPEN' and `CLOSE' are characters evil-up-paren is used. Otherwise `OPEN' and `CLOSE' must be regular expressions and evil-up-block is used.

If the selection is exclusive, whitespace at the end or at the beginning of the selection until the end-of-line or beginning-of-line is ignored.

  1. (1) There are many more ways that a `thing' can be defined, but the definition of forward-THING is perhaps the most straightforward way to go about it. ↩︎