feat(complete): Support to complete custom external subcommand

Author: shannmu

clap_builder/src/builder/command.rs

@@ -1039,6 +1039,14 @@ impl Command {
 
         Usage::new(self).create_usage_with_title(&[])
     }
+
+    /// Extend [`Command`] with [`CommandExt`] data
+    #[cfg(feature = "unstable-ext")]
+    #[allow(clippy::should_implement_trait)]
+    pub fn add<T: CommandExt + crate::builder::ext::Extension>(mut self, tagged: T) -> Self {
+        self.app_ext.set(tagged);
+        self
+    }
 }
 
 /// # Application-wide Settings
@@ -3958,6 +3966,18 @@ impl Command {
     pub fn is_multicall_set(&self) -> bool {
         self.is_set(AppSettings::Multicall)
     }
+
+    /// Access an [`CommandExt`]
+    #[cfg(feature = "unstable-ext")]
+    pub fn get<T: CommandExt + crate::builder::ext::Extension>(&self) -> Option<&T> {
+        self.app_ext.get::<T>()
+    }
+
+    /// Remove an [`CommandExt`]
+    #[cfg(feature = "unstable-ext")]
+    pub fn remove<T: CommandExt + crate::builder::ext::Extension>(mut self) -> Option<T> {
+        self.app_ext.remove::<T>()
+    }
 }
 
 // Internally used only
@@ -4921,6 +4941,10 @@ struct MaxTermWidth(usize);
 
 impl AppTag for MaxTermWidth {}
 
+/// User-provided data that can be attached to an [`Command`]
+#[cfg(feature = "unstable-ext")]
+pub trait CommandExt: crate::builder::ext::Extension {}
+
 fn two_elements_of<I, T>(mut iter: I) -> Option<(T, T)>
 where
     I: Iterator<Item = T>,

clap_builder/src/builder/mod.rs

@@ -33,6 +33,7 @@ pub use arg::ArgExt;
 pub use arg_group::ArgGroup;
 pub use arg_predicate::ArgPredicate;
 pub use command::Command;
+pub use command::CommandExt;
 pub use os_str::OsStr;
 pub use possible_value::PossibleValue;
 pub use range::ValueRange;

clap_complete/src/engine/complete.rs

@@ -7,6 +7,7 @@ use super::custom::complete_path;
 use super::ArgValueCandidates;
 use super::ArgValueCompleter;
 use super::CompletionCandidate;
+use super::SubcommandCandidates;
 
 /// Complete the given command, shell-agnostic
 pub fn complete(
@@ -363,11 +364,31 @@ fn complete_subcommand(value: &str, cmd: &clap::Command) -> Vec<CompletionCandid
         .into_iter()
         .filter(|x| x.get_value().starts_with(value))
         .collect::<Vec<_>>();
+
+    let external_completer = cmd.get::<SubcommandCandidates>();
+    if let Some(completer) = external_completer {
+        scs.extend(complete_external_subcommand(value, completer));
+    }
     scs.sort();
     scs.dedup();
     scs
 }
 
+fn complete_external_subcommand(
+    value: &str,
+    completer: &SubcommandCandidates,
+) -> Vec<CompletionCandidate> {
+    debug!("complete_custom_arg_value: completer={completer:?}, value={value:?}");
+
+    let mut values = Vec::new();
+    let custom_arg_values = completer.candidates();
+    values.extend(custom_arg_values);
+
+    values.retain(|comp| comp.get_value().starts_with(value));
+
+    values
+}
+
 /// Gets all the long options, their visible aliases and flags of a [`clap::Command`] with formatted `--` prefix.
 /// Includes `help` and `version` depending on the [`clap::Command`] settings.
 fn longs_and_visible_aliases(p: &clap::Command) -> Vec<CompletionCandidate> {

clap_complete/src/engine/custom.rs

@@ -3,6 +3,7 @@ use std::ffi::OsStr;
 use std::sync::Arc;
 
 use clap::builder::ArgExt;
+use clap::builder::CommandExt;
 use clap_lex::OsStrExt as _;
 
 use super::CompletionCandidate;
@@ -52,8 +53,54 @@ impl std::fmt::Debug for ArgValueCandidates {
 
 impl ArgExt for ArgValueCandidates {}
 
+/// Extend [`Command`][clap::Command] with a [`ValueCandidates`]
+///
+/// # Example
+/// ```rust
+/// use clap::Parser;
+/// use clap_complete::engine::{SubcommandCandidates, CompletionCandidate};
+/// #[derive(Debug, Parser)]
+/// #[clap(name = "cli", add = SubcommandCandidates::new(|| { vec![
+///     CompletionCandidate::new("foo"),
+///     CompletionCandidate::new("bar"),
+///     CompletionCandidate::new("baz")] }))]
+/// struct Cli {
+///     #[arg(long)]
+///     input: Option<String>,
+/// }
+/// ```
+#[derive(Clone)]
+pub struct SubcommandCandidates(Arc<dyn ValueCandidates>);
+
+impl SubcommandCandidates {
+    /// Create a new `SubcommandCandidates` with a custom completer
+    pub fn new<C>(completer: C) -> Self
+    where
+        C: ValueCandidates + 'static,
+    {
+        Self(Arc::new(completer))
+    }
+
+    /// All potential candidates for an external subcommand.
+    ///
+    /// See [`CompletionCandidate`] for more information.
+    pub fn candidates(&self) -> Vec<CompletionCandidate> {
+        self.0.candidates()
+    }
+}
+
+impl std::fmt::Debug for SubcommandCandidates {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str(type_name::<Self>())
+    }
+}
+
+impl CommandExt for SubcommandCandidates {}
+
 /// User-provided completion candidates for an [`Arg`][clap::Arg], see [`ArgValueCandidates`]
 ///
+/// User-provided completion candidates for an [`Subcommand`][clap::Subcommand], see [`SubcommandCandidates`]
+///
 /// This is useful when predefined value hints are not enough.
 pub trait ValueCandidates: Send + Sync {
     /// All potential candidates for an argument.

clap_complete/src/engine/mod.rs

@@ -11,5 +11,6 @@ pub use complete::complete;
 pub use custom::ArgValueCandidates;
 pub use custom::ArgValueCompleter;
 pub use custom::PathCompleter;
+pub use custom::SubcommandCandidates;
 pub use custom::ValueCandidates;
 pub use custom::ValueCompleter;

clap_complete/tests/testsuite/engine.rs

@@ -5,7 +5,7 @@ use std::path::Path;
 
 use clap::{builder::PossibleValue, Command};
 use clap_complete::engine::{
-    ArgValueCandidates, ArgValueCompleter, CompletionCandidate, PathCompleter,
+    ArgValueCandidates, ArgValueCompleter, CompletionCandidate, PathCompleter, SubcommandCandidates,
 };
 use snapbox::assert_data_eq;
 
@@ -984,7 +984,10 @@ a_pos,c_pos"
 #[test]
 fn suggest_external_subcommand() {
     let mut cmd = Command::new("dynamic")
-        .arg(clap::Arg::new("positional").value_parser(["pos1", "pos2", "pos3"]));
+        .arg(clap::Arg::new("positional").value_parser(["pos1", "pos2", "pos3"]))
+        .add(SubcommandCandidates::new(|| {
+            vec![CompletionCandidate::new("external")]
+        }));
 
     assert_data_eq!(
         complete!(cmd, " [TAB]"),
@@ -994,9 +997,12 @@ fn suggest_external_subcommand() {
 pos1
 pos2
 pos3
+external
 "
         ]
     );
+
+    assert_data_eq!(complete!(cmd, "e[TAB]"), snapbox::str!["external"]);
 }
 
 fn complete(cmd: &mut Command, args: impl AsRef<str>, current_dir: Option<&Path>) -> String {