OccurrenceModifier

Isaac edited this page Jul 14, 2017 · 3 revisions

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

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.

gUip-vs-gUoip

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

cip-vs-coip

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

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

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.