feat(complete): Give control over display order

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

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)
 }