feat!: remove File::names_and_active_state() in favor of File::is_active_platform().

With this platform it's possible to make repeated checks to see if a named submodule is active.

Author: Byron

gix-submodule/src/access.rs

@@ -1,5 +1,5 @@
 use crate::config::{Branch, FetchRecurse, Ignore, Update};
-use crate::{config, File};
+use crate::{config, File, IsActivePlatform};
 use bstr::BStr;
 use std::borrow::Cow;
 use std::collections::HashSet;
@@ -40,17 +40,7 @@ impl File {
             })
     }
 
-    /// Return an iterator of names along with a boolean that indicates the submodule is active (`true`) or inactive  (`false`).
-    /// If the boolean was wrapped in an error, there was a configuration error.
-    /// Use `defaults` for parsing the pathspecs used to match on names via `submodule.active` configuration retrieved from `config`.
-    /// `attributes` provides a way to resolve the attributes mentioned in pathspecs.
-    ///
-    /// Inactive submodules should not participate in any operations that are applying to all submodules.
-    ///
-    /// Note that the entirety of sections in `config` are considered, not just the ones of the configuration for the repository itself.
-    /// `submodule.active` pathspecs are considered to be top-level specs and match the name of submodules, which may be considered active
-    /// on match. However, there is a [hierarchy of rules](https://git-scm.com/docs/gitsubmodules#_active_submodules) that's
-    /// implemented here, but pathspecs add the most complexity.
+    /// Similar to [Self::is_active_platform()], but automatically applies it to each name to learn if a submodule is active or not.
     pub fn names_and_active_state<'a>(
         &'a self,
         config: &'a gix_config::File<'static>,
@@ -63,12 +53,30 @@ impl File {
             ) -> bool
             + 'a,
     ) -> Result<
-        impl Iterator<Item = (&BStr, Result<bool, config::names_and_active_state::iter::Error>)> + 'a,
-        config::names_and_active_state::Error,
+        impl Iterator<Item = (&BStr, Result<bool, crate::is_active_platform::is_active::Error>)> + 'a,
+        crate::is_active_platform::Error,
     > {
-        let mut search = config
+        let mut platform = self.is_active_platform(config, defaults)?;
+        let iter = self
+            .names()
+            .map(move |name| (name, platform.is_active(self, config, name, &mut attributes)));
+        Ok(iter)
+    }
+
+    /// Return a platform which allows to check if a submodule name is active or inactive.
+    /// Use `defaults` for parsing the pathspecs used to later match on names via `submodule.active` configuration retrieved from `config`.
+    ///
+    /// All `submodule.active` pathspecs are considered to be top-level specs and match the name of submodules, which are active
+    /// on inclusive match.
+    /// The full algorithm is described as [hierarchy of rules](https://git-scm.com/docs/gitsubmodules#_active_submodules).
+    pub fn is_active_platform(
+        &self,
+        config: &gix_config::File<'_>,
+        defaults: gix_pathspec::Defaults,
+    ) -> Result<IsActivePlatform, crate::is_active_platform::Error> {
+        let search = config
             .strings_by_key("submodule.active")
-            .map(|patterns| -> Result<_, config::names_and_active_state::Error> {
+            .map(|patterns| -> Result<_, crate::is_active_platform::Error> {
                 let patterns = patterns
                     .into_iter()
                     .map(|pattern| gix_pathspec::parse(&pattern, defaults))
@@ -80,27 +88,7 @@ impl File {
                 )?)
             })
             .transpose()?;
-        let iter = self.names().map(move |name| {
-            let active = (|| -> Result<_, config::names_and_active_state::iter::Error> {
-                if let Some(val) = config.boolean("submodule", Some(name), "active").transpose()? {
-                    return Ok(val);
-                };
-                if let Some(val) = search
-                    .as_mut()
-                    .and_then(|search| search.pattern_matching_relative_path(name, Some(true), &mut attributes))
-                    .map(|m| !m.is_excluded())
-                {
-                    return Ok(val);
-                }
-                Ok(match self.url(name) {
-                    Ok(_) => true,
-                    Err(config::url::Error::Missing { .. }) => false,
-                    Err(err) => return Err(err.into()),
-                })
-            })();
-            (name, active)
-        });
-        Ok(iter)
+        Ok(IsActivePlatform { search })
     }
 
     /// Given the `relative_path` (as seen from the root of the worktree) of a submodule with possibly platform-specific

gix-submodule/src/config.rs

@@ -214,28 +214,3 @@ pub mod path {
         OutsideOfWorktree { actual: BString, submodule: BString },
     }
 }
-///
-pub mod names_and_active_state {
-    /// The error returned by [File::names_and_active_state](crate::File::names_and_active_state()).
-    #[derive(Debug, thiserror::Error)]
-    #[allow(missing_docs)]
-    pub enum Error {
-        #[error(transparent)]
-        NormalizePattern(#[from] gix_pathspec::normalize::Error),
-        #[error(transparent)]
-        ParsePattern(#[from] gix_pathspec::parse::Error),
-    }
-
-    ///
-    pub mod iter {
-        /// The error returned by the iterator of [File::names_and_active_state](crate::File::names_and_active_state()).
-        #[derive(Debug, thiserror::Error)]
-        #[allow(missing_docs)]
-        pub enum Error {
-            #[error("The value of the 'active' field of a submodule could not be decoded")]
-            ActiveField(#[from] gix_config::value::Error),
-            #[error(transparent)]
-            Url(#[from] crate::config::url::Error),
-        }
-    }
-}

gix-submodule/src/is_active_platform.rs

@@ -0,0 +1,68 @@
+use crate::IsActivePlatform;
+use bstr::BStr;
+
+/// The error returned by [File::names_and_active_state](crate::File::names_and_active_state()).
+#[derive(Debug, thiserror::Error)]
+#[allow(missing_docs)]
+pub enum Error {
+    #[error(transparent)]
+    NormalizePattern(#[from] gix_pathspec::normalize::Error),
+    #[error(transparent)]
+    ParsePattern(#[from] gix_pathspec::parse::Error),
+}
+
+///
+pub mod is_active {
+    /// The error returned by the iterator of [File::names_and_active_state](crate::File::names_and_active_state()).
+    #[derive(Debug, thiserror::Error)]
+    #[allow(missing_docs)]
+    pub enum Error {
+        #[error("The value of the 'active' field of a submodule could not be decoded")]
+        ActiveField(#[from] gix_config::value::Error),
+        #[error(transparent)]
+        Url(#[from] crate::config::url::Error),
+    }
+}
+
+impl IsActivePlatform {
+    /// Returns `true` if the submodule named `name` is active or `false` otherwise.
+    /// `modules` is the instance that [is_active_platform()](crate::File::is_active_platform()) was called on, and
+    /// `config` is the configuration that was passed there as well.
+    /// `attributes(relative_path, case, is_dir, outcome)` provides a way to resolve the attributes mentioned in `submodule.active` pathspecs
+    /// that are evaluated in the platforms git configuration.
+    ///
+    /// A submodule's active state is determined in the following order
+    ///
+    /// * it's `submodule.<name>.active` configuration is set
+    /// * it matches a `submodule.active` pathspec either positively or negatively via `:!<spec>`
+    /// * it's active if it has a `url`
+    pub fn is_active(
+        &mut self,
+        modules: &crate::File,
+        config: &gix_config::File<'static>,
+        name: &BStr,
+        attributes: impl FnMut(
+            &BStr,
+            gix_pathspec::attributes::glob::pattern::Case,
+            bool,
+            &mut gix_pathspec::attributes::search::Outcome,
+        ) -> bool,
+    ) -> Result<bool, is_active::Error> {
+        if let Some(val) = config.boolean("submodule", Some(name), "active").transpose()? {
+            return Ok(val);
+        };
+        if let Some(val) = self
+            .search
+            .as_mut()
+            .and_then(|search| search.pattern_matching_relative_path(name, Some(true), attributes))
+            .map(|m| !m.is_excluded())
+        {
+            return Ok(val);
+        }
+        Ok(match modules.url(name) {
+            Ok(_) => true,
+            Err(crate::config::url::Error::Missing { .. }) => false,
+            Err(err) => return Err(err.into()),
+        })
+    }
+}

gix-submodule/src/lib.rs

@@ -21,6 +21,14 @@ mod access;
 ///
 pub mod config;
 
+///
+pub mod is_active_platform;
+
+/// A platform to keep the state necessary to perform repeated active checks, created by [File::is_active_platform()].
+pub struct IsActivePlatform {
+    pub(crate) search: Option<gix_pathspec::Search>,
+}
+
 /// Mutation
 impl File {
     /// This can be used to let `config` override some values we know about submodules, namely…

gix-submodule/tests/file/mod.rs

@@ -2,7 +2,7 @@ fn submodule(bytes: &str) -> gix_submodule::File {
     gix_submodule::File::from_bytes(bytes.as_bytes(), None, &Default::default()).expect("valid module")
 }
 
-mod names_and_active_state {
+mod is_active_platform {
     use bstr::{BStr, ByteSlice};
     use std::str::FromStr;
 
@@ -31,17 +31,25 @@ mod names_and_active_state {
         module: &'a gix_submodule::File,
         config: &'a gix_config::File<'static>,
         defaults: gix_pathspec::Defaults,
-        attributes: impl FnMut(
+        mut attributes: impl FnMut(
                 &BStr,
                 gix_pathspec::attributes::glob::pattern::Case,
                 bool,
                 &mut gix_pathspec::attributes::search::Outcome,
             ) -> bool
             + 'a,
     ) -> crate::Result<Vec<(&'a str, bool)>> {
+        let mut platform = module.is_active_platform(config, defaults)?;
         Ok(module
-            .names_and_active_state(config, defaults, attributes)?
-            .map(|(name, bool)| (name.to_str().expect("valid"), bool.expect("valid")))
+            .names()
+            .map(|name| {
+                (
+                    name.to_str().expect("valid"),
+                    platform
+                        .is_active(module, config, name, &mut attributes)
+                        .expect("valid"),
+                )
+            })
             .collect())
     }