refactor: Rename Arg::conflicts_with_everything to Arg::exclusive (#1583

) (#1624)

#1624 (comment)

examples/05_flag_args.rs

@@ -29,7 +29,7 @@ fn main() {
                 .conflicts_with("output"), // Opposite of requires(), says "if the
                                            // user uses -a, they CANNOT use 'output'"
                                            // also has a conflicts_with_all(Vec<&str>)
-                                           // and a conflicts_with_everything()
+                                           // and a exclusive(true)
         )
         // NOTE: In order to compile this example, comment out requires() and
         // conflicts_with() because we have not defined an "output" or "config"

examples/06_positional_args.rs

@@ -25,7 +25,7 @@ fn main() {
                 .conflicts_with("output") // Opposite of requires(), says "if the
                 // user uses -a, they CANNOT use 'output'"
                 // also has a conflicts_with_all(Vec<&str>)
-                // and a conflicts_with_everything()
+                // and a exclusive(true)
                 .required(true), // By default this argument MUST be present
                                  // NOTE: mutual exclusions take precedence over
                                  // required arguments

examples/07_option_args.rs

@@ -33,7 +33,7 @@ fn main() {
                 .conflicts_with("output"), // Opposite of requires(), says "if the
                                            // user uses -a, they CANNOT use 'output'"
                                            // also has a conflicts_with_all(Vec<&str>)
-                                           // and a conflicts_with_everything()
+                                           // and a exclusive(true)
         )
         // NOTE: In order to compile this example, comment out conflicts_with()
         // and requires() because we have not defined an "output" or "config"

src/build/arg/mod.rs

@@ -785,9 +785,13 @@ impl<'help> Arg<'help> {
     /// only need to be set for one of the two arguments, they do not need to be set for each.
     ///
     /// **NOTE:** Defining a conflict is two-way, but does *not* need to defined for both arguments
-    /// (i.e. if A conflicts with B, defining A.conflicts_with(B) is sufficient. You do not need
+    /// (i.e. if A conflicts with B, defining A.conflicts_with(B) is sufficient. You do not
     /// need to also do B.conflicts_with(A))
     ///
+    /// **NOTE:** [`Arg::conflicts_with_all(names)`] allows specifying an argument which conflicts with more than one argument.
+    ///
+    /// **NOTE** [`Arg::exclusive(true)`] allows specifying an argument which conflicts with every other argument.
+    ///
     /// # Examples
     ///
     /// ```rust
@@ -815,6 +819,10 @@ impl<'help> Arg<'help> {
     /// assert!(res.is_err());
     /// assert_eq!(res.unwrap_err().kind, ErrorKind::ArgumentConflict);
     /// ```
+    ///     
+    /// [`Arg::conflicts_with_all(names)`]: ./struct.Arg.html#method.conflicts_with_all
+    /// [`Arg::exclusive(true)`]: ./struct.Arg.html#method.exclusive
+
     pub fn conflicts_with<T: Key>(mut self, arg_id: T) -> Self {
         let name = arg_id.key();
         if let Some(ref mut vec) = self.blacklist {
@@ -835,6 +843,8 @@ impl<'help> Arg<'help> {
     /// (i.e. if A conflicts with B, defining A.conflicts_with(B) is sufficient. You do not need
     /// need to also do B.conflicts_with(A))
     ///
+    /// **NOTE:** [`Arg::exclusive(true)`] allows specifying an argument which conflicts with every other argument.
+    ///
     /// # Examples
     ///
     /// ```rust
@@ -866,6 +876,8 @@ impl<'help> Arg<'help> {
     /// assert_eq!(res.unwrap_err().kind, ErrorKind::ArgumentConflict);
     /// ```
     /// [`Arg::conflicts_with`]: ./struct.Arg.html#method.conflicts_with
+    /// [`Arg::exclusive(true)`]: ./struct.Arg.html#method.exclusive
+
     pub fn conflicts_with_all(mut self, names: &[&str]) -> Self {
         if let Some(ref mut vec) = self.blacklist {
             for s in names {
@@ -885,7 +897,7 @@ impl<'help> Arg<'help> {
     /// ```rust
     /// # use clap::Arg;
     /// Arg::with_name("config")
-    ///     .conflicts_with_everything()
+    ///     .exclusive(true)
     /// # ;
     /// ```
     /// **NOTE:** If using YAML the above example should be laid out as follows
@@ -903,7 +915,7 @@ impl<'help> Arg<'help> {
     /// let res = App::new("prog")
     ///     .arg(Arg::with_name("exclusive")
     ///         .takes_value(true)
-    ///         .conflicts_with_everything()
+    ///         .exclusive(true)
     ///         .long("exclusive"))
     ///     .arg(Arg::with_name("debug")
     ///         .long("debug"))
@@ -916,8 +928,8 @@ impl<'help> Arg<'help> {
     /// assert!(res.is_err());
     /// assert_eq!(res.unwrap_err().kind, ErrorKind::ArgumentConflict);
     /// ```
-    pub fn conflicts_with_everything(mut self) -> Self {
-        self.exclusive = true;
+    pub fn exclusive(mut self, exclusive: bool) -> Self {
+        self.exclusive = exclusive;
         self
     }
 
@@ -4148,13 +4160,6 @@ impl<'help> Arg<'help> {
             Cow::Borrowed(self.name)
         }
     }
-
-    // Used by yaml
-    #[allow(dead_code)]
-    fn exclusive(mut self, exclusive: bool) -> Self {
-        self.exclusive = exclusive;
-        self
-    }
 }
 
 impl<'help, 'z> From<&'z Arg<'help>> for Arg<'help> {

src/parse/validator.rs

@@ -209,7 +209,7 @@ impl<'b, 'c, 'z> Validator<'b, 'c, 'z> {
 
     fn validate_conflicts(&mut self, matcher: &mut ArgMatcher) -> ClapResult<()> {
         debugln!("Validator::validate_conflicts;");
-        let validate_result = self.validate_conflicts_with_everything(matcher);
+        let validate_result = self.validate_exclusive(matcher);
         if validate_result.is_err() {
             return validate_result;
         }
@@ -261,8 +261,8 @@ impl<'b, 'c, 'z> Validator<'b, 'c, 'z> {
         Ok(())
     }
 
-    fn validate_conflicts_with_everything(&mut self, matcher: &mut ArgMatcher) -> ClapResult<()> {
-        debugln!("Validator::validate_conflicts_with_everything;");
+    fn validate_exclusive(&mut self, matcher: &mut ArgMatcher) -> ClapResult<()> {
+        debugln!("Validator::validate_exclusive;");
         let args_count = matcher.arg_names().count();
         for &name in matcher.arg_names() {
             debugln!(

tests/conflicts.rs

@@ -55,7 +55,7 @@ fn flag_conflict_with_all() {
 #[test]
 fn flag_conflict_with_everything() {
     let result = App::new("flag_conflict")
-        .arg(Arg::from("-f, --flag 'some flag'").conflicts_with_everything())
+        .arg(Arg::from("-f, --flag 'some flag'").exclusive(true))
         .arg(Arg::from("-o, --other 'some flag'"))
         .try_get_matches_from(vec!["myprog", "-o", "-f"]);
     assert!(result.is_err());