group of arguments depending on another argument?

[martinetd]

I'm writing a program that can run with different "engines", with a set of common arguments and some engine-specific arguments, e.g. my ideal command line would be as follow:

Usage: testme run [OPTIONS] <TEMPLATE>

Arguments:
  <TEMPLATE>  Template to run

Options:
      --common-arg    Some argument that works with all engines
      --no-defaults      Disable default modules
      --engine <engine>    Engine to use [default: auto] [possible values: auto, engine1, engine2, engine3]
  -h, --help             Print help
  -V, --version          Print version

engine1 options:
     --eng1-opt VAL   Some option for engine1
     --eng12-opt VAL   Option common to engine1 and 2

engine2 options:
     --eng12-opt VAL   Option common to engine1 and 2

# let's say engine3 has no extra options

I don't think that's quite possible as far as help goes, but I'd like to think I could get close behaviour-wise (perhaps with some post-checking...)

I've got something very basic that allows expressing the switches with a sub struct for engine specific options, and I can then check arguments based on engine, but it's all very manual:

• is there a better way to enforce only one of the flatten struct is not None (like arg group? ideally based on the engine option...)
• is there a way to repeat eng12-opt within both flatten structs? if I move it there running panics (rightfully) saying the option is listed twice and clap doesn't know what to do.

Here's code producing the above without grouping in help:

Run thing

Usage: r run [OPTIONS] <TEMPLATE>

Arguments:
  <TEMPLATE>  Template to run

Options:
      --common-arg           Some argument that works with all engines
      --no-defaults          Disable default modules
      --engine <engine>      Hypervisor-specific options [default: auto] [possible values: auto, engine1, engine2, engine3]
      --eng1-opt <eng1-opt>  boot this kernel instead of default one
      --eng2-opt <eng2-opt>  boot this kernel instead of default one
      --eng12-opt            option common to eng1 and 2
  -h, --help                 Print help
  -V, --version              Print version

use clap::{Parser, Subcommand, ValueEnum};
use serde::{Deserialize, Serialize};

#[derive(Parser)]
#[clap(version, about)]
#[clap(propagate_version = true)]
#[clap(subcommand_required = true)]
#[clap(arg_required_else_help = true)]
struct Cli {
    #[clap(subcommand)]
    command: Commands,
}

#[derive(Parser, Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
#[serde(deny_unknown_fields)]
struct Engine1Opts {
    /// boot this kernel instead of default one
    #[clap(name = "eng1-opt", long, required = false)]
    eng1: Option<String>,
}

#[derive(Parser, Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
#[serde(deny_unknown_fields)]
struct Engine2Opts {
    /// boot this kernel instead of default one
    #[clap(name = "eng2-opt", long, required = false)]
    eng2: Option<String>,
}

#[derive(ValueEnum, Clone, Default, Debug)]
enum Engine {
    #[default]
    Auto,
    Engine1,
    Engine2,
    Engine3,
}

#[derive(Subcommand, Debug)]
enum Commands {
    /// Run thing
    Run {
        /// Template to run
        template: String,
        /// Some argument that works with all engines
        #[clap(name = "common-arg", long)]
        common_arg: bool,
        /// Disable default modules
        #[clap(name = "no-defaults", long)]
        no_defaults: bool,
        /// pick one engine
        #[clap(name = "engine", long, default_value_t, value_enum)]
        engine: Engine,
        #[clap(flatten)]
        Engine1Opts: Option<Engine1Opts>,
        #[clap(flatten)]
        Engine2Opts: Option<Engine2Opts>,
        /// option common to eng1 and 2
        #[clap(name = "eng12-opt", long)]
        eng12_opt: bool,
    },
}

fn main() {
    let args = Cli::parse();
    println!("Hello, {:?}", args.command);
}

Note I also experimented with groups for the engine, but:

• if I am to replicate the example, that'd mean making it a struct with booleans, with --engine1 and similar args, which I find less obvious but I can live with that
• I then tried adding requires="engine1" to args within engine1's structs and that appeared to work.. until I noticed passing --engine2 or --engine3 also apparently made clap happy?
  FWIW the structs were then defined as this

#[derive(Args, Clone, Default, Debug)]
#[group(required = false, multiple = false)]
struct Engine {
    #[arg(long)]
    engine1: bool,
    #[arg(long)]
    engine2: bool,
    #[arg(long)]
    engine3: bool,
}

#[derive(Subcommand, Debug)]
enum Commands {
    /// Run thing
    Run {
        /// Template to run
        template: String,
        /// Disable default modules
        #[clap(name = "no-defaults", long)]
        no_defaults: bool,
        /// pick one engine
        #[clap(flatten)]
        engine: Engine,
        #[arg(long, requires = "engine1")]
        eng1-opt: Option<String>,
    },
}

As things stand I'll likely continue with the first approach implementing tests manually even if it's a bit klumsy, but I'm thinking as far as clap goes this would be more natural with subcommands, e.g. testme run --common-arg engine1 --engine1-args template but I'd like testme run --common-arg template to keep working (it's the current CLI) and I couldn't get that to work in the time I had today, it looks possible with a "default subcommand" according to what I'm reading...

[martinetd]

Hmm, here's a variant with a nested subcommand... I had forgotten I had an "eat all" command parameter as well which makes things more annoying.

I don't like two things here:

• I need to repeat template/cmd within the common block and all engines, and code needs to check which has been set if any...
• this makes testme run somearg engine1 morearg valid with engine1 being interpreted as subcommand and both the common and engine1's template being set, which is yet another corner case to check for, for all variants...
• (usability-wise I'd have prefered common args to be allowed later in command as well, at this point I'd just as well repeat common options in all variants of the enum and separate run into run (for engine1) and run-engine2, and give up on autodetection if no specific options were given...)

use clap::{Parser, Subcommand, ValueEnum};
use serde::{Deserialize, Serialize};

#[derive(Parser)]
#[clap(version, about)]
#[clap(propagate_version = true)]
#[clap(subcommand_required = true)]
#[clap(arg_required_else_help = true)]
struct Cli {
    #[clap(subcommand)]
    command: Commands,
}

#[derive(Subcommand, Clone, Debug)]
enum Engine {
    Engine1 {
        /// Template to run
        template: Option<String>,
        /// arguments
        cmd: Vec<String>,
        ///  eng1 opt
        #[clap(name = "eng1-opt", long)]
        eng1: Option<String>,
        ///  eng12 opt
        #[clap(name = "eng12-opt", long)]
        eng12: Option<String>,
    },
    Engine2 {
        /// eng2 opt
        #[clap(name = "eng2-opt", long)]
        eng2: Option<String>,
        ///  eng12 opt
        #[clap(name = "eng12-opt", long)]
        eng12: Option<String>,
    },
    Engine3,
}

#[derive(Subcommand, Debug)]
enum Commands {
    /// Run thing
    Run {
        /// Template to run
        template: Option<String>,
        /// arguments
        cmd: Vec<String>,
        /// Some argument that works with all engines
        #[clap(name = "common-arg", long)]
        common_arg: bool,
        /// Disable default modules
        #[clap(name = "no-defaults", long)]
        no_defaults: bool,
        /// Hypervisor-specific options
        #[clap(subcommand)]
        engine: Option<Engine>,
    },
}

fn main() {
    let args = Cli::parse();
    println!("Hello, {:?}", args.command);
}

Well, this will be enough for today; if someone has any example where something similar to my initial "desired help" has been done that'd be appreciated!

Thanks!

[epage]

I don't think that's quite possible as far as help goes, but I'd like to think I could get close behaviour-wise (perhaps with some post-checking...)

For help, what you want is either help_heading or next_help_heading and you can divide them by engine.

is there a better way to enforce only one of the flatten struct is not None (like arg group? ideally based on the engine option...)

Not at this time. You would at least need #4697 and #2621.

is there a way to repeat eng12-opt within both flatten structs? if I move it there running panics (rightfully) saying the option is listed twice and clap doesn't know what to do.

When we process arguments, we do it with an identifier which is currently only the field name. I might extend it to include the struct name but that won't help here. It would also still require the long flag to be unique.

[martinetd]

Thank you, help heading looks good for grouping!

I'll look at how to check arguments manually after parsing, I think there's not much way around it.