From 67d9fef9cee8f1b297aed73e6d95f78744b43a27 Mon Sep 17 00:00:00 2001
From: Ed Page <eopage@gmail.com>
Date: Fri, 20 Sep 2024 14:39:18 -0500
Subject: [PATCH] feat(complete): Give control over display order

---
 clap_complete/src/engine/candidate.rs | 12 ++++++++++++
 clap_complete/src/engine/complete.rs  |  7 ++++++-
 2 files changed, 18 insertions(+), 1 deletion(-)

diff --git a/clap_complete/src/engine/candidate.rs b/clap_complete/src/engine/candidate.rs
index 202fea0e971..af629f0f7c0 100644
--- a/clap_complete/src/engine/candidate.rs
+++ b/clap_complete/src/engine/candidate.rs
@@ -10,6 +10,7 @@ pub struct CompletionCandidate {
     help: Option<StyledStr>,
     id: Option<String>,
     tag: Option<StyledStr>,
+    display_order: Option<usize>,
     hidden: bool,
 }
 
@@ -45,6 +46,12 @@ impl CompletionCandidate {
         self
     }
 
+    /// Sort weight within a [`CompletionCandidate::tag`]
+    pub fn display_order(mut self, order: Option<usize>) -> Self {
+        self.display_order = order;
+        self
+    }
+
     /// Set the visibility of the completion candidate
     ///
     /// Only shown when there is no visible candidate for completing the current argument.
@@ -88,6 +95,11 @@ impl CompletionCandidate {
         self.tag.as_ref()
     }
 
+    /// Get the grouping tag
+    pub fn get_display_order(&self) -> Option<usize> {
+        self.display_order
+    }
+
     /// Get the visibility of the completion candidate
     pub fn is_hide_set(&self) -> bool {
         self.hidden
diff --git a/clap_complete/src/engine/complete.rs b/clap_complete/src/engine/complete.rs
index ed0c3a64900..359af90e743 100644
--- a/clap_complete/src/engine/complete.rs
+++ b/clap_complete/src/engine/complete.rs
@@ -286,7 +286,12 @@ fn complete_arg(
             tags.push(tag);
         }
     }
-    completions.sort_by_key(|c| tags.iter().position(|t| c.get_tag() == t.as_ref()));
+    completions.sort_by_key(|c| {
+        (
+            tags.iter().position(|t| c.get_tag() == t.as_ref()),
+            c.get_display_order(),
+        )
+    });
 
     Ok(completions)
 }