What's the difference between a text object and a motion?

Question

I've been using vim for a while and consider myself moderately proficient. I've also built custom text objects, primarily using the fantastic vim-textobj-user rather than natively, as well as using many of the text objects others have built in plugins, and of course built-in text objects and motions.

However, I'm still not clear on the real difference between a text object and a motion. (I think this question is of limited practical importance, but I'm interested anyway). If I hit w, I obviously navigate by words (motion), and if I hit yw, I yank to the end of where that motion would have gone (text object?). However, some text objects (e.g. ip, for inside paragraph) do not work as motions by themselves. In fact, most don't, in my experience. The paragraph motion (}) is a totally unrelated keybinding from ip or ap. In the :operator documentation, vim talks about using motions after operators, but there is no mention there of text objects. Confusingly, there is also a section called :object-motions, which refers to "Text Object Motions"!

So what's the difference? Are they actually related, or is Vim itself just built so some (but not all) of the inbuilt text objects also work as motions through deliberately-chosen identical key bindings? I clearly cannot always use a text object as a motion (try typing ip in normal mode), but it seems I can always use a motion as a text object (y} works as expected). Are text objects a subset of motions?

Answer 1

You've described most of the differences yourself.

The one thing you didn't note specifically is that motions move the cursor in a single direction, whereas text objects are bi-directional: they define an area that expands in both directions from the cursor. (This also makes it clear why a text object can't work as a motion by themselves: they cannot move the cursor in both directions, so what would they do?)

The other thing to realise is that both motions and text objects are conceptual groupings of behaviours (at least, I believe this is the case): they're not actually implemented in an object-oriented way where all the code for motions is in one place, and all the code for text objects is in this other place. I believe under the hood the actual implementation is actually closer to a bunch of ad hoc operator-pending, visual, (and for motions, normal) mode mappings.

So if it helps you to think of motions as being a subset of text objects (or vice versa?), feel free to do so!

Answer 2

I take them as "completely different things".

Just w is a normal mode command/mapping. But after you press y you get into operator-pending mode. So w from yw fully belongs to that mode. And they can be (although shouldn't be) remapped to do something else independently.

This is the same as "normal" y vs. "visual" y. Both are referred as simply "yank", but they are different "yanks"!

So mode is they key. Roughly speaking, "a motion" is something working by default in "normal", "visual" and "operator-pending" modes. "A text object" is the thing which works only in the "visual" and "operator-pending", but not "normal" mode.

Answer 3

A text object is a defined portion of text.

Thus, operations you apply to them can be triggered on them (when basically you are inside this object), and as you pointed they have and inside and outside.

Motions behave differently, in the sense that they are triggered from your cursor position, to where your motion points.

The relation between them is obvious : you will probably use motions to define your own text objects (example in this thread).

Answer 4

I believe it is worth mentioning the plugins: targets.vim, vim-easymotion, vim-paraglide.