name implies a user-facing meaning, causing confusion

[pwinckles]

Maintainer's notes:

• The root cause was confusion over name vs value_name and impact on the rest of the API
• We should look into renaming Arg::name to Arg::id
• We should also resolve clap_derive casing change stringly type #2475 which is possible because we (should be) setting value_name on people's behalf.

---

Please complete the following tasks

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

Rust Version

rustc 1.58.1 (db9d1b20b 2022-01-20)

Clap Version

3.0.10

Minimal reproducible code

use clap::Parser;

#[derive(Debug, Parser)]
pub struct Example {
    #[clap(short = 'S', long, conflicts_with = "version")]
    pub staged: bool,

    #[clap(name = "OBJ_ID")]
    pub object_id: String,

    #[clap(name = "VERSION")]
    pub version: Option<String>,
}

fn main() {
    println!("{:?}", Example::parse());
}

Steps to reproduce the bug with the above code

cargo run -- asdf

Actual Behaviour

Panics:

thread 'main' panicked at 'App clap-example: Argument or group 'version' specified in 'conflicts_with*' for 'staged' does not exist', /home/pwinckles/.cargo/registry/src/github.com-1ecc6299db9ec823/clap-3.0.10/src/build/app/debug_asserts.rs:171:13

Expected Behaviour

It should not panic. I would expect Clap to enforce that the staged flag cannot be set if a version positional arg is provided, and otherwise allow the flag to be present or not.

Additional Context

conflicts_with works as expected when conflicting with another flag. The problem seems to be when conflicting with an optional positional arg.

Debug Output

[            clap::build::app] 	App::_do_parse
[            clap::build::app] 	App::_build
[            clap::build::app] 	App::_propagate:clap-example
[            clap::build::app] 	App::_check_help_and_version
[            clap::build::app] 	App::_check_help_and_version: Removing generated version
[            clap::build::app] 	App::_propagate_global_args:clap-example
[            clap::build::app] 	App::_derive_display_order:clap-example
[clap::build::app::debug_asserts] 	App::_debug_asserts
[clap::build::arg::debug_asserts] 	Arg::_debug_asserts:help
[clap::build::arg::debug_asserts] 	Arg::_debug_asserts:staged

[epage]

use clap::Parser;

#[derive(Debug, Parser)]
pub struct Example {
    #[clap(short = 'S', long, conflicts_with = "version")]
    pub staged: bool,

    #[clap(name = "OBJ_ID")]
    pub object_id: String,

    #[clap(name = "VERSION")]
    pub version: Option<String>,
}

fn main() {
    println!("{:?}", Example::parse());
}

should be

use clap::Parser;

#[derive(Debug, Parser)]
pub struct Example {
    #[clap(short = 'S', long, conflicts_with = "VERSION")]
    pub staged: bool,

    #[clap(name = "OBJ_ID")]
    pub object_id: String,

    #[clap(name = "VERSION")]
    pub version: Option<String>,
}

fn main() {
    println!("{:?}", Example::parse());
}

With name, you overrode the ID for referencing the version argument within clap, so you need to update references to that ID as well.

Most likely what you want is value_name instead of name (we do default value_name based on name).

use clap::Parser;

#[derive(Debug, Parser)]
pub struct Example {
    #[clap(short = 'S', long, conflicts_with = "version")]
    pub staged: bool,

    #[clap(value_name = "OBJ_ID")]
    pub object_id: String,

    #[clap(value_name = "VERSION")]
    pub version: Option<String>,
}

fn main() {
    println!("{:?}", Example::parse());
}

This kind of confusion is why I want to rename it from name to id.

[pwinckles]

😊

Thank you! You are correct that I was confusing name with value_name. Sorry for the trouble.

[epage]

Keeping this open as a use case for why we should explore changing Arg::name.

[pwinckles]

For what it's worth, I experienced the issue because I migrated from clap 2 + structopt, and structopt includes an example like the following in its docs:

    /// File name: only required when `out-type` is set to `file`
    #[structopt(name = "FILE", required_if("out-type", "file"))]
    file_name: Option<String>,

I looked at the docs for clap 3, and I do think it's clear what name does, though I agree that it isn't intuitive without reading the docs.