[Surfraw-devel] Some ideas for improvements (feedback please!)

[Gabriel Lisaca]

Hi,

Word of warning: long mail ahead!

So I've been thinking of some improvements to Surfraw, but it would 
probably be best to get some thoughts on the matter.  They are as follows:

1. Integrated bash completions in elvi; and
2. Rearranged config files read order.

Bash completions:

There are two ways I've thought of this: (a) have a separate completion 
file (with its own directories), (b) include a completion function in 
each elvis.

I'm leaning towards b more since it's easier to use directly. This 
function would have a similar interface to `w3_parse_option_hook` ($1: 
option name (e.g., `-opt=`), $2: option arg (e.g., `foo`)) and output 
the words to match in its stdout.  It should be written in POSIX shell.

Some open questions (for b):

1. What should the name be? `w3_completion_hook`?  That seems too long, 
and what does the `w3` prefix even mean?

Some downsides to this specific method:

1. Potentially large overhead.  It has to source `surfraw`, find elvis, 
source elvis, execute function.  Maybe it could be overcome by having a 
`-complete` option that does all of those steps in one go (e.g., 
`surfraw debpackages -complete surfr`).  That is, when `-complete` is 
processed, the remaining non-option arguments are the words to be completed.
2. More duplication of information: option names have to be kept 
synchronised between `w3_config_hook`, `w3_parse_option_hook`, and now 
`w3_completion_hook` (or whatever its name will be).

Config files:

As it is, the current hierarchy of configuration is a tad annoying: 
local > elvis > global, with the actual read order being global > elvis 
 > local.  Notice that there is no room for pre-existing (exported) 
environment variables.  This makes customising calls to`surfraw`more 
annoying--especially in scripts calling `surfraw` itself.  In my 
scripts, I've had to include a separate (inherited) `SURFRAW_FLAGS` 
variable to pass to relevant `surfraw` calls.  It would be easier if I 
could do something like:

     $ export SURFRAW_graphical=yes
     $ surfraw foo
     $ surfraw bar

Of course, this would be most useful with scripts calling `surfraw`, as 
detailed above.

I propose that the hierarchy is as follows:  pre-existing environment 
variables > local > elvis > global, while the read order is the same as 
the hierarchy (more intuitive, right?). Local config files should also 
only use the `def*` family of shell functions to set variables.  This 
change depends on it.

Obviously, this isn't backwards compatible, so something similar to the 
change to using `XDG_CONFIG_HOME` could be done.  That is, accept a 
`config` (or something similar) in addition to the other config files, 
while retaining their semantics and read order.  The resulting 
precedence for local config files would then be: 
`$XDG_CONFIG_HOME/config` (the new one) > `$XDG_CONFIG_HOME/conf` (the 
current one) > `~/.surfraw.conf` (the old convention).  Only *one* of 
the local config files would be read.

Some feedback would be great :)  I don't want to make some radical 
changes without consensus.

I'll try to get working implementations of both of those up as soon as I 
can.

PS I was recently granted maintainer access to the Surfraw repo on 
GitLab.  Hi!

Cheers,
Gabriel