Traefik-style . separated flag categories

[XAMPPRocky]

It would be nice if clap had a way to support traefik style flag argument categories which allow you to cleanly separate categories of flags. This would also work well with enums of structs which is currently not supported in the clap derive.

Examples

CLI

# Separate Providers
--providers.docker.endpoint=tcp://127.0.0.1:2377
--providers.docker.swarmMode=true
# Or
--providers.kubernetescrd.endpoint=http://localhost:8080
--providers.kubernetescrd.token=mytoken

Rust Derive

#[derive(clap::Parse)]
struct Cli {
     providers: Providers,
}

#[derive(clap::Args)]
pub enum Providers {
     Docker {
          endpoint: Option<Url>,
          swarm_mode: bool,
     },
     Kubernetescrd {
          endpoint: Option<Url>,
          token: Option<String>,
     }
}

[epage]

This sounds like a more static version of #4198.

With #2621, this would look something like

#[derive(clap::Parse)]
struct Cli {
    #[command(flatten)]
     providers: Providers,
}

#[derive(clap::Args)]
pub enum Providers {
     Docker {
         #[arg(long = "providers.docker.endpoint")]
          endpoint: Option<Url>,
         #[arg(long = "providers.docker.swamMode")]
          swarm_mode: bool,
     },
     Kubernetescrd {
         #[arg(long = "providers.kubernetescrd.endpoint")]
          endpoint: Option<Url>,
         #[arg(long = "providers.kubernetescrd.token")]
          token: Option<String>,
     }
}

Which also makes me realize that for #2621, we should make the implicit #[arg(id = ...)] for Kubernetescrd ::endpoint be "Kubernetescrd::endpoint" rather than "endpoint" which the more naive solution would do. I actually wonder if all ids should be qualified by their type, making this Providers::Kubernetescrd::endpoint

Another interesting aspect your use case brings up is what ti do if no flags are specified. Kubernetescrd is completely optional. Is the intention that a group is required or that Kubernetescrd is the default?. For a group being required, that will require adding a #[group(required = true)] as we haven't switched to flattening requiring a group (yet?). If Kubernetescrd should be a default, we currently have no mechanism for that or even design sketches.

[XAMPPRocky]

Should we do this just for enums or, on the next breaking change, require doing this for structs as well?

I think structs could be nice, just as a way to prefix flags, but I don't think that's as valuable as enum support.

How do we model this from the parser's perspective?

I'm not familiar with clap's parser, but as a user, I think what I would expect having to add an attribute to the field, to make it explicit as a group, this would also provide us with the group names (e.g. providers), so you could collect every argument starting with the group name, and then pass all those arguments to that group's parser.

#[derive(clap::Parse)]
struct Cli {
    #[clap(group)]
     providers: Providers,
}

#[derive(clap::Args)]
#[clap(group)]
pub enum Providers {
     Docker {
         #[arg(long)]
          endpoint: Option<Url>,
         #[arg(long)]
          swarm_mode: bool,
     },
     Kubernetescrd {
         #[arg(long)]
          endpoint: Option<Url>,
         #[arg(long)]
          token: Option<String>,
     }
}

[epage]

#3513 is the issue for prefixes.

I'm not familiar with clap's parser, but as a user, I think what I would expect having to add an attribute to the field, to make it explicit as a group, this would also provide us with the group names (e.g. providers), so you could collect every argument starting with the group name, and then pass all those arguments to that group's parser.

We'd need to answer

• When does the parser start a new group. Is it when an item from another group fist shows up? Do we need a group-start flag? Does the answer to this work for everyone or only some people?
• How does the user specify required-in-a-group vs required-globally?
• How do you tell the builder API about this? How is the data stored in ArgMatches and accessed?

As for the derive API / #[clap(group)], we already have ArgGroup with #[group(...)] attributes, so this isn't something new. We just need to add support for deriving Args for enums which we have an issue for.

[XAMPPRocky]

When does the parser start a new group. Is it when an item from another group fist shows up? Do we need a group-start flag? Does the answer to this work for everyone or only some people?

I would assume that the parser sorts all groups into buckets first, and then validates them all at once. In pseudo-code.

let parser = parser();
let groups: BTreeSet<_, _> = ["providers", "categories"];
let group_args = BTreeMap::default();

// fn arguments() -> impl Iterator<Item = FlagArg>
// Where `FlagArg` is any `--` / `-` flag argument.
'arg: for arg in parser.arguments() {
     for group in groups {
          if arg.starts_with(group) {
              group_args.insert(group, arg);
              continue 'arg;
          }
     }
     // validate non-group arg
}

for args in group_args.values() {
     // validate group args
}

How does the user specify required-in-a-group vs required-globally?

Isn't that what the #[clap(group)] would do? It would state "this shape of arguments is treated as a group", and when it's not there, it's global.

[epage]

I would assume that the parser sorts all groups into buckets first, and then validates them all at once. In pseudo-code.

Your proposed behavior highlights another use case with Vec<Group> that hasn't been discussed before in these settings: only allowing one instance of each group member. We have had requests for allowing multiple instances of a group member with Vec and this is the parse case that is less clear to me. If one instance of each member is desired, then we'd also need to do the API design work (builder and derive) to clarify which the user is requesting.

How does the user specify required-in-a-group vs required-globally?

Isn't that what the #[clap(group)] would do? It would state "this shape of arguments is treated as a group", and when it's not there, it's global.

The presence of an argument implies a group but I'm referring to the presence of the group requiring an argument. Currently, an argument being implicitly required (by not using Option) sets required. I guess we could reuse ArgGroup::requires to require ones own member but the question is how would the derive know to set that instead of required because it doesn't know a group is going to be used in this context. Most likely, we'd need to document that a user must disable required and enable ArgGroup::requires.

[XAMPPRocky]

only allowing one instance of each group member.

Wouldn't that be BTreeSet<Group> / HashSet<Group> instead of Vec<Group>?