Add API for titling an option group #492
Conversation
This change lets you provide a title for option groups, which is used
when generating the help screen. Titled option groups, when they exist,
are placed between the ARGUMENTS and OPTIONS section of the help.
Multiple option groups with the same title are coalesced into a single
group.
For example, this command declaration:
struct Extras: ParsableArguments {
@Flag(help: "Print extra output while processing.")
var verbose: Bool = false
@Flag(help: "Include details no one asked for.")
var oversharing: Bool = false
}
@main
struct Example: ParsableCommand {
@OptionGroup(title: "Extras")
var extras: Extras
@argument var name: String?
@option var title: String?
}
yields this help screen:
USAGE: example [--verbose] [--oversharing] [<name>] [--title <title>]
ARGUMENTS:
<name>
EXTRAS:
--verbose Print extra output while processing.
--oversharing Include details no one asked for.
OPTIONS:
--title <title>
-h, --help Show help information.
|
@rauhul I think we'll need an updated schema for the JSON help dump, and then we can update the man page generation to support this feature as well. Does that sound right? |
| // Combine the compiled groups in this order: | ||
| // - arguments | ||
| // - named sections | ||
| // - options/flags | ||
| // - subcommands |
There was a problem hiding this comment.
@rauhul @ethan-kusters Does this seem like the correct order?
There was a problem hiding this comment.
Yeah this makes sense to me!
There was a problem hiding this comment.
LGTM, I'm a little unsure if setting the title on every instance of an option group is the best api. It may be valuable to have an OptionGroupConfiguration so a default title could be provided by the type. This can always be added in the future, so theres no reason to stop this change.
|
|
||
| extension OptionGroup { | ||
| @_disfavoredOverload | ||
| @available(*, deprecated, renamed: "init(title:visibility:)") |
There was a problem hiding this comment.
Do we need this still, SAP isn't ABI stable and the above initializer is source compatible?
There was a problem hiding this comment.
eh, well very very minimally source breaking if someone ever used a point free version of the function: OptionGroup.init(visibility:)I really doubt this is the case though.
| @@ -136,6 +139,8 @@ internal struct HelpGenerator { | |||
|
|
|||
| var positionalElements: [Section.Element] = [] | |||
| var optionElements: [Section.Element] = [] | |||
| var titledSections: [String: [Section.Element]] = [:] | |||
| var sectionTitles: [String] = [] | |||
There was a problem hiding this comment.
is this needed? It seems like a duplicate of titledSections.keys
There was a problem hiding this comment.
NVM this is so they are sorted. A comment about this would be nice!
This is a really good point. I think since we'll want to be able to specify a title at the |
|
@swift-ci Please test |
| @@ -239,4 +238,8 @@ extension StringProtocol where SubSequence == Substring { | |||
| guard lines.count == 2 else { return lines.joined(separator: "") } | |||
| return "\(lines[0])\n\(lines[1].indentingEachLine(by: n))" | |||
| } | |||
|
|
|||
| var nilIfEmpty: Self? { | |||
There was a problem hiding this comment.
Note: this is called nonEmpty in ArgumentParserToolInfo
natecook1000
force-pushed
the
named_option_groups
branch
from
5a7ca46
to
47188c7
Compare
|
@swift-ci Please test |
This change lets you provide a title for option groups, which is used when generating the help screen. Titled option groups, when they exist, are placed between the ARGUMENTS and OPTIONS section of the help. Multiple option groups with the same title are coalesced into a single group.
For example, this command declaration:
yields this help screen:
Resolves #267.
Checklist