Allow replacing commands with metavar when using parserOptionGroup

[nmattia]

First of all, thank you for optparse-applicative! I've been using it for many years and it's one of the reasons I come back to Haskell every now and then.

Recently parserOptionGroup was added which allows grouping options. When used alone though, the options are shown twice. In niv, which has a few options (simplified below), it eats up a lot of real estate:

Usage: <interactive> update [PACKAGE] 
                            [
                              (--attribute KEY=VAL | 
                                --string-attribute KEY=VAL | --owner ARG | 
                                --repo ARG | --branch ARG | --rev ARG)]

  Update dependencies

ATTRIBUTES
  --attribute KEY=VAL      ...
  --string-attribute KEY=VAL
                           ...
  --owner ARG              ...
  --repo ARG               ...
  --branch ARG             ...
  --rev ARG                ...

Available options:
  -h,--help                Show this help text

I've come up with a mixture of a dummy option and hidden modifiers which show a metavar instead, which I think makes the output easier to understand:

Usage: <interactive> update [PACKAGE] [ATTRIBUTES]

  Update dependencies

ATTRIBUTES
  --attribute KEY=VAL      ...
  --string-attribute KEY=VAL
                           ...
  --owner ARG              ...
  --repo ARG               ...
  --branch ARG             ...
  --rev ARG                ...

Available options:
  -h,--help                Show this help text

The implementation looks like this:

parsePackageSpec' :: Opts.Parser ParsedPackageSpec
parsePackageSpec' = groupOptions "ATTRIBUTES" $ ParsedPackageSpec <$> Opts.some attribute
    where
        groupOptions :: String -> Opts.Parser a -> Opts.Parser a
        groupOptions mv x = Opts.option empty (Opts.metavar mv) <|> Opts.parserOptionGroup mv x
        
        attribute = Opts.strOption ... Opts.hidden

        ...

Am I missing something obvious with parserOptionGroup? Is there a simpler way to achieve this?

[tbidne]

Hi @nmattia, implementer of parserOptionGroup here.

If I am not mistaken, your issue doesn't really have anything to do with parserOptionGroup per se, as I believe this is how optparse has always worked? That is, options have always been duplicated in the "brief description" (top of --help) and the "full description" (Available options list), except for those marked hidden. For example, niv 0.2.22 shows this behavior, presumably before your parserOptionGroup usage:

λ. niv update --help
Examples:

  niv update                     # update all packages
  niv update nixpkgs             # update nixpkgs
  niv update my-package -v beta-0.2 # update my-package to version "beta-0.2"

Usage: niv update [PACKAGE 
                    [(-a|--attribute KEY=VAL) | 
                      (-s|--string-attribute KEY=VAL) | (-b|--branch BRANCH) | 
                      (-o|--owner OWNER) | (-r|--rev REV) | 
                      (-v|--version VERSION) | (-t|--template URL) | 
                      (-T|--type TYPE)]]

  Update dependencies

Available options:
  -a,--attribute KEY=VAL   Set the package spec attribute <KEY> to <VAL>, where
                           <VAL> may be JSON.
  -s,--string-attribute KEY=VAL
                           Set the package spec attribute <KEY> to <VAL>.
  -b,--branch BRANCH       Equivalent to --attribute branch=<BRANCH>
  -o,--owner OWNER         Equivalent to --attribute owner=<OWNER>
  -r,--rev REV             Equivalent to --attribute rev=<REV>
  -v,--version VERSION     Equivalent to --attribute version=<VERSION>
  -t,--template URL        Used during 'update' when building URL. Occurrences
                           of <foo> are replaced with attribute 'foo'.
  -T,--type TYPE           The type of the URL target. The value can be either
                           'file' or 'tarball'. If not set, the value is
                           inferred from the suffix of the URL.
  -h,--help                Show this help text

What parserOptionGroup did, was allow groups in the "full description", but the "brief description" was unchanged. It sounds like you would also like the ability for options to be grouped in the "brief description" as well?

This sounds like it could be a good feature, as it would be a nice middle-ground between having nothing (everything marked hidden) and a very busy description (all options individually listed). I think you'd want a new ParserPrefs field, something like

data BriefOptDesc
  = BriefOptDescSummarize
  | BriefOptDescList -- default