mirror of
https://github.com/clap-rs/clap
synced 2024-12-13 22:32:33 +00:00
1cdb2250e8
Before:
- `bool`: a flag
- `Option<_>`: not required
- `Option<Option<_>>` is not required and when it is present, the value
is not required
- `Vec<_>`: multiple values, optional
- `Option<Vec<_>>`: multiple values, min values of 0, optional
After:
- `bool`: a flag
- `Option<_>`: not required
- `Option<Option<_>>` is not required and when it is present, the value
is not required
- `Vec<_>`: multiple occurrences, optional
- optional: `Vec` implies 0 or more, so should not imply required
- `Option<Vec<_>>`: multiple occurrences, optional
- optional: Use over `Vec` to detect when no option being present when
using multiple values
Motivations:
My priorities were:
1. Are we getting in the users way?
2. Does the API make sense?
3. Does the API encourage best practices?
I was originally concerned about the lack of composability with
`Option<Option<_>>` and `Option<Vec<_>>` (and eventually `Vec<Vec<_>>`).
It prescribes special meaning to each type depending on where it shows
up, rather than providing a single meaning for a type generally. You
then can't do things like have `Option<_>` mean "required argument with
optional value" without hand constructing it. However, in practice the
outer type correlates with the argument occurrence and the inner type
with the value. It is rare to want the value behavior without also the
occurrence behavior. So I figure it is probably fine as long as people
can set the flags to manually get the behavior they want.
`Vec<_>` implies multiple occurrences, rather than multiple values.
Anecdotally, whenever I've used the old `Arg::multiple`, I thought I was
getting `Arg::multiple_occurrences` only. `Arg::multiple_values`,
without any bounds or delimiter requirement, can lead to a confusing
user experience and isn't a good default for these. On top of that, if
someone does have an unbounded or a delimiter multiple values, they are
probably also using multiple occurrences.
`Vec<_>` is optional because a `Vec` implies 0 or more, so we stick to
the meaning of the rust type. At least for me, I also rarely need a
required with multiple occurrences argument but more often need optional
with multiple occurrences.
`Option<Vec<_>>` ends up matching `Vec<_>` which can raise the question
of why have it. Some users might prefer the type. Otherwise, this is
so users can detect whether the argument is present or not when using
`min_values(0)`. Rather than defining an entire policy around this and
having users customize it, or setting `min_values(0)` without the rest
of a default policy, this gives people a blank slate to work from.
Another design option would have been to not infer any special-type
settings if someone sets a handful of settings manually, which would
have avoided the confusion in Issue clap-rs/clap 2599 but I see that
being confusing (for someone who knows the default, they will be
expecting it to be additive; which flags disable inferred settings?) and
brittle (as flags are added or changed, how do we ensure we keep this
up?).
Tests were added to ensure we support people customizing the behavior to
match their needs.
This is not solving:
- `Vec<Vec<_>>`, see clap-rs/clap 2924
- `(T1, T2)`, `Vec<(T1, T2)>`, etc, see clap-rs/clap 1717
- `Vec<Option<_>>` and many other potential combinations
Fixes clap-rs/clap 1772
Fixes clap-rs/clap 2599
See also clap-rs/clap 2195
423 lines
10 KiB
Rust
423 lines
10 KiB
Rust
// Copyright 2018 Guillaume Pinot (@TeXitoi) <texitoi@texitoi.eu>,
|
|
// Kevin Knapp (@kbknapp) <kbknapp@gmail.com>, and
|
|
// Andrew Hobden (@hoverbear) <andrew@hoverbear.org>
|
|
//
|
|
// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
|
|
// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
|
|
// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
|
|
// option. This file may not be copied, modified, or distributed
|
|
// except according to those terms.
|
|
//
|
|
// This work was derived from Structopt (https://github.com/TeXitoi/structopt)
|
|
// commit#ea76fa1b1b273e65e3b0b1046643715b49bec51f which is licensed under the
|
|
// MIT/Apache 2.0 license.
|
|
|
|
#![allow(clippy::option_option)]
|
|
|
|
mod utils;
|
|
|
|
use clap::{Parser, Subcommand};
|
|
use utils::*;
|
|
|
|
#[test]
|
|
fn required_option() {
|
|
#[derive(Parser, PartialEq, Debug)]
|
|
struct Opt {
|
|
#[clap(short, long)]
|
|
arg: i32,
|
|
}
|
|
assert_eq!(
|
|
Opt { arg: 42 },
|
|
Opt::try_parse_from(&["test", "-a42"]).unwrap()
|
|
);
|
|
assert_eq!(
|
|
Opt { arg: 42 },
|
|
Opt::try_parse_from(&["test", "-a", "42"]).unwrap()
|
|
);
|
|
assert_eq!(
|
|
Opt { arg: 42 },
|
|
Opt::try_parse_from(&["test", "--arg", "42"]).unwrap()
|
|
);
|
|
assert!(Opt::try_parse_from(&["test"]).is_err());
|
|
assert!(Opt::try_parse_from(&["test", "-a42", "-a24"]).is_err());
|
|
}
|
|
|
|
#[test]
|
|
fn option_with_default() {
|
|
#[derive(Parser, PartialEq, Debug)]
|
|
struct Opt {
|
|
#[clap(short, default_value = "42")]
|
|
arg: i32,
|
|
}
|
|
assert_eq!(
|
|
Opt { arg: 24 },
|
|
Opt::try_parse_from(&["test", "-a24"]).unwrap()
|
|
);
|
|
assert_eq!(Opt { arg: 42 }, Opt::try_parse_from(&["test"]).unwrap());
|
|
assert!(Opt::try_parse_from(&["test", "-a42", "-a24"]).is_err());
|
|
}
|
|
|
|
#[test]
|
|
fn option_with_raw_default() {
|
|
#[derive(Parser, PartialEq, Debug)]
|
|
struct Opt {
|
|
#[clap(short, default_value = "42")]
|
|
arg: i32,
|
|
}
|
|
assert_eq!(
|
|
Opt { arg: 24 },
|
|
Opt::try_parse_from(&["test", "-a24"]).unwrap()
|
|
);
|
|
assert_eq!(Opt { arg: 42 }, Opt::try_parse_from(&["test"]).unwrap());
|
|
assert!(Opt::try_parse_from(&["test", "-a42", "-a24"]).is_err());
|
|
}
|
|
|
|
#[test]
|
|
fn option_from_str() {
|
|
#[derive(Debug, PartialEq)]
|
|
struct A;
|
|
|
|
impl<'a> From<&'a str> for A {
|
|
fn from(_: &str) -> A {
|
|
A
|
|
}
|
|
}
|
|
|
|
#[derive(Debug, Parser, PartialEq)]
|
|
struct Opt {
|
|
#[clap(parse(from_str))]
|
|
a: Option<A>,
|
|
}
|
|
|
|
assert_eq!(Opt { a: None }, Opt::try_parse_from(&["test"]).unwrap());
|
|
assert_eq!(
|
|
Opt { a: Some(A) },
|
|
Opt::try_parse_from(&["test", "foo"]).unwrap()
|
|
);
|
|
}
|
|
|
|
#[test]
|
|
fn option_type_is_optional() {
|
|
#[derive(Parser, PartialEq, Debug)]
|
|
struct Opt {
|
|
#[clap(short)]
|
|
arg: Option<i32>,
|
|
}
|
|
assert_eq!(
|
|
Opt { arg: Some(42) },
|
|
Opt::try_parse_from(&["test", "-a42"]).unwrap()
|
|
);
|
|
assert_eq!(Opt { arg: None }, Opt::try_parse_from(&["test"]).unwrap());
|
|
assert!(Opt::try_parse_from(&["test", "-a42", "-a24"]).is_err());
|
|
}
|
|
|
|
#[test]
|
|
fn required_with_option_type() {
|
|
#[derive(Debug, PartialEq, Eq, Parser)]
|
|
#[clap(setting(clap::AppSettings::SubcommandsNegateReqs))]
|
|
struct Opt {
|
|
#[clap(required = true)]
|
|
req_str: Option<String>,
|
|
|
|
#[clap(subcommand)]
|
|
cmd: Option<SubCommands>,
|
|
}
|
|
|
|
#[derive(Debug, PartialEq, Eq, Subcommand)]
|
|
enum SubCommands {
|
|
ExSub {
|
|
#[clap(short, long, parse(from_occurrences))]
|
|
verbose: u8,
|
|
},
|
|
}
|
|
|
|
assert_eq!(
|
|
Opt {
|
|
req_str: Some(("arg").into()),
|
|
cmd: None,
|
|
},
|
|
Opt::try_parse_from(&["test", "arg"]).unwrap()
|
|
);
|
|
|
|
assert_eq!(
|
|
Opt {
|
|
req_str: None,
|
|
cmd: Some(SubCommands::ExSub { verbose: 1 }),
|
|
},
|
|
Opt::try_parse_from(&["test", "ex-sub", "-v"]).unwrap()
|
|
);
|
|
|
|
assert!(Opt::try_parse_from(&["test"]).is_err());
|
|
}
|
|
|
|
#[test]
|
|
fn ignore_qualified_option_type() {
|
|
fn parser(s: &str) -> Option<String> {
|
|
Some(s.to_string())
|
|
}
|
|
|
|
#[derive(Parser, PartialEq, Debug)]
|
|
struct Opt {
|
|
#[clap(parse(from_str = parser))]
|
|
arg: ::std::option::Option<String>,
|
|
}
|
|
|
|
assert_eq!(
|
|
Opt {
|
|
arg: Some("success".into())
|
|
},
|
|
Opt::try_parse_from(&["test", "success"]).unwrap()
|
|
);
|
|
}
|
|
|
|
#[test]
|
|
fn option_option_type_is_optional_value() {
|
|
#[derive(Parser, PartialEq, Debug)]
|
|
struct Opt {
|
|
#[clap(short, multiple_occurrences(true))]
|
|
#[allow(clippy::option_option)]
|
|
arg: Option<Option<i32>>,
|
|
}
|
|
assert_eq!(
|
|
Opt {
|
|
arg: Some(Some(42))
|
|
},
|
|
Opt::try_parse_from(&["test", "-a42"]).unwrap()
|
|
);
|
|
assert_eq!(
|
|
Opt { arg: Some(None) },
|
|
Opt::try_parse_from(&["test", "-a"]).unwrap()
|
|
);
|
|
assert_eq!(Opt { arg: None }, Opt::try_parse_from(&["test"]).unwrap());
|
|
assert!(Opt::try_parse_from(&["test", "-a42", "-a24"]).is_err());
|
|
}
|
|
|
|
#[test]
|
|
fn option_option_type_help() {
|
|
#[derive(Parser, Debug)]
|
|
struct Opt {
|
|
#[clap(long, value_name = "val")]
|
|
arg: Option<Option<i32>>,
|
|
}
|
|
let help = get_help::<Opt>();
|
|
assert!(help.contains("--arg <val>"));
|
|
assert!(!help.contains("--arg <val>..."));
|
|
}
|
|
|
|
#[test]
|
|
fn two_option_option_types() {
|
|
#[derive(Parser, PartialEq, Debug)]
|
|
struct Opt {
|
|
#[clap(short)]
|
|
arg: Option<Option<i32>>,
|
|
|
|
#[clap(long)]
|
|
field: Option<Option<String>>,
|
|
}
|
|
assert_eq!(
|
|
Opt {
|
|
arg: Some(Some(42)),
|
|
field: Some(Some("f".into()))
|
|
},
|
|
Opt::try_parse_from(&["test", "-a42", "--field", "f"]).unwrap()
|
|
);
|
|
assert_eq!(
|
|
Opt {
|
|
arg: Some(Some(42)),
|
|
field: Some(None)
|
|
},
|
|
Opt::try_parse_from(&["test", "-a42", "--field"]).unwrap()
|
|
);
|
|
assert_eq!(
|
|
Opt {
|
|
arg: Some(None),
|
|
field: Some(None)
|
|
},
|
|
Opt::try_parse_from(&["test", "-a", "--field"]).unwrap()
|
|
);
|
|
assert_eq!(
|
|
Opt {
|
|
arg: Some(None),
|
|
field: Some(Some("f".into()))
|
|
},
|
|
Opt::try_parse_from(&["test", "-a", "--field", "f"]).unwrap()
|
|
);
|
|
assert_eq!(
|
|
Opt {
|
|
arg: None,
|
|
field: Some(None)
|
|
},
|
|
Opt::try_parse_from(&["test", "--field"]).unwrap()
|
|
);
|
|
assert_eq!(
|
|
Opt {
|
|
arg: None,
|
|
field: None
|
|
},
|
|
Opt::try_parse_from(&["test"]).unwrap()
|
|
);
|
|
}
|
|
|
|
#[test]
|
|
fn vec_type_is_multiple_occurrences() {
|
|
#[derive(Parser, PartialEq, Debug)]
|
|
struct Opt {
|
|
#[clap(short, long)]
|
|
arg: Vec<i32>,
|
|
}
|
|
assert_eq!(
|
|
Opt { arg: vec![24] },
|
|
Opt::try_parse_from(&["test", "-a24"]).unwrap()
|
|
);
|
|
assert_eq!(Opt { arg: vec![] }, Opt::try_parse_from(&["test"]).unwrap());
|
|
assert_eq!(
|
|
Opt { arg: vec![24, 42] },
|
|
Opt::try_parse_from(&["test", "-a", "24", "-a", "42"]).unwrap()
|
|
);
|
|
}
|
|
|
|
#[test]
|
|
fn vec_type_with_required() {
|
|
#[derive(Parser, PartialEq, Debug)]
|
|
struct Opt {
|
|
#[clap(short, long, required = true)]
|
|
arg: Vec<i32>,
|
|
}
|
|
assert_eq!(
|
|
Opt { arg: vec![24] },
|
|
Opt::try_parse_from(&["test", "-a24"]).unwrap()
|
|
);
|
|
assert!(Opt::try_parse_from(&["test"]).is_err());
|
|
assert_eq!(
|
|
Opt { arg: vec![24, 42] },
|
|
Opt::try_parse_from(&["test", "-a", "24", "-a", "42"]).unwrap()
|
|
);
|
|
}
|
|
|
|
#[test]
|
|
fn vec_type_with_multiple_values_only() {
|
|
#[derive(Parser, PartialEq, Debug)]
|
|
struct Opt {
|
|
#[clap(short, long, multiple_values(true), multiple_occurrences(false))]
|
|
arg: Vec<i32>,
|
|
}
|
|
assert_eq!(
|
|
Opt { arg: vec![24] },
|
|
Opt::try_parse_from(&["test", "-a24"]).unwrap()
|
|
);
|
|
assert_eq!(Opt { arg: vec![] }, Opt::try_parse_from(&["test"]).unwrap());
|
|
assert_eq!(
|
|
Opt { arg: vec![24, 42] },
|
|
Opt::try_parse_from(&["test", "-a", "24", "42"]).unwrap()
|
|
);
|
|
}
|
|
|
|
#[test]
|
|
fn ignore_qualified_vec_type() {
|
|
fn parser(s: &str) -> Vec<String> {
|
|
vec![s.to_string()]
|
|
}
|
|
|
|
#[derive(Parser, PartialEq, Debug)]
|
|
struct Opt {
|
|
#[clap(parse(from_str = parser))]
|
|
arg: ::std::vec::Vec<String>,
|
|
}
|
|
|
|
assert_eq!(
|
|
Opt {
|
|
arg: vec!["success".into()]
|
|
},
|
|
Opt::try_parse_from(&["test", "success"]).unwrap()
|
|
);
|
|
}
|
|
|
|
#[test]
|
|
fn option_vec_type() {
|
|
#[derive(Parser, PartialEq, Debug)]
|
|
struct Opt {
|
|
#[clap(short)]
|
|
arg: Option<Vec<i32>>,
|
|
}
|
|
assert_eq!(
|
|
Opt { arg: Some(vec![1]) },
|
|
Opt::try_parse_from(&["test", "-a", "1"]).unwrap()
|
|
);
|
|
|
|
assert_eq!(
|
|
Opt {
|
|
arg: Some(vec![1, 2])
|
|
},
|
|
Opt::try_parse_from(&["test", "-a", "1", "-a", "2"]).unwrap()
|
|
);
|
|
|
|
assert_eq!(Opt { arg: None }, Opt::try_parse_from(&["test"]).unwrap());
|
|
}
|
|
|
|
#[test]
|
|
fn option_vec_type_structopt_behavior() {
|
|
#[derive(Parser, PartialEq, Debug)]
|
|
struct Opt {
|
|
#[clap(short, long, multiple_values(true), min_values(0))]
|
|
arg: Option<Vec<i32>>,
|
|
}
|
|
assert_eq!(
|
|
Opt { arg: Some(vec![1]) },
|
|
Opt::try_parse_from(&["test", "-a", "1"]).unwrap()
|
|
);
|
|
|
|
assert_eq!(
|
|
Opt {
|
|
arg: Some(vec![1, 2])
|
|
},
|
|
Opt::try_parse_from(&["test", "-a", "1", "2"]).unwrap()
|
|
);
|
|
|
|
assert_eq!(
|
|
Opt { arg: Some(vec![]) },
|
|
Opt::try_parse_from(&["test", "-a"]).unwrap()
|
|
);
|
|
|
|
assert_eq!(Opt { arg: None }, Opt::try_parse_from(&["test"]).unwrap());
|
|
}
|
|
|
|
#[test]
|
|
fn two_option_vec_types() {
|
|
#[derive(Parser, PartialEq, Debug)]
|
|
struct Opt {
|
|
#[clap(short)]
|
|
arg: Option<Vec<i32>>,
|
|
|
|
#[clap(short)]
|
|
b: Option<Vec<i32>>,
|
|
}
|
|
|
|
assert_eq!(
|
|
Opt {
|
|
arg: Some(vec![1]),
|
|
b: None,
|
|
},
|
|
Opt::try_parse_from(&["test", "-a", "1"]).unwrap()
|
|
);
|
|
|
|
assert_eq!(
|
|
Opt {
|
|
arg: Some(vec![1]),
|
|
b: Some(vec![1])
|
|
},
|
|
Opt::try_parse_from(&["test", "-a", "1", "-b", "1"]).unwrap()
|
|
);
|
|
|
|
assert_eq!(
|
|
Opt {
|
|
arg: Some(vec![1, 2]),
|
|
b: Some(vec![1, 2])
|
|
},
|
|
Opt::try_parse_from(&["test", "-a", "1", "-a", "2", "-b", "1", "-b", "2"]).unwrap()
|
|
);
|
|
|
|
assert_eq!(
|
|
Opt { arg: None, b: None },
|
|
Opt::try_parse_from(&["test"]).unwrap()
|
|
);
|
|
}
|