feat: Fullname(Ref)::category() and Category (#364)

A way to classify references.

Author: Byron

git-ref/src/fullname.rs

@@ -112,6 +112,11 @@ impl FullName {
     pub fn strip_prefix(&self) -> &BStr {
         self.to_ref().strip_prefix()
     }
+
+    /// Classify this name, or return `None` if it's unclassified.
+    pub fn category(&self) -> Option<crate::Category> {
+        self.to_ref().category()
+    }
 }
 
 impl<'a> FullNameRef<'a> {

git-ref/src/lib.rs

@@ -118,6 +118,22 @@ pub enum Kind {
     Symbolic,
 }
 
+/// The various known categories of references.
+///
+/// This translates into a prefix containing all references of a given category.
+#[derive(PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone, Copy)]
+pub enum Category {
+    /// A tag in `refs/tags`
+    Tag,
+    /// A branch in `refs/heads`
+    LocalBranch,
+    /// A branch in `refs/remotes`
+    RemoteBranch,
+    /// A tag in `refs/notes`
+    Note,
+    // NOTE: when adding something here, add it to `kind()` and `strip_prefix()` too.
+}
+
 /// Denotes a ref target, equivalent to [`Kind`], but with mutable data.
 #[derive(PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone)]
 pub enum Target {

git-ref/src/name.rs

@@ -6,11 +6,23 @@ use std::{
 
 use git_object::bstr::{BStr, BString, ByteSlice, ByteVec};
 
-use crate::{FullNameRef, PartialNameRef};
+use crate::{Category, FullNameRef, PartialNameRef};
 
 /// The error used in the [`PartialNameRef`][super::PartialNameRef]::try_from(…) implementations.
 pub type Error = git_validate::reference::name::Error;
 
+impl Category {
+    /// Return the prefix that would contain all references of our kind.
+    pub fn prefix(&self) -> &BStr {
+        match self {
+            Category::Tag => b"refs/tags/".as_bstr(),
+            Category::LocalBranch => b"refs/heads/".as_bstr(),
+            Category::RemoteBranch => b"refs/remotes/".as_bstr(),
+            Category::Note => b"refs/notes/".as_bstr(),
+        }
+    }
+}
+
 impl<'a> FullNameRef<'a> {
     /// Convert this name into the relative path identifying the reference location.
     pub fn to_path(self) -> &'a Path {
@@ -34,6 +46,21 @@ impl<'a> FullNameRef<'a> {
             .map(|n| n.as_bstr())
             .unwrap_or(n)
     }
+
+    /// Classify this name, or return `None` if it's unclassified.
+    pub fn category(&self) -> Option<Category> {
+        for kind in &[
+            Category::Tag,
+            Category::LocalBranch,
+            Category::RemoteBranch,
+            Category::Note,
+        ] {
+            if self.0.starts_with(kind.prefix()) {
+                return (*kind).into();
+            }
+        }
+        None
+    }
 }
 
 impl<'a> PartialNameRef<'a> {

git-ref/tests/fullname/mod.rs

@@ -1,3 +1,4 @@
+use git_ref::Category;
 use std::convert::TryInto;
 
 #[test]
@@ -7,15 +8,18 @@ fn file_name() {
 }
 #[test]
 fn strip_prefix() {
-    for (input, expected) in [
-        ("refs/tags/tag-name", "tag-name"),
-        ("refs/heads/main", "main"),
-        ("refs/remotes/origin/main", "origin/main"),
-        ("refs/notes/note-name", "notes/note-name"),
+    for (input, expected, category) in [
+        ("refs/tags/tag-name", "tag-name", Category::Tag),
+        ("refs/heads/main", "main", Category::LocalBranch),
+        ("refs/remotes/origin/main", "origin/main", Category::RemoteBranch),
+        ("refs/notes/note-name", "notes/note-name", Category::Note),
     ] {
         let name: git_ref::FullName = input.try_into().unwrap();
+        let category = Some(category);
         assert_eq!(name.to_ref().strip_prefix(), expected);
         assert_eq!(name.strip_prefix(), expected);
+        assert_eq!(name.category(), category);
+        assert_eq!(name.to_ref().category(), category);
     }
 
     let special = "HEAD";
@@ -25,7 +29,7 @@ fn strip_prefix() {
         special,
         "the whole name is returned if there is no prefix"
     );
-    assert_eq!(name.strip_prefix(), name.to_ref().strip_prefix());
+    assert_eq!(name.category(), None);
 }
 
 #[test]