There's a lot of undocumented options for patterns…

[evantravers]

Finally taking some time to dive into this wonderful plugin…

What does synchro do? What's the difference between action and kind? What does match_syntax do?

[machakann]

Sorry for my late response.

Let me explain in arbitrary order.

[machakann]

First, I try to answer for the second question. This plugin provides three "kind"s of operators and two "kind"s of text-objects.

• operator

  • add
  • delete
  • replace

• text-object

  • auto
  • query

The kind option is to filter recipes by the kind of those pure text-objects and/or operators. However, note that the keymappings to delete (sd) and to replace (sr) are a little special.

Generally speaking, a text-object only specifies a region on the buffer and an operator only edits the region specified by a text-object (or a motion).

From this aspect, the keymapping to delete and to replace are neither a pure operator nor a pure textobject. To delete or replace, it would be useful if a keymapping does both things what text-object and operator do, that is, find a surrounded region and edit it, as surround.vim plugin does.

For example, when you type sd' (or you may like ds'), it searches the nearest surrounded text by single quotes and deletes the quotes at both edges. Here, the searching is the task of text-objects while deleting quotes is the task of operator. The sandwich.vim make this behavior by combining operator-delete and a text-object, either textobj-auto for sdb or textobj-query for sd + {input}. Therefore, users should note that the corresponding textobject should be listed in kind option of the recipe if one wants to delete or replace it.

[machakann]

action is very similar to kind option, but works different for the keymapping to replace.

sa just add a pair of surroundings and sd just delete, however sr actually does both. The key sequence sr([ works like this.

(foo)

• First, delete ()

foo

• Next, add []

[foo]

The first step should work like sd and the second step should work like sa, but kind option cannot differentiate each step even if someone wants to make independent recipes. action option was introduced to solve the problem.

The textobjects are included in delete because of the reason described in the explanation of kind filter.

[machakann]

The synchro option relates to the keymappings to delete and to replace.

At the early development stage of this plugin, the operators and the textobjects were implemented completely independent. It worked but not very efficient; when a user uses sdb, textobject-auto scans all recipes to search the nearest surroundings and then operator-delete scans all recipes again to check if any one matches to the specified region. synchro option is to force the operator to use the recipe matched in the textobject-auto.

• sdb without synchro

  1. textobj-auto scans recipe1, recipe2, recipe3..., and find the nearest recipeN
  2. operator-delete scans recipe1, recipe2, recipe3..., and find the match with recipeN to delete it

• sdb with synchro

  1. textobj-auto scans recipe1, recipe2, recipe3..., and find the nearest recipeN
  2. textobj-auto notifies operator-delete that the recipeN is matched
  3. operator-delete use recipeN to delete it

The synchro option was implemented later; it has included some problems at that time, but they were all solved now. Thus, this option defaults true. I think users don't need to mind about this option anymore and I am going to delete from the document in the future.

[machakann]

The match_syntax option is a trial to make the matching more accurate. For example, there are four surrounded texts.

The first one is a surrounded text, but the double quotes (") will be deleted only if match_syntax is 0 because the syntax coloring is not matched.

In the second case, the syntax coloring of double quotes are the same but "f" and "o" are not the same. Thus the double quotes will be deleted if match_syntax is equal to or less than 1. It match_syntax is larger than 1, the color of the text inside also checked.

The case match_syntax equals 2 is the strictest case. The color of double quotes and a character inside at both edges should be all the same.

The case match_syntax equals 3 is similar to 2 but it allows the case shown, the double quotes and a character inside at both edges are checked separately.

Recently, I found that this option is too strict even if it is 1, since the syntax coloring is frequently broken with incomplete texts in editing.

[evantravers]

I'm about to read this with a vigor… but thank you so much for the incredible response. I'll try to repay you with a documentation PR if I can understand it correctly.

[machakann]

Thank you.

I cannot take time these days but I have recognized that the document is messy. So, thank you again and looking forward to seeing your PR!

[evantravers]

This is the most detailed response to a ticket I have seen in a long time, thank you @machakann.

This makes a lot more sense, I'm going to think about how it can be simplified or explained for the docs.