Merge pull request #5688 from epage/rename

fix(complete)!: Rename Custom completer

Author: epage

clap_complete/src/command/mod.rs

@@ -49,7 +49,7 @@ pub use shells::*;
 /// To customize completions, see
 /// - [`ValueHint`][crate::ValueHint]
 /// - [`ValueEnum`][clap::ValueEnum]
-/// - [`ArgValueCompleter`][crate::ArgValueCompleter]
+/// - [`ArgValueCandidates`][crate::ArgValueCandidates]
 ///
 /// **Warning:** `stdout` should not be written to before [`CompleteCommand::complete`] has had a
 /// chance to run.
@@ -121,7 +121,7 @@ impl CompleteCommand {
 /// To customize completions, see
 /// - [`ValueHint`][crate::ValueHint]
 /// - [`ValueEnum`][clap::ValueEnum]
-/// - [`ArgValueCompleter`][crate::ArgValueCompleter]
+/// - [`ArgValueCandidates`][crate::ArgValueCandidates]
 ///
 /// **Warning:** `stdout` should not be written to before [`CompleteArgs::complete`] has had a
 /// chance to run.

clap_complete/src/engine/complete.rs

@@ -3,7 +3,7 @@ use std::ffi::OsString;
 
 use clap_lex::OsStrExt as _;
 
-use super::ArgValueCompleter;
+use super::ArgValueCandidates;
 use super::CompletionCandidate;
 
 /// Complete the given command, shell-agnostic
@@ -270,7 +270,7 @@ fn complete_arg_value(
         Err(value_os) => value_os,
     };
 
-    if let Some(completer) = arg.get::<ArgValueCompleter>() {
+    if let Some(completer) = arg.get::<ArgValueCandidates>() {
         values.extend(complete_custom_arg_value(value_os, completer));
     } else if let Some(possible_values) = possible_values(arg) {
         if let Ok(value) = value {
@@ -394,7 +394,7 @@ fn complete_path(
 
 fn complete_custom_arg_value(
     value: &OsStr,
-    completer: &ArgValueCompleter,
+    completer: &ArgValueCandidates,
 ) -> Vec<CompletionCandidate> {
     debug!("complete_custom_arg_value: completer={completer:?}, value={value:?}");
 

clap_complete/src/engine/custom.rs

@@ -5,31 +5,31 @@ use clap::builder::ArgExt;
 
 use super::CompletionCandidate;
 
-/// Extend [`Arg`][clap::Arg] with a [`CustomCompleter`]
+/// Extend [`Arg`][clap::Arg] with a [`ValueCandidates`]
 ///
 /// # Example
 ///
 /// ```rust
 /// use clap::Parser;
-/// use clap_complete::engine::{ArgValueCompleter, CompletionCandidate};
+/// use clap_complete::engine::{ArgValueCandidates, CompletionCandidate};
 ///
 /// #[derive(Debug, Parser)]
 /// struct Cli {
-///     #[arg(long, add = ArgValueCompleter::new(|| { vec![
+///     #[arg(long, add = ArgValueCandidates::new(|| { vec![
 ///         CompletionCandidate::new("foo"),
 ///         CompletionCandidate::new("bar"),
 ///         CompletionCandidate::new("baz")] }))]
 ///     custom: Option<String>,
 /// }
 /// ```
 #[derive(Clone)]
-pub struct ArgValueCompleter(Arc<dyn CustomCompleter>);
+pub struct ArgValueCandidates(Arc<dyn ValueCandidates>);
 
-impl ArgValueCompleter {
-    /// Create a new `ArgValueCompleter` with a custom completer
+impl ArgValueCandidates {
+    /// Create a new `ArgValueCandidates` with a custom completer
     pub fn new<C>(completer: C) -> Self
     where
-        C: CustomCompleter + 'static,
+        C: ValueCandidates + 'static,
     {
         Self(Arc::new(completer))
     }
@@ -42,25 +42,25 @@ impl ArgValueCompleter {
     }
 }
 
-impl std::fmt::Debug for ArgValueCompleter {
+impl std::fmt::Debug for ArgValueCandidates {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
         f.write_str(type_name::<Self>())
     }
 }
 
-impl ArgExt for ArgValueCompleter {}
+impl ArgExt for ArgValueCandidates {}
 
-/// User-provided completion candidates for an [`Arg`][clap::Arg], see [`ArgValueCompleter`]
+/// User-provided completion candidates for an [`Arg`][clap::Arg], see [`ArgValueCandidates`]
 ///
 /// This is useful when predefined value hints are not enough.
-pub trait CustomCompleter: Send + Sync {
+pub trait ValueCandidates: Send + Sync {
     /// All potential candidates for an argument.
     ///
     /// See [`CompletionCandidate`] for more information.
     fn candidates(&self) -> Vec<CompletionCandidate>;
 }
 
-impl<F> CustomCompleter for F
+impl<F> ValueCandidates for F
 where
     F: Fn() -> Vec<CompletionCandidate> + Send + Sync,
 {

clap_complete/src/engine/mod.rs

@@ -8,5 +8,5 @@ mod custom;
 
 pub use candidate::CompletionCandidate;
 pub use complete::complete;
-pub use custom::ArgValueCompleter;
-pub use custom::CustomCompleter;
+pub use custom::ArgValueCandidates;
+pub use custom::ValueCandidates;

clap_complete/src/env/mod.rs

@@ -19,7 +19,7 @@
 //! To customize completions, see
 //! - [`ValueHint`][crate::ValueHint]
 //! - [`ValueEnum`][clap::ValueEnum]
-//! - [`ArgValueCompleter`][crate::ArgValueCompleter]
+//! - [`ArgValueCandidates`][crate::ArgValueCandidates]
 //!
 //! To source your completions:
 //!

clap_complete/src/lib.rs

@@ -80,7 +80,7 @@ pub use command::CompleteArgs;
 pub use command::CompleteCommand;
 #[doc(inline)]
 #[cfg(feature = "unstable-dynamic")]
-pub use engine::ArgValueCompleter;
+pub use engine::ArgValueCandidates;
 #[doc(inline)]
 #[cfg(feature = "unstable-dynamic")]
 pub use engine::CompletionCandidate;

clap_complete/tests/testsuite/engine.rs

@@ -4,7 +4,7 @@ use std::fs;
 use std::path::Path;
 
 use clap::{builder::PossibleValue, Command};
-use clap_complete::engine::{ArgValueCompleter, CompletionCandidate, CustomCompleter};
+use clap_complete::engine::{ArgValueCandidates, CompletionCandidate, ValueCandidates};
 use snapbox::assert_data_eq;
 
 macro_rules! complete {
@@ -596,7 +596,7 @@ fn suggest_custom_arg_value() {
     #[derive(Debug)]
     struct MyCustomCompleter {}
 
-    impl CustomCompleter for MyCustomCompleter {
+    impl ValueCandidates for MyCustomCompleter {
         fn candidates(&self) -> Vec<CompletionCandidate> {
             vec![
                 CompletionCandidate::new("custom1"),
@@ -609,7 +609,7 @@ fn suggest_custom_arg_value() {
     let mut cmd = Command::new("dynamic").arg(
         clap::Arg::new("custom")
             .long("custom")
-            .add::<ArgValueCompleter>(ArgValueCompleter::new(MyCustomCompleter {})),
+            .add::<ArgValueCandidates>(ArgValueCandidates::new(MyCustomCompleter {})),
     );
 
     assert_data_eq!(