std/flags should be able to provide "--help" usage information

[jaredkrinke]

Is your feature request related to a problem? Please describe.

Deno's std/flags module can parse command line arguments, but a complete command line interface should also be self-documenting, e.g. by printing out usage information when "--help" is specified. Currently, there doesn't appear to be anything in the standard library for producing usage information.

Describe the solution you'd like

My personal preference would be to extend the existing std/flags module to support optionally generating usage information on "--help". I created a prototype module here: x/flags_usage (note: I'm not claiming this is the ideal solution; it just does what I want and has reasonable default behavior on the interfaces I've tested it on).

Describe alternatives you've considered

• Manually printing out usage
  • Obviously can be done today, but it would be nice if the standard library made this easy to do (at least for trivial cases such as tools that only have string/bool/number options), so that we'd all spend less time formatting strings, and tools would have a more consistent style
• Third party modules
  • There are some third party modules for this (in the Node ecosystem, I liked commander), but I think it would make sense to just build on the existing std/flags module because it seems to be widely used (and again, there would be more consistency)
  • Leaving this to third party modules is reasonable, but not ideal, in my opinion
• Focus only on parsing and leave usage out of the picture, i.e. do nothing
  • This is what minimist did (relevant issue)
  • I think the same reasoning does not apply here because Deno claims to be convenient for creating command line utilities ("Deno is a great replacement for utility scripts that may have been historically written with Bash or Python.") and having usable command line interfaces is required for that, so creating such interfaces should be easy

[bartlomieju]

Sounds like a good idea and it would be a nice addition! PRs are welcome.

[LionC]

Just to connect the idea: I think it would be very good to have a commander-like module in general, which covers argument parsing, subcommands, help text etc (together with some utils e.g. for redrawing, loading bars, inquirer-like interaction...). The jump to that is not as far as it seems.

[bartlomieju]

Just to connect the idea: I think it would be very good to have a commander-like module in general, which covers argument parsing, subcommands, help text etc (together with some utils e.g. for redrawing, loading bars, inquirer-like interaction...). The jump to that is not as far as it seems.

That sounds good to me too, again PRs are welcome!

[jaredkrinke]

My vote would be for scoping this to just argument parsing, commands, and usage info. In other words, for non-interactive command line interfaces. (I thought commander was also scoped this way, but I could be wrong.)

Redrawing, progress bars, etc. are often handled separately in other languages (e.g. popt vs curses in C).

If you think both should be grouped together, I've heard the "cliffy" module might be a good start (though I've never used it).

[jaredkrinke]

Not sure how I missed this the first time I looked, but someone already created a commander-like module for Deno:

https://github.com/siokas/denomander

I haven't tried it out yet, but it sounds promising.

[gtamas]

@bartlomieju @kt3k
I would gladly look into this, but it's not clear to me what's the goal here.
Is this only about adding the ability of usage info generation (--help), or is this more about improving the current implementation, turning it into a more sophisticated commander or yargs-like module (or something similar), as proposed above?

Could you clarify so I can get started? Thx!

[gtamas]

Btw, in my opinion the ideal scope would be maybe improving the current implementation, but keeping it simple. Just argument, option parsing, defaults, help generation etc in a nicely organised API, like commander.
I mean, turning this module into a super advanced CLI parser is also an option of course, but I'm not sure that makes sense. Yargs and other packages are available.

Anyway, please let me know what you think. I'm happy to work on anything related to this. Just let's decide the scope.

[gtamas]

@bartlomieju @kt3k
Could you please get back to me on this? I could start to work on it this weekend.
I need to know what direction would you prefer. A minimalist, commander-like API with command, flag parsing and usage info generation? Or something more?

[kt3k]

@gtamas
What kind of API design do you have in mind? If it's backward compatible, then probably it's fine to go ahead with it. If your design includes breaking changes, please create a proposal issue first with your proposed design, and let's discuss it there.

[gtamas]

@kt3k
Thanks for the reply.
My plan for now is just to extend the current implementation and add usage info generation (if possible).
As I can see, the current code is a minimalist approach So I would extend it without any major API changes.

But I still don't understand what's the long term goal. Do you wish the "flags" module to be a highly advanced CLI parser / API someday or do you want to keep the current minimalist approach?

A major API refact would require a proper proposal. I'm happy to work that too.

[kt3k]

@gtamas

My plan for now is just to extend the current implementation and add usage info generation (if possible).
As I can see, the current code is a minimalist approach So I would extend it without any major API changes.

If the change doesn't include breaking changes, we probably can land those changes.

But I still don't understand what's the long term goal. Do you wish the "flags" module to be a highly advanced CLI parser / API someday or do you want to keep the current minimalist approach?

I think there's no fixed long term goal about std/flags for now. So I think this depends on what the community needs for it.

But because yargs now officially supports deno https://github.com/yargs/yargs#deno, and there's also a good CLI framework cliffy, I personally guess the demand of such feature-rich CLI tools are now a little low in the community (but that doesn't prevent people from working on this area