Support for using ArgGroup as Enum with derive

[ModProg]

Maintainer's notes

• Deriving Args on an enum would create a ArgGroup::new("T")::multiple(false)
• More builder methods can be accessed via #[group(...)] (split out as Implement more derive attributes for ArgGroup #4574)
  • We need to ensure overriding the group name works
• Variants without a type would be flags
• Tuple variants would be arguments like in a struct
• Flattening tuple variants would use Args::group_id, flattening struct variants would use the Variant.
  • Flattened struct variant fields should have their Arg::id set to Variant::field, see Traefik-style `.` separated flag categories #4699.
• Likely, we'll need to refactor clap_derive so we can share code between structs and enums
• Note that nesting groups is problematic atm. See Create a group from an Args struct #3165
• Create a Traefik cookbook example based on notes in Traefik-style `.` separated flag categories #4699

Blocked on #3165 as that will lay some of the initial groundwork and #4211 to provide a fallback mechanism

Related

• Optional, nested flatten gets ignored (nested ArgGroups are unsupported) #4697

---

Please complete the following tasks

• I have searched the discussions
• I have searched the existing issues

Clap Version

3.0.0-beta.2

Describe your use case

I have multiple filters of witch only one can be set (--running, --exited, --restarting,...).

Describe the solution you'd like

I would like something with this usage:

#[derive(Clap)]
pub struct App{
    #[clap(flatten)]
    pub state_filter: StateFilter,
}

#[derive(Args)]
pub enum StateFilter {
    /// Only running servers are returned
    #[clap(long)]
    Running,
    /// Only exited servers are returned
    #[clap(long)]
    Exited,
    /// Only restarting servers are returned
    #[clap(long)]
    Restarting,
    #[clap(long)]
    Custom(String),
}

Resulting in:

OPTIONS:
    --exited
           Only exited servers are returned
    --restarting
           Only restarting servers are returned
    --running
           Only running servers are returned
    --cusxtom <CUSTOM>

Alternatives, if applicable

I could use an arggroup for this currently, but I would still need to check each boolean separately and could not just easily (and readable) match it.

Additional Context

No response

[epage]

When I was implementing the Args trait, I was thinking of this case. I was assuming we could do

#[derive(Clap)]
pub struct App{
    #[clap(flatten)]
    pub state_filter: Option<StateFilter>,
}

#[derive(Args)]
pub enum StateFilter {
    /// Only running servers are returned
    #[clap(long)]
    Running,
    /// Only exited servers are returned
    #[clap(long)]
    Exited,
    /// Only restarting servers are returned
    #[clap(long)]
    Restarting,
}

(with an attribute on the enum to override the group name)

Though I hadn't considered

• Option in the caller, I like it!
• Enum variants as flags, which I also like!

[Skirmisher]

This would be lovely for my use case (an archive utility, where the operation modes are exclusive but otherwise share the same options, similar to tar). I find clap's subcommand system to be a bit heavy-handed for what I need, but I'm lacking another way to concisely describe and match "exactly one of these options" like is described here.

[epage]

You can workaround this by manually defining the arg group and adding the arguments to it. While its using structopt instead of clap-derive, the principle and calls are pretty much the same in this code of mine.

[0x5c]

The problem with argument groups and the struct equivalent is that you can't ask clap what option was specified, all you can do is check each individual option of the group for presence in the arguments. We're back to to arguments not really being parsed into something useful.

With subcommands, clab directly talls you what subcommand was found in the arguments, as either an Enum or as the string ID of the subcommand. In both cases you can actually match on something instead of having an if-else chain or iteration simply to know which one it was

[MTCoster]

I have a perfect use case for this right now: my app can accept a config file, or (perhaps if the config is very short) a string directly in the command line. For instance:

$ app --config 'foo=bar,baz=bat'
$ app --config-file ../longer-config.txt

The config string is not designed to be parsed by the app; it's passed directly through to the output. I have no desire to parse it.

Ideally, I'd write something like this:

#[derive(Parser)]
struct RootArgs {
    #[clap(flatten)]
    config: ConfigStringOrFile,
}

#[derive(Args)]
enum ConfigStringOrFile {
    #[clap(short = 'c', long = "config")]
    String(String),
    #[clap(short = 'C', long = "config-file")]
    File(PathBuf),
}

fn main() {
    let args = RootArgs::parse();

    let config = match args.config {
        ConfigStringOrFile::String(s) => s,
        ConfigStringOrFile::File(path) => { 
            // Read config from file...
        },
    };

    // ...
}

[epage]

The problem with argument groups and the struct equivalent is that you can't ask clap what option was specified, all you can do is check each individual option of the group for presence in the arguments. We're back to to arguments not really being parsed into something useful.

Yes, its only a workaround to help keep people from being blocked and is not ideal. We are trying to focus on polishing up clap v3 before before working on new features. Once v3 is out (and maybe a little after as we do high priority work we postponed), we can look into this or mentoring someone who can look into this,