feat: add Search::pop_pattern_list().

Also, improve method documentation.

Author: Byron

gix-attributes/src/search/attributes.rs

@@ -11,11 +11,14 @@ use crate::{
 
 /// Instantiation and initialization.
 impl Search {
-    /// Create a search instance preloaded with *built-ins* as well as attribute `files` from various global locations.
+    /// Create a search instance preloaded with *built-ins* followed by attribute `files` from various global locations.
+    ///
     /// See [`Source`][crate::Source] for a way to obtain these paths.
+    ///
     /// Note that parsing is lenient and errors are logged.
-    /// `buf` is used to read `files` from disk which will be ignored if they do not exist.
-    /// `collection` will be updated with information necessary to perform lookups later.
+    ///
+    /// * `buf` is used to read `files` from disk which will be ignored if they do not exist.
+    /// * `collection` will be updated with information necessary to perform lookups later.
     pub fn new_globals(
         files: impl IntoIterator<Item = impl Into<PathBuf>>,
         buf: &mut Vec<u8>,
@@ -36,7 +39,7 @@ impl Search {
     /// Add the given file at `source` to our patterns if it exists, otherwise do nothing.
     /// Update `collection` with newly added attribute names.
     /// If a `root` is provided, it's not considered a global file anymore.
-    /// Returns true if the file was added, or false if it didn't exist.
+    /// Returns `true` if the file was added, or `false` if it didn't exist.
     pub fn add_patterns_file(
         &mut self,
         source: impl Into<PathBuf>,
@@ -63,12 +66,17 @@ impl Search {
         self.patterns.push(pattern::List::from_bytes(bytes, source, root));
         collection.update_from_list(self.patterns.last_mut().expect("just added"));
     }
+
+    /// Pop the last attribute patterns list from our queue.
+    pub fn pop_pattern_list(&mut self) -> Option<gix_glob::search::pattern::List<Attributes>> {
+        self.patterns.pop()
+    }
 }
 
 /// Access and matching
 impl Search {
     /// Match `relative_path`, a path relative to the repository, while respective `case`-sensitivity and write them to `out`
-    /// Return true if at least one pattern matched.
+    /// Return `true` if at least one pattern matched.
     pub fn pattern_matching_relative_path<'a, 'b>(
         &'a self,
         relative_path: impl Into<&'b BStr>,

gix-attributes/src/search/outcome.rs

@@ -15,7 +15,7 @@ use crate::{
 /// Initialization
 impl<'pattern> Outcome<'pattern> {
     /// Initialize this instance to collect outcomes for all names in `collection`, which represents all possible attributes
-    /// or macros we may visit.
+    /// or macros we may visit, and [`reset`][Self::reset()] it unconditionally.
     ///
     /// This must be called after each time `collection` changes.
     pub fn initialize(&mut self, collection: &MetadataCollection) {
@@ -125,6 +125,11 @@ impl<'pattern> Outcome<'pattern> {
     pub fn match_by_id(&self, id: AttributeId) -> Option<&Match<'pattern>> {
         self.matches_by_id.get(id.0).and_then(|m| m.r#match.as_ref())
     }
+
+    /// Return `true` if there is nothing more to be done as all attributes were filled.
+    pub fn is_done(&self) -> bool {
+        self.remaining() == 0
+    }
 }
 
 /// Mutation
@@ -201,11 +206,6 @@ impl<'attr> Outcome<'attr> {
             .expect("BUG: instance must be initialized for each search set")
     }
 
-    /// Return true if there is nothing more to be done as all attributes were filled.
-    pub(crate) fn is_done(&self) -> bool {
-        self.remaining() == 0
-    }
-
     fn reduce_and_check_if_done(&mut self, attr: AttributeId) -> bool {
         if self.selected.is_empty()
             || self

gix-attributes/tests/search/mod.rs

@@ -258,6 +258,8 @@ fn assignments<'a>(
 
 mod baseline {
     use bstr::{BStr, ByteSlice};
+    use gix_attributes::{search::MetadataCollection, AssignmentRef, StateRef};
+    use std::path::PathBuf;
 
     /// Read user-attributes and baseline in one go.
     pub fn user_attributes_named_baseline(
@@ -274,9 +276,6 @@ mod baseline {
 
         Ok((group, collection, base, input))
     }
-    use std::path::PathBuf;
-
-    use gix_attributes::{search::MetadataCollection, AssignmentRef, StateRef};
 
     /// Read user-attributes and baseline in one go.
     pub fn user_attributes(