Re: Questions about completion matchers

[Marlon Richert <marlon.richert@xxxxxxxxx>]

On Sun, Oct 10, 2021 at 1:40 AM Bart Schaefer <schaefer@xxxxxxxxxxxxxxxx> wrote:
>
> On Sat, Oct 9, 2021 at 3:12 PM Marlon Richert <marlon.richert@xxxxxxxxx> wrote:
> >
> > On Sat, Oct 9, 2021 at 7:23 PM Bart Schaefer <schaefer@xxxxxxxxxxxxxxxx> wrote:
> > >
> > > *             l:|$lpat=$tpat -> [[ $trial = *${~lpat}* ]] &&
> > > ${word/#$~lpat/$~tpat}
> >
> > Perhaps I'm mistaken, but aren't you mixing up $lpat and $lanchor
> > here?
>
> Well, sort of, yes.  See Oliver's more recent message.  A better
> description of what's happening is that the matcher transforms the
> word from the command line into a pattern, and then that pattern is
> compared to every one of the trial candidates, and then pieces of the
> trial candidates are extracted and merged with the word from the
> command line to generate the list of possible replacements for that
> word.  It's never as simple as a string substitution on the word
> itself taken directly from the patterns in the matcher.

Having an explanation like this in the docs would help so much! :)

Or what would help even more is to put it in a step-by-step form. For example:

> 1. Each matcher generates a search pattern by taking the word on the command line (or the pattern produced by the previous matcher) and applying a transformation specific to the matcher. If the matcher has an uppercase letter, it also captures the original substrings of the command line word that it transformed.
> 2. After all matchers are applied, the resulting search pattern is used to find matching completions.
> 3. For each uppercase matcher, substrings captured from the word on the command line are then inserted into the matching completions.

And then each matcher could state exactly how it produces its search
pattern. For example:

> r:lanchor||ranchor=tpat
> l:lanchor||ranchor=tpat
>
> 1. Find each substring in the word on the command line that matches pattern ranchor (for r:) or lanchor (for l:). If this anchor is empty, it matches the end (for r:) or the beginning (for l:) of the word on the command line.
> 2. Insert a pattern to the left (for r:) or right (for l:) of each substring:
>    * If tpat is **, then insert `*lanchor` (for r:) or `ranchor*` (for l:).
>    * Otherwise, insert `(tpat~*lanchor*)lanchor` (for r:) or `ranchor(tpat~*ranchor*)` (for l:).
>
> Example: If the word on the command line is `H2`, then the match spec r:[[:lower:]]|[[:upper:][:digit:]]=** captures the substrings 'H' and '2' and generates the search pattern `*[[:lower:]]H*[[:lower:]]2`.


On Sun, Oct 10, 2021 at 1:40 AM Bart Schaefer <schaefer@xxxxxxxxxxxxxxxx> wrote:
>
> On Sat, Oct 9, 2021 at 3:12 PM Marlon Richert <marlon.richert@xxxxxxxxx> wrote:
> >
> > How about changing the docs to just literally state the transformation
> > that each matcher applies?
>
> Because it's not a literal transformation.  Matchers don't transform,
> they create a comparison between the command line and the compadd
> strings and define which parts of the command line can be replaced by
> what parts of the compadd strings when that comparison finds a match.

Perhaps "transformation" is not the word I should've used. What I
meant is that each matcher generates a pattern, using as input the
word on the command line or the pattern generated by the previous
matcher. After this has been done in turn for each matcher, the
resulting pattern is then used to find matching completions. Isn't
that correct?