dependent optional arguments

[TheJJ]

Please complete the following tasks

• I have searched the discussions
• I have searched the open and rejected issues

Clap Version

master

Describe your use case

i have a building tool with several build backends.
depending on the used backend, it can have different other arguments.

example:

• select the build backend with --driver docker, this unlocks other options like --dockerfile <name>.
• when we instead use --driver lxd, we have other options such as --lxc-raw "lxc.init.cmd = /bin/bash"

Describe the solution you'd like

this can be done very similar to Subcommands, but without enforcing the positional order.

this could be Subargs or something. definition wise, you could define them just like subcommands, in the above case

#[derive(Parser, Debug)]
#[command(name = "debmagic")]
struct Cli {
    #[command(subcommand)]
    command: Commands,
}

#[derive(Subcommand, Debug)]
pub enum Commands {
    Build(BuildSubcommandArgs),
    ...
}

#[derive(Args, Debug)]
pub struct BuildSubcommandArgs {
    #[arg(short, long)]
    pub driver: Option<BuildDriverType>,

    #[arg(short, long)]
    pub source_dir: Option<PathBuf>,
}

#[derive(Subargs, Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord, ValueEnum, Serialize, Deserialize)]
pub enum BuildDriverType {
    Docker(DockerDriverArgs),
    Lxd(LxdDriverArgs),
}

#[derive(Args, Debug)]
pub struct DockerDriverSubargs {
    #[arg(long)]
    pub dockerfile: Option<String>,
    ...
}

#[derive(Args, Debug)]
pub struct LxdDriverSubargs {
    #[arg(long)]
    pub lxc_raw: Option<String>,
    ...
}

Alternatives, if applicable

currently, you would

• either make the driver a subcommand, which doesn't fit its optional nature and position independence.
• or add the arguments at the same level as the driver selection, and then use ArgGroups. this doesn't model the variable relations and encapsulation properly, though.

#[derive(clap::Subcommand, Debug)]
enum Commands {
    #[command(
        group(
            ArgGroup::new("docker_args")
                .args(["docker_image"])
                .conflicts_with("lxd_args")
        ),
        group(
            ArgGroup::new("lxd_args")
                .args(["lxc_options"])
        )
    )]
    Pack {
        #[arg(long, value_enum)]
        driver: Option<Driver>,

        /// docker options
        #[arg(long, group = "docker_args")]
        docker_image: Option<String>,
        ...

        /// lxd options
        #[arg(long, group = "lxd_args")]
        lxc_options: Option<String>,
        ....
    },
}

Additional Context

No response

[epage]

Note that this is defining the solution in terms of the derive API. That is a wrapper around the builder API. We would need both defined (and how they map to each other). Generally, these would be separate issues as they have their own independent design constraints to keep track of.

Regarding the builder API, related conversations:

• Make arg enabled depending on value of other arg? #4402
• How to return an error when the value of another argument is unexpected #5556

Regarding the derive API, this is a bit tricky because parts of this are defined in BuildSubcommandArgs and parts are defined in BuildDriverType. This requires a lot of coordination across types which proc-macros can't do. Instead, this requires doing that communication through the traits. There are many features people want that would require an extension of the traits here or there but it doesn't scale very well.

[TheJJ]

I see there was a typo, sorry. BuildSubcommandArgs doesn't need to know about the subargs and just BuildDriverType needs the info, since we basically just "include" more arguments when one enum value is chosen.

Regarding the builder API, how about adding to_additonal_args to ValueEnum?:

#[derive(Eq)]
enum BuildDriverType {
    Docker,
    LXD,
}

impl ValueEnum for BuildDriverType {
    fn value_variants<'a>() -> &'a [Self] {
        &[BuildDriverType::Docker, BuildDriverType::LXD]
    }

    fn to_possible_value(&self) -> Option<PossibleValue> {
        Some(match self {
            BuildDriverType::Docker => PossibleValue::new("docker"),
            BuildDriverType::LXD => PossibleValue::new("lxd"),
        })
    }

    fn to_additional_args(&self) -> Vec<Arg> {
        /// map arg values to additionally added further args.
        Some(match self {
            BuildDriverType::Docker => vec![Arg::new("dockerfile"), ...],
            BuildDriverType::LXD => vec![Arg::new("lxc_raw"), ...],
        })
    }
}

fn main() {
    let matches = command!()
        .arg(
            arg!(<driver>)
                .value_parser(value_parser!(BuildDriverType)),
        )
        .get_matches();
    [...]
}

[epage]

I see there was a typo, sorry. BuildSubcommandArgs doesn't need to know about the subargs and just BuildDriverType needs the info, since we basically just "include" more arguments when one enum value is chosen.

I think my statement still stands. Inside of BuildSubcommandArgs, --driver is defined. The possible values for --driver are defined in BuildDriverType. Then for the arguments defined in DockerDriverArgs, we need to say that those depend on --driver <value>.

Regarding the builder API, how about adding to_additonal_args to ValueEnum?:

ValueEnum is part of the derive API.