Explain mode

[KOLANICH]

Inspired by https://github.com/open-source-ideas/open-source-ideas/issues/270 .

It may be nice to have an "--hexplain" (--help + --explain, the name is intentionally mistyped instead of using --explain in order to avoid potential conflicts, 120 results in Google for hexplain, and 290 on GitHub, lot of which are not source code) mode in addition to --help.

• ~~When invoked with such a flag (--hexplain) an app should parse its command line and print into stdout a human-readable text explaination of the actuall args used. Its exact appearance is at discretion of CLI parsing library, but it must have the following features:~~

  • ~~first it may clear the echo left by a shell and replace it with a syntax-highlighted version of the command it was got by the app.~~
  • ~~then goes the human-readable overall overview what the whole call does. Its support can be implemented via a hook. If there is no hook set up, it shows the short summary. If there is no short summary set up, it is not shown at all.~~
  • ~~then goes a list of args. First a syntax-highlighted quote of each arg and its value goes, second the human-readable explaination of exactly this arg goes. The explaination can be customized via a hook. If there is no hook set up, the description provided by the tool author for help text is shown.~~

• When an ~~optional~~ value is passed the command must return a machine-readable explaination using some (it is proposed to use BEncode due to its extreme simplicity) binary serialization format

  • =parse should return an AST of the command line.
  • =human should return a machine-readable non-syntax-highlighted version of the messages for each argument.
  • =spec returns a spec that can be used by GUI tools for creating a GUI widget for starting the CLI app and maybe tools like https://github.com/amoffat/sh for creating wrappers for CLI tools.
  • Since we use bencode and it supports dicts, this is composable. =human,parse return both.

It worth mentioning that it turns out that there exists a tool https://github.com/idank/explainshell doing some of the functionality proposed here.

[ThiefMaster]

While interesting, I have the feeling this is such a niche usecase that it's not worth the maintenance overhead unless it can be implemented as a standalone package people can just use in addition to click...