Allow making inherited options hidden on subcommands

[remkop]

This depends on #649.

Once inherited/global options are implemented, there will be cases where the top-level command defines many shared options, and each subcommands defines only the options applicable for that specific command. Applications may want to define some or all of the top-level options as "global" or "inherited" options, so they can be specified on the top-level command as well as on the subcommand.

However, they may not want the inherited options to clutter the usage help message of the subcommand, especially if there are many inherited options.

Ideas for Programmatic Solution

Provide API to allow subcommands to hide inherited options. For example:

CommandLine::setHideInheritedOptions(boolean) // on the full hierarchy
CommandSpec::hideInheritedOptions(boolean) // on a specific command

Ideas for Declarative Solution

Add an enumeration value to hide inherited options. For example:

public enum ScopeType {
    /** The element only exists in the current command. */
    LOCAL,
    /** The element exists in the command where the element is defined
     * and all descendents (subcommands, sub-subcommands, etc.). */
    INHERIT,
    /** The element exists in the command where the element is defined
     * and all descendents (subcommands, sub-subcommands, etc.),
     * but is not shown in the usage help for the descendents. */
    INHERIT_AS_HIDDEN,
}

TBD should this apply to inherited positional parameters?

[remkop]

Some work is in progress to address this: the tickets below make it easier to customize the option list in the usage help message. However, it is not yet possible to customize the synopsis...

• [Add methods Help::optionListExcludingGroups to show only the specified options, including hidden ones #1090] API: Add methods Help::optionListExcludingGroups to return a String with the rendered section of the usage help containing only the specified options, including hidden ones.
• [Add methods Help::parameterList(List<PositionalParamSpec>) to show only the specified positional parameters, including hidden ones #1092] API: Add method Help::parameterList(List<PositionalParamSpec>) to return a String with the rendered section of the usage help containing only the specified positional parameters, including hidden ones.
• [Add method Help::optionListGroupSections to show option groups #1091] API: Add method Help::optionListGroupSections to return a String with the rendered section of the usage help containing only the option groups.
• [Add API allOptionsNested and allPositionalParametersNested to ArgumentGroupSpec #1087] API: Add methods ArgumentGroupSpec::allOptionsNested and ArgumentGroupSpec::allPositionalParametersNested.
• [Add API in Help.Layout that shows all specified options (including hidden ones) #1086] API: add methods Help.Layout::addAllOptions and Help.Layout::addAllPositionals, to show all specified options, including hidden ones.

[remkop]

This is now implemented in master.

See these examples for how to accomplish this:

• CustomOptionListAndSynopsis
• CustomOptionListAndSynopsisWithInheritance