OccurrenceModifier

v0.55.0 is big feature enhancement.
So I will quickly explain part of it to encourage user to use these new feature.

Most of the new features introduced in v0.55.0 are somewhat related or based on occurrence operator-modifier.
So reading this test spec will also help to understand these features.

• Occurrence operator-modifier
• [Experimental] Keystroke sugar introduced from v0.57.0, v0.58.0
  • What o does?
  • Normal operation vs occurrence-modified operation.
• Select/change occurrence have special support in visual-mode and in incremental-search-input
  • Select occurrence
  • Change occurrence
  • Supplemental explanation

Occurrence operator-modifier

When you type o in operator-pending-mode, you can modify existing operator to behave differently.

[Experimental] Keystroke sugar introduced from v0.57.0, v0.58.0

Following keymap are available.
So you can use c o p and d o f rather than c o i p and d o a f.

Sugar	Equivalent	Example
o p	o i p	d o p delete all occurs in inner-paragraph
o f	o a f	c o f change all occurs in a-function
o l	o i l	c o l change all occurs in inner-current-line
o z	o a z	g U o z uppercases all occurs in a-fold
o r	o a r	d o r delete all occurs in a-range-marker
o v	o i v	d o v delete all occurs in a-visible-area

o v is added from v0.58.0

What o does?

• o is operator modifier.

• The command name of o is operator-modifier-occurrence.

• What's this? what operator-modifier?

• Operator-modifier is command available in operator-pending-mode and is used to modify existing operator's behavior to behave differently.

• Well known operator-modifier is v and V which forces operator's wise(linewise, charcterwise).

  • d j delete two line, but d v j delete same char as when you did v j d.
    • So you modified d to behave characterwise by v modifier.
  • d l delete right char only, but d V j delete whole line(same range as you did d d).
    • So you modified d to behave linewise by V modifier.

• So what o does?

• What o does is to instruct operator to re-select occurrence of cursor word from target range just after target selected but before applying operator to target.

Normal operation vs occurrence-modified operation.

g U i p uppercases all text in a paragraph, g U o i p uppercases all occurrences of cursor-word in a paragraph.

c i p change whole paragraph, c o i p change occurrence of cursor word in paragraph.

What is happening under the hood.

Vim's text editing operation is consists of operator and its target(motion or text-object).
Operator is command to instruct do something such as delete, change, uppercase, surround etc.
Target is command to specify to what such as here-to-end-of-line, paragraph, inner-parenthesis, inner-word etc.

• Operator: g U is upper-case operator, c is change operator.
• Target: i p is inner-paragraph text-object used as operator target.
• Operator modifier: o instruct re-select occurrence of cursor word within target.

When user type i p, paragraph is selected internally then apply g U or c to that selected text.
But when o modifier is used, before applying operator to selected paragraph, it scan occurrence of cursor word from selected range(paragraph) then re-select found words.
So, instead of directly applying operator to whole paragraph, operator is applied to those re-selected words.

Select/change occurrence have special support in visual-mode and in incremental-search-input

Off course o modifier is available for all operators in vim-mode-plus.
But keystroke is a bit complex and might be confusing for many user.
And I believe most frequent use-case of occurrence operation is select-occurrence and change-occurrence.
So vim-mode-plus provides accessible keybindings for those commands and also have special support in visual-mode and incremental-search-input.

Select occurrence

Mode	Keybind	Description
normal	g cmd-d	Select occur of cursor word in specific target
visual.is-narrowed	cmd-d	Select occur of cursor word in selection.
incseach-input	cmd-d	Select occur of search word in target

Change occurrence

Mode	Keybind	Description
normal	c o	Change occur of cursor word in specified target
visual.is-narrowed	ctrl-cmd-c	Change occur of cursor word in selection.
incseach-input	ctrl-cmd-c	Change occur of search word in target

c o above is just a change operation with occurrence(o) modifier.
So nothing special, but put here for consistency.

Supplemental explanation

What's visual-mode.is-narrowed?

When selection is multi-line(not single-line) in visual-mode, vim-mode-plus automatically sets an is-narrowed css class on editorElement(view part of text-editor).

In visual-mode.charcterwise mode, selection is auto-extended to end of cursor word

As long as cursor word is starting from inner-selection, that word is treated as occurrence.

Special behavior for incsearch-input

When ctrl-d, or ctrl-cmd-c is executed from incsearch-input, it tries to auto-set the target by following priority.

1. In visual-mode use current selection as target.
2. If there is range-marker then use it as target.
3. None of above match, then enter operator-pending state to get target from user.