--help to rule them all

[Glutexo]

The -h/--help switch is omnipotent. It trumps all other valid switches or positional arguments.

• onigumo --help
• onigumo --help downloader
• onigumo downloader --help
• onigumo --help --working-dir . downloader
• onigumo --working-dir . --help downloader
• onigumo --working-dir . downloader --help
• onigumo downloader --working-dir . --help

All the commands above print the help message. This behavior is insipired by established UNIX tools like cURL and Wget.

Resolves #205.

[Glutexo]

There are no tests yet. Those from @nappex’s pull request #238 may come handy. This PR obsoletes #238 and #244.

[Glutexo]

I realized that both cURL and Wget only print a help message if --help is on the first position. If an invalid switch is passed before --help, an invalid usage message is printed instead of a help message.

Wget

Wget needs --help on the first position to print the help message. It still recognizes invalid switches though.

$ LC_ALL=C wget --invalid --help
wget: unrecognized option '--invalid'
Usage: wget [OPTION]... [URL]...

Try `wget --help' for more options.

$ wget --help --invalid 
wget --help --invalid 
wget: unrecognized option '--invalid'
GNU Wget 1.25.0, a non-interactive network retriever.
Usage: wget [OPTION]... [URL]...

Mandatory arguments to long options are mandatory for short options too.

Startup:
  -V,  --version                   display the version of Wget and exit
…

$ wget --help --version
wget --help --version
GNU Wget 1.25.0, a non-interactive network retriever.
Usage: wget [OPTION]... [URL]...

Mandatory arguments to long options are mandatory for short options too.

Startup:
  -V,  --version                   display the version of Wget and exit

cURL

cURL supports help categories like --help auth. If an invalid argument is passed after a help and its category, no error is printed.

$ curl --invalid --help
curl: option --invalid: is unknown
curl: try 'curl --help' or 'curl --manual' for more information

$ curl --help --invalid
Usage: curl [options...] <url>
Invalid category provided, here is a list of all categories:

 auth        Different types of authentication methods
…

$ curl --help auth --invalid
Usage: curl [options...] <url>
auth: Different types of authentication methods
     --anyauth                       Pick any authentication method
…

[Glutexo]

We discussed the matter with @nappex and we concluded that mixing --help with other CLI options would only be confusing. --help --working-dir may be an attempt to get help for the switch, --help downloader would be the same for the component.

We decided to only support lone -h/--help and print invalid usage message if combined with anything else. The usage message would instruct the user to run onligumo --help with no other options.

Closing this PR as outdated.

[Glutexo]

How to implement the lone help switch? I was thinking about a case clause.

case parsed do
  {help: true, [], []} →
     help_message()
  _
     … with …
end