From gabriel.lisaca at gmail.com  Wed Jun 16 12:11:40 2021
From: gabriel.lisaca at gmail.com (Gabriel Lisaca)
Date: Wed, 16 Jun 2021 23:11:40 +1200
Subject: [Surfraw-devel] Elvis-specific completions are done
Message-ID: <4e41a7ce-597c-10d2-2a81-1f8300781968@gmail.com>

Hi all,

Just a warning, long mail ahead!

So I've finished (really) the elvis-specific completions support I 
talked about a while back.  It's at merge request !15 [0].

It would be appreciated if you had a play around with it.  If you want 
to read the changes, the most relevant files to see are surfraw.IN and 
surfraw-bash-completion.IN

Regarding the issues raised when I suggested elvis-specific completions:

* I don't think this is much more complicated than before and it's easy 
enough to use by example (copy-pasting is even encouraged by the HACKING 
file).
* It also doesn't affect the current test approach at all.  Why would 
the completions be tested?

On the other hand, the benefits include a more comfortable command line, 
and easy consumption by tools that wrap surfraw to give a nicer 
interface.  As for the former, stuff like -co*=* are nice, but too 
imprecise for my tastes.  I do the latter in my dmenu script for surfraw 
[1], and it feels nice to use.

(To be honest, I want my elvi on my phone, which I have most of the 
time.  And since typing on a phone is a pain, a graphical interface that 
gives me full access to the functions of an elvis is important.  I plan 
to do this at some point.)

I've documented the changes in the HACKING file, but here's a summary:

 > Surfraw now supports elvis-specific tab-completions, eg:
       sr debpackages -<TAB>
       sr debpackages -release=<TAB>
       sr debpackages <TAB>
   can all be defined by an elvis.

The first one (option name completion) is done by the new function 
mkopts() whose arguments are the option names available to the current 
elvis.  Options that take arguments and those that don't are 
distinguished by an '=' suffix.  '=' for options that *do*, nothing for 
options that don't.
For example:
     mkopts optwithoutarg optwitharg=

The second one (option argument completion) is done by 
w3_complete_hook_opt().  It functions similarly to 
w3_parse_option_hook(), switching on its input (the option), but this 
time outputting its possible values, separated by whitespace, instead of 
setting variables.

The third one (elvis argument completion) is done by 
w3_complete_hook_arg().  The output is the possible values of the 
argument, separated by *newline* characters.  It defaults to using 
`look` on the system dictionary (like it did before), but some elvi 
override it for more useful completions, such as debpackages and other 
elvi that work with package names.

More elvi now complete package names too: archpkg, debpkghome, finkpkg, 
and genportage.  Package names are taken from one of: apt-cache, pacman, 
yum, and fink.  I use Debian so I used online references to help create 
completions from the other package managers.  Just FYI.

0: https://gitlab.com/surfraw/Surfraw/-/merge_requests/15
1: 
https://github.com/Hoboneer/.scripts/blob/50678c467cc23207d549fdbe9e874a37b6aab085/dmenu_surfraw

Cheers,
Gabriel