search

ndmitchell / cmdargs

Haskell library for command line argument processing
Other
91 stars 12 forks source link

Have --help list the options available for --help #41

Open phlummox opened 7 years ago

phlummox commented 7 years ago

For an end-user, it's not at all obvious that "--help" will accept arguments, since this doesn't seem to be especially typical of command-line programs.    I'm therefore adding my own explanation, since so far as I can see, there is no way of automatically producing it. Also, a number of options ( "def", "bash", "zsh") aren't actually explained in the documentation for System.Console.CmdArgs.Explicit.flagHelpFormat, one has to look at various other bits of documentation and the source code.    Would it be possible to have "--help" (either by default, or as an option) display to the user the options available for "--help"?

phlummox commented 7 years ago

Hm. From a casual look at the code, it doesn't even look like it's possible to "slightly modify" what "--help" does in System.Console.CmdArgs.Implicit, since the behaviour is baked in using code in System.Console.CmdArgs.Implicit.Global, which only exports global.     So the options seem to be to abandon using 'Implicit', and use 'Explicit' (which is undesirable, 'Implicit' is part of the reason I'm using cmdargs); or to reimplement hunks of 'Global' (messy); or to use a patched version of cmdargs.     For future versions, might it be possible to expose more of the internals of 'Implicit' to make it easier to alter the behaviour? (e.g. Using the pattern of ".Internal" packages, which are accessible, but for which a stable API isn't guaranteed.)

ndmitchell commented 7 years ago

Having --help only display the extra features as an option would give the same problem of discoverability. I should document properly that --help takes flags, on the command line, and say what they are, since it can be useful. That does seem like a good idea.

It isn't possible to delve inside the existing --help flags, but I don't think making the Internals available would give you any more leverage - there just isn't an extension point where you could add them without monkey-patching. I'm not a fan of the .Internal API pattern - it seems the pattern of lazily dumping the guts of your library onto users because you don't have the right abstractions - and it always ends up with some level of implied API stability.

phlummox commented 7 years ago

Hi, many thanks for that!   re the internal modules: Yes, having looked into the code, I see what you mean, and I agree – there's no point exposing something unless there's some level of extensibility. Thanks again for your consideration, though :)