plugins.md

Internals

In order to understand how plugins can add new targets sources, lets first have a look at how targets.vim works internally.

The basic flow works like this:

• Each source can be used to create a factory for a given set of args.
• A factory can be used to create generators of different type. Possible types are current (target around cursor), next (target after cursor) and last (target before cursor). A new generator is usually created per invocation (the last generator will be reused if possible, for example for growing and skipping)
• A generator can be called multiple times to generate a list of targets. For example the generator for current targets should return the smallest targets closest to the cursor on the first call, the next bigger one on the next call and so on. The generator for next targets should first return the first next target (closest to the cursor, but to the right/below of the cursor), the next call should return the second closest of that type etc. If no more targets are available, because there are no enclosing ones any more, or the end of file is reached, a generator can indicate that by returning an error (pseudo) target which will be handled accordingly.

For example, lets see what happens when you type d2inq to delete in the second next quote:

• Vim will parse the typed character d and remember that as operator func to be used later.
• Vim will parse 2 and recognize it as count, accessed by targets.vim later.
• Vim will parse i in operator pending mode and find find and execute the expression mapping from targets.vim.
• targets#e() gets called with a parameter telling it that i was typed, which we remember as modifier for later use. It then continues reading characters until the command is complete or when it recognizes that no such target is set up. In our case it reads the n which is recognized as which (which is either c (current), n (next) or l (last)). Finally it reads q which it recognizes as trigger.
• targets.vim uses the trigger to look up sources from its internal mappings. For trigger q it finds a single source quote with three sets of arguments. It looks up the source quote to find a factory constructor and uses it to create three quote factories, one for single quotes, one fore double quotes and one for backticks. (unless they were already cached by the trigger q).
• targets.vim takes uses three factories to one generator each. Here we use the which value of n to get three generators, one to find next double quote targets, one for next single quote targets and one for next backtick targets.
• targets.vim create a multi generator out of those three generators. Since we had a count of 2, this multi gen will be called two times. On the first call it calls each internal generator once to get three next quote targets of the respective kind. It compares them to pick the best one (according to g:targets_seekRanges). This would have been the first next quote target, but is discarded because we asked for the second. On the second call the internal generator which yielded the first best target gets called again, to produce the second best of that kind. This one gets compared with the first best targets from the other internal generators from earlier, to be declared the best of this round, which in turn is our second next best quote target we've asked for.
• targets.vim apply the proper modify function, depending on the modifier value and the source.

While mappings can use multiple sources and multiple args per source to create any multi targets, most triggers are mapped to a single source with a single set of args. However, the multi generator approach is still being used for all of them to support seeking. For example, if type ci), we get a single factory for () pair targets, but we use it to get all three generators for current, next and last pair. Then we use a multi generator to pick the best available target. Depending on the seek ranges again, usually this will be the target around the cursor if available. But if that one doesn't exist, it automatically switches to the next or last one, depending on which one is deemed better

Plugins

It's possible to extend targets.vim by adding new sources. Text objects implemented as targets.vim plugin will automatically gain all the functionality of the built in ones. Most notably you can use n and l to select next and last one, provide counts to pick a specific one, use seeking (vix pick current, next or last), growing (vixix is the same as v2ix etc.) and skipping vinxinx is the same as v2inx).

The basic steps are:

1. Register your new source: Map source name to factory constructor function.
2. Optionally add some default mappings: Map trigger to your source with some args.
3. Implement the factory constructor: This declares generator functions (all three required) and modify functions (optional).
4. Implement the generator functions: These functions might be called multiple times and should yield more and more distant targets on each call.
5. Implement modify functions: These functions take a target and a modifier (i, a, I or A) and should return the modified target. The ones used by targets.vim internally are available for external use. These include basic white space handling.

An example source with comments is implemented in line-targets.vim. Please have a look at that repository to see how such an implementation can be organized.