Command groups?

[zackw]

I'm working on a program with two groups of subcommands. Here's an excerpt of help output as it stands currently:

Usage: bshatag COMMAND ...

Available commands:
    verify           Verify existing tags.
    recalculate      Recalculate tags from scratch.
    remove           Remove tags.
    write            Copy data from standard input to a file, and
                     tag that file.
    create           Same as 'write', but will not overwrite a file
                     that already exists.

It would be easier to understand if I could mark the first three commands as one group and the last two as another group, specify custom usage for each group (not each command) and get output more like this:

Usage: bshatag (TREE-WALK-MODE ROOTS... | WRITE-MODE DESTINATION)

Tree-walking modes:
    verify           Verify existing tags.
    recalculate      Recalculate tags from scratch.
    remove           Remove tags.

Writing modes:
    write            Copy data from standard input to a file, and
                     tag that file.
    create           Same as 'write', but will not overwrite a file
                     that already exists.

Is this currently possible? If not, how difficult would it be to add?

[pacak]

group_help can arrange items into groups, custom_usage can change how items look on the usage line. I think both of those should work with commands as well.

• https://docs.rs/bpaf/latest/bpaf/trait.Parser.html#method.group_help
• https://docs.rs/bpaf/latest/bpaf/trait.Parser.html#method.custom_usage

[zackw]

Yes, that does work. The documentation somehow made me think that you could only apply group_help to a construct!ed struct, not any other group of parsers, but now I realize that's silly. I might send a patch adding some more examples to the group_help documentation later.

[pacak]

Heh. I'm doing a big documentation rewrite right now and would really appreciate a list of any sticking points. Like something that was hard to find, hard to understand and so on.