refactor: _parse_{help,usage} => _comp_compgen_help

[akinomyoga]

This is based on #952 so would be kept to be Draft until PR #952 settles.

The own changes of this PR are 2ce600f...39b15f3. This PR includes the API change of _parse_{help,usage} and trivial rewriting for switching from _parse_{help,usage}. Other non-trivial rewriting related to _parse_{help,usage} will be included in later PRs.

[akinomyoga]

8a203c1 is automatically generated by running sed and checked afterward by eyes.

8a203c1e

sed -E "s/$path/$rep/g"

with

pat='COMPREPLY=\(\$\(compgen -W '\''\$\(_parse_help ([^()|]+)\)'\'' -- "\$cur"\)\)'
rep='_comp_compgen_help \1'
pat='COMPREPLY=\(\$\(compgen -W '\''\$\(_parse_usage ([^()|]+)\)'\'' -- "\$cur"\)\)'
rep='_comp_compgen_help -u \1'
pat='COMPREPLY\+=\(\$\(compgen -W '\''\$\(_parse_help ([^()|]+)\)'\'' -- "\$cur"\)\)'
rep='_comp_compgen -a help \1'
pat='COMPREPLY\+=\(\$\(compgen -W '\''\$\(_parse_usage ([^()|]+)\)'\'' -- "\$cur"\)\)'
rep='_comp_compgen -a help -u \1'
pat='([[:alnum:]_]{1,})=\(\$\(compgen -W '\''\$\(_parse_help ([^()|]+)\)'\'' -- "\$cur"\)\)'
rep='_comp_compgen_help -v \1 \2'
pat='([[:alnum:]_]{1,})=\(\$\(compgen -W '\''\$\(_parse_usage ([^()|]+)\)'\'' -- "\$cur"\)\)'
rep='_comp_compgen_help -uv \1 \2'
pat='([[:alnum:]_]{1,})\+=\(\$\(compgen -W '\''\$\(_parse_help ([^()|]+)\)'\'' -- "\$cur"\)\)'
rep='_comp_compgen_help -av \1 \2'
pat='([[:alnum:]_]{1,})\+=\(\$\(compgen -W '\''\$\(_parse_usage ([^()|]+)\)'\'' -- "\$cur"\)\)'
rep='_comp_compgen_help -uav \1 \2'
pat='COMPREPLY=\(\$\(_parse_help ([^()|]+)\)\)'
rep='_comp_compgen -R help \1'
pat='COMPREPLY=\(\$\(_parse_usage ([^()|]+)\)\)'
rep='_comp_compgen -R help -u \1'
pat='COMPREPLY\+=\(\$\(_parse_help ([^()|]+)\)\)'
rep='_comp_compgen -aR help \1'
pat='COMPREPLY\+=\(\$\(_parse_usage ([^()|]+)\)\)'
rep='_comp_compgen -aR help -u \1'
pat='^([[:space:]]*)local ([[:alnum:]_]{1,})=\(\$\(_parse_help ([^()|]+)\)\)'
rep='\1local -a \2\n\1_comp_compgen -Rv \2 help \3'
pat='^([[:space:]]*)local ([[:alnum:]_]{1,})=\(\$\(_parse_usage ([^()|]+)\)\)'
rep='\1local -a \2\1_comp_compgen -Rv \2 help -u \3'
pat='^([[:space:]]*)local ([[:alnum:]_]{1,})\+=\(\$\(_parse_help ([^()|]+)\)\)'
rep='\1local -a \2\n\1_comp_compgen -Rv \2 help -a \3'
pat='^([[:space:]]*)local ([[:alnum:]_]{1,})\+=\(\$\(_parse_usage ([^()|]+)\)\)'
rep='\1local -a \2\n\1_comp_compgen -aRv \2 help -u \3'
pat='([[:alnum:]_]{1,})=\(\$\(_parse_help ([^()|]+)\)\)'
rep='_comp_compgen -Rv \1 help \2'
pat='([[:alnum:]_]{1,})=\(\$\(_parse_usage ([^()|]+)\)\)'
rep='_comp_compgen -Rv \1 help -u \2'
pat='([[:alnum:]_]{1,})\+=\(\$\(_parse_help ([^()|]+)\)\)'
rep='_comp_compgen -aRv \1 help \2'
pat='([[:alnum:]_]{1,})\+=\(\$\(_parse_usage ([^()|]+)\)\)'
rep='_comp_compgen -aRv \1 help -u \2'

56d55ac is searched by grep and then manually replaced.

[scop]

I'm wondering if passing everything after a -- to the command would be a cleaner and more consistent API for this? For example _comp_compgen uses that approach.

[akinomyoga]

I also thought about it, but as far as the command name $1 does not start with -, we can actually omit --. The difference in _comp_compgen is that the arguments to compgen always starts with -. But I think it is good to prefix -- before every "$1".

[akinomyoga]

Hmm, maybe it is better to split the function into two separate functions _comp_compgen_help and _comp_compgen_usage.

Before introducing the idea _comp_compgen NAME, I originally combined _parse_help and _parse_usage in a single function because it shared long codes of the command-line option parsing. But now the option parsing is moved to _comp_compgen, so two processings help and usage now share only a small part of the code. I'll think about it again.

[akinomyoga]

I split the function into _comp_compgen_help and _comp_compgen_usage.

[scop]

I like the split better. Perhaps still provide command options as $2... instead of cramming them into single $2 string, for a bit cleaner call site code and avoiding a _comp_split?

Then again, I suppose we could make the first parameter optional too, and default it to ${comp_args[0]}. If so, usage like [-c command] [--] [command_opts...] could be in order.

[akinomyoga]

Then again, I suppose we could make the first parameter optional too, and default it to ${comp_args[0]}. If so, usage like [-c command] [--] [command_opts...] could be in order.

I like this idea. Let me implement it.

[akinomyoga]

After thinking about it again, I have slightly changed the suggested command line usage:

usage: _comp_compgen_help -
usage: _comp_compgen_help -c cmd args...
usage: _comp_compgen_help [[--] args...]

• When we want to read stdin, requiring to write _comp_compgen_help -c - seems strange, so _comp_compgen_help - is supported separately.
• When the caller specifies the command and arguments, splitting between $1 and $2... with -- as _comp_compgen_help -c cmd -- args also seems not so natural. So when the first argument is -c, the later words are all treated as the command and arguments as is.
• _comp_dequote is only applied to comp_args[0]. The command name specified through -c cmd args... is not de-quoted by _comp_dequote. When it is needed, the caller should take care of it.
• --help (or --usage in the case of _comp_compgen_usage) is only supplemented when no arguments are specified. E.g., when the user uses _comp_compgen_help --, it doesn't specify --help but directly calls comp_args[0] without arguments.

---

I rebased and modified existing commits. There are additional commits:

• There are additional fixes for localvar_inherit: 0a87c15
• The backslash in -\? in ssh-addwas removed: 01cfc44
• These are non-trivial changes (where originally, a command name different from "$1" or multiple words in $2 are supplied): fbe62ba

[scop]

We could clean up some redundant passing of --help while at it.

[scop]

I like the split better. Perhaps still provide command options as $2... instead of cramming them into single $2 string, for a bit cleaner call site code and avoiding a _comp_split?

Then again, I suppose we could make the first parameter optional too, and default it to ${comp_args[0]}. If so, usage like [-c command] [--] [command_opts...] could be in order.

[scop]

Nice, pre-approved with some comments addressed.