feat: comfort API like string_by_key(key) takes a key like "remote.origin.url", add section_by_key("remote.origin") as well.

That way it's the most comfortable way to query values and very
similar to how git does it, too.

Additionally, sections can be obtained by section key, both mutably and immutably for completeness.

Author: Byron

git-config/src/file/access/comfort.rs

@@ -18,6 +18,11 @@ impl<'event> File<'event> {
         self.string_filter(section_name, subsection_name, key, &mut |_| true)
     }
 
+    /// Like [`string()`][File::string()], but suitable for statically known `key`s like `remote.origin.url`.
+    pub fn string_by_key<'a>(&self, key: impl Into<&'a BStr>) -> Option<Cow<'_, BStr>> {
+        self.string_filter_by_key(key, &mut |_| true)
+    }
+
     /// Like [`string()`][File::string()], but the section containing the returned value must pass `filter` as well.
     pub fn string_filter(
         &self,
@@ -29,6 +34,17 @@ impl<'event> File<'event> {
         self.raw_value_filter(section_name, subsection_name, key, filter).ok()
     }
 
+    /// Like [`string_filter()`][File::string_filter()], but suitable for statically known `key`s like `remote.origin.url`.
+    pub fn string_filter_by_key<'a>(
+        &self,
+        key: impl Into<&'a BStr>,
+        filter: &mut MetadataFilter,
+    ) -> Option<Cow<'_, BStr>> {
+        let key = crate::parse::key(key)?;
+        self.raw_value_filter(key.section_name, key.subsection_name, key.value_name, filter)
+            .ok()
+    }
+
     /// Like [`value()`][File::value()], but returning `None` if the path wasn't found.
     ///
     /// Note that this path is not vetted and should only point to resources which can't be used
@@ -44,6 +60,11 @@ impl<'event> File<'event> {
         self.path_filter(section_name, subsection_name, key, &mut |_| true)
     }
 
+    /// Like [`path()`][File::path()], but suitable for statically known `key`s like `remote.origin.url`.
+    pub fn path_by_key<'a>(&self, key: impl Into<&'a BStr>) -> Option<crate::Path<'_>> {
+        self.path_filter_by_key(key, &mut |_| true)
+    }
+
     /// Like [`path()`][File::path()], but the section containing the returned value must pass `filter` as well.
     ///
     /// This should be the preferred way of accessing paths as those from untrusted
@@ -62,6 +83,16 @@ impl<'event> File<'event> {
             .map(crate::Path::from)
     }
 
+    /// Like [`path_filter()`][File::path_filter()], but suitable for statically known `key`s like `remote.origin.url`.
+    pub fn path_filter_by_key<'a>(
+        &self,
+        key: impl Into<&'a BStr>,
+        filter: &mut MetadataFilter,
+    ) -> Option<crate::Path<'_>> {
+        let key = crate::parse::key(key)?;
+        self.path_filter(key.section_name, key.subsection_name, key.value_name, filter)
+    }
+
     /// Like [`value()`][File::value()], but returning `None` if the boolean value wasn't found.
     pub fn boolean(
         &self,
@@ -72,6 +103,11 @@ impl<'event> File<'event> {
         self.boolean_filter(section_name, subsection_name, key, &mut |_| true)
     }
 
+    /// Like [`boolean()`][File::boolean()], but suitable for statically known `key`s like `remote.origin.url`.
+    pub fn boolean_by_key<'a>(&self, key: impl Into<&'a BStr>) -> Option<Result<bool, value::Error>> {
+        self.boolean_filter_by_key(key, &mut |_| true)
+    }
+
     /// Like [`boolean()`][File::boolean()], but the section containing the returned value must pass `filter` as well.
     pub fn boolean_filter(
         &self,
@@ -99,6 +135,16 @@ impl<'event> File<'event> {
         None
     }
 
+    /// Like [`boolean_filter()`][File::boolean_filter()], but suitable for statically known `key`s like `remote.origin.url`.
+    pub fn boolean_filter_by_key<'a>(
+        &self,
+        key: impl Into<&'a BStr>,
+        filter: &mut MetadataFilter,
+    ) -> Option<Result<bool, value::Error>> {
+        let key = crate::parse::key(key)?;
+        self.boolean_filter(key.section_name, key.subsection_name, key.value_name, filter)
+    }
+
     /// Like [`value()`][File::value()], but returning an `Option` if the integer wasn't found.
     pub fn integer(
         &self,
@@ -109,6 +155,11 @@ impl<'event> File<'event> {
         self.integer_filter(section_name, subsection_name, key, &mut |_| true)
     }
 
+    /// Like [`integer()`][File::integer()], but suitable for statically known `key`s like `remote.origin.url`.
+    pub fn integer_by_key<'a>(&self, key: impl Into<&'a BStr>) -> Option<Result<i64, value::Error>> {
+        self.integer_filter_by_key(key, &mut |_| true)
+    }
+
     /// Like [`integer()`][File::integer()], but the section containing the returned value must pass `filter` as well.
     pub fn integer_filter(
         &self,
@@ -124,6 +175,16 @@ impl<'event> File<'event> {
         }))
     }
 
+    /// Like [`integer_filter()`][File::integer_filter()], but suitable for statically known `key`s like `remote.origin.url`.
+    pub fn integer_filter_by_key<'a>(
+        &self,
+        key: impl Into<&'a BStr>,
+        filter: &mut MetadataFilter,
+    ) -> Option<Result<i64, value::Error>> {
+        let key = crate::parse::key(key)?;
+        self.integer_filter(key.section_name, key.subsection_name, key.value_name, filter)
+    }
+
     /// Similar to [`values(…)`][File::values()] but returning strings if at least one of them was found.
     pub fn strings(
         &self,
@@ -134,6 +195,12 @@ impl<'event> File<'event> {
         self.raw_values(section_name, subsection_name, key).ok()
     }
 
+    /// Like [`strings()`][File::strings()], but suitable for statically known `key`s like `remote.origin.url`.
+    pub fn strings_by_key<'a>(&self, key: impl Into<&'a BStr>) -> Option<Vec<Cow<'_, BStr>>> {
+        let key = crate::parse::key(key)?;
+        self.strings(key.section_name, key.subsection_name, key.value_name)
+    }
+
     /// Similar to [`strings(…)`][File::strings()], but all values are in sections that passed `filter`.
     pub fn strings_filter(
         &self,
@@ -145,6 +212,16 @@ impl<'event> File<'event> {
         self.raw_values_filter(section_name, subsection_name, key, filter).ok()
     }
 
+    /// Like [`strings_filter()`][File::strings_filter()], but suitable for statically known `key`s like `remote.origin.url`.
+    pub fn strings_filter_by_key<'a>(
+        &self,
+        key: impl Into<&'a BStr>,
+        filter: &mut MetadataFilter,
+    ) -> Option<Vec<Cow<'_, BStr>>> {
+        let key = crate::parse::key(key)?;
+        self.strings_filter(key.section_name, key.subsection_name, key.value_name, filter)
+    }
+
     /// Similar to [`values(…)`][File::values()] but returning integers if at least one of them was found
     /// and if none of them overflows.
     pub fn integers(
@@ -156,6 +233,11 @@ impl<'event> File<'event> {
         self.integers_filter(section_name, subsection_name, key, &mut |_| true)
     }
 
+    /// Like [`integers()`][File::integers()], but suitable for statically known `key`s like `remote.origin.url`.
+    pub fn integers_by_key<'a>(&self, key: impl Into<&'a BStr>) -> Option<Result<Vec<i64>, value::Error>> {
+        self.integers_filter_by_key(key, &mut |_| true)
+    }
+
     /// Similar to [`integers(…)`][File::integers()] but all integers are in sections that passed `filter`
     /// and that are not overflowing.
     pub fn integers_filter(
@@ -179,4 +261,14 @@ impl<'event> File<'event> {
                     .collect()
             })
     }
+
+    /// Like [`integers_filter()`][File::integers_filter()], but suitable for statically known `key`s like `remote.origin.url`.
+    pub fn integers_filter_by_key<'a>(
+        &self,
+        key: impl Into<&'a BStr>,
+        filter: &mut MetadataFilter,
+    ) -> Option<Result<Vec<i64>, value::Error>> {
+        let key = crate::parse::key(key)?;
+        self.integers_filter(key.section_name, key.subsection_name, key.value_name, filter)
+    }
 }

git-config/src/file/access/mutate.rs

@@ -31,6 +31,15 @@ impl<'event> File<'event> {
             .to_mut(nl))
     }
 
+    /// Returns the last found mutable section with a given `key`, identifying the name and subsection name like `core` or `remote.origin`.
+    pub fn section_mut_by_key<'a, 'b>(
+        &'a mut self,
+        key: impl Into<&'b BStr>,
+    ) -> Result<SectionMut<'a, 'event>, lookup::existing::Error> {
+        let key = section::unvalidated::Key::parse(key).ok_or(lookup::existing::Error::KeyMissing)?;
+        self.section_mut(key.section_name, key.subsection_name)
+    }
+
     /// Return the mutable section identified by `id`, or `None` if it didn't exist.
     ///
     /// Note that `id` is stable across deletions and insertions.
@@ -99,6 +108,17 @@ impl<'event> File<'event> {
         Ok(id.and_then(move |id| self.sections.get_mut(&id).map(move |s| s.to_mut(nl))))
     }
 
+    /// Like [`section_mut_filter()`][File::section_mut_filter()], but identifies the with a given `key`,
+    /// like `core` or `remote.origin`.
+    pub fn section_mut_filter_by_key<'a, 'b>(
+        &'a mut self,
+        key: impl Into<&'b BStr>,
+        filter: &mut MetadataFilter,
+    ) -> Result<Option<file::SectionMut<'a, 'event>>, lookup::existing::Error> {
+        let key = section::unvalidated::Key::parse(key).ok_or(lookup::existing::Error::KeyMissing)?;
+        self.section_mut_filter(key.section_name, key.subsection_name, filter)
+    }
+
     /// Adds a new section. If a subsection name was provided, then
     /// the generated header will use the modern subsection syntax.
     /// Returns a reference to the new section for immediate editing.

git-config/src/file/access/read_only.rs

@@ -139,6 +139,16 @@ impl<'event> File<'event> {
             .expect("section present as we take all"))
     }
 
+    /// Returns the last found immutable section with a given `key`, identifying the name and subsection name like `core`
+    /// or `remote.origin`.
+    pub fn section_by_key<'a>(
+        &self,
+        key: impl Into<&'a BStr>,
+    ) -> Result<&file::Section<'event>, lookup::existing::Error> {
+        let key = crate::parse::section::unvalidated::Key::parse(key).ok_or(lookup::existing::Error::KeyMissing)?;
+        self.section(key.section_name, key.subsection_name)
+    }
+
     /// Returns the last found immutable section with a given `name` and optional `subsection_name`, that matches `filter`.
     ///
     /// If there are sections matching `section_name` and `subsection_name` but the `filter` rejects all of them, `Ok(None)`
@@ -161,6 +171,16 @@ impl<'event> File<'event> {
             }))
     }
 
+    /// Like [`section_filter()`][File::section_filter()], but identifies the section with `key` like `core` or `remote.origin`.
+    pub fn section_filter_by_key<'a, 'b>(
+        &'a self,
+        key: impl Into<&'b BStr>,
+        filter: &mut MetadataFilter,
+    ) -> Result<Option<&'a file::Section<'event>>, lookup::existing::Error> {
+        let key = crate::parse::section::unvalidated::Key::parse(key).ok_or(lookup::existing::Error::KeyMissing)?;
+        self.section_filter(key.section_name, key.subsection_name, filter)
+    }
+
     /// Gets all sections that match the provided `name`, ignoring any subsections.
     ///
     /// # Examples

git-config/src/parse/section/mod.rs

@@ -8,6 +8,8 @@ use crate::parse::{Event, Section};
 ///
 pub mod header;
 
+pub(crate) mod unvalidated;
+
 /// A container for events, avoiding heap allocations in typical files.
 pub type Events<'a> = SmallVec<[Event<'a>; 64]>;
 

git-config/src/parse/section/unvalidated.rs

@@ -0,0 +1,25 @@
+use bstr::{BStr, ByteSlice};
+
+/// An unvalidated parse result of a key for a section, parsing input like `remote.origin` or `core`.
+#[derive(Debug, PartialEq, Ord, PartialOrd, Eq, Hash, Clone, Copy)]
+pub struct Key<'a> {
+    /// The name of the section, like `remote` in `remote.origin`.
+    pub section_name: &'a str,
+    /// The name of the sub-section, like `origin` in `remote.origin`.
+    pub subsection_name: Option<&'a BStr>,
+}
+
+impl<'a> Key<'a> {
+    /// Parse `input` like `remote.origin` or `core` as a `Key` to make its section specific fields available,
+    /// or `None` if there were not one or two tokens separated by `.`.
+    /// Note that `input` isn't validated, and is `str` as ascii is a subset of UTF-8 which is required for any valid keys.
+    pub fn parse(input: impl Into<&'a BStr>) -> Option<Self> {
+        let input = input.into();
+        let mut tokens = input.splitn(2, |b| *b == b'.');
+
+        Some(Key {
+            section_name: tokens.next()?.to_str().ok()?,
+            subsection_name: tokens.next().map(Into::into),
+        })
+    }
+}

git-config/src/parse/tests.rs

@@ -1,6 +1,43 @@
 mod section {
 
     mod header {
+        mod unvalidated {
+            use crate::parse::section::unvalidated::Key;
+
+            #[test]
+            fn section_name_only() {
+                assert_eq!(
+                    Key::parse("core").unwrap(),
+                    Key {
+                        section_name: "core",
+                        subsection_name: None
+                    }
+                );
+            }
+
+            #[test]
+            fn section_name_and_subsection() {
+                assert_eq!(
+                    Key::parse("core.bare").unwrap(),
+                    Key {
+                        section_name: "core",
+                        subsection_name: Some("bare".into())
+                    }
+                );
+            }
+
+            #[test]
+            fn section_name_and_subsection_with_separators() {
+                assert_eq!(
+                    Key::parse("remote.https:///home/user.git").unwrap(),
+                    Key {
+                        section_name: "remote",
+                        subsection_name: Some("https:///home/user.git".into())
+                    }
+                );
+            }
+        }
+
         mod write_to {
             use std::borrow::Cow;
 

git-config/tests/file/access/read_only.rs

@@ -39,6 +39,7 @@ fn get_value_for_all_provided_values() -> crate::Result {
 
         assert!(!config.value::<Boolean>("core", None, "bool-explicit")?.0);
         assert!(!config.boolean("core", None, "bool-explicit").expect("exists")?);
+        assert!(!config.boolean_by_key("core.bool-explicit").expect("exists")?);
 
         assert!(
             config.value::<Boolean>("core", None, "bool-implicit").is_err(),
@@ -58,6 +59,10 @@ fn get_value_for_all_provided_values() -> crate::Result {
             &[cow_str("")],
             "unset values show up as empty within a string array"
         );
+        assert_eq!(
+            config.strings_by_key("core.bool-implicit").expect("present"),
+            &[cow_str("")],
+        );
 
         assert_eq!(config.string("doesnt", None, "exist"), None);
 
@@ -145,6 +150,8 @@ fn get_value_for_all_provided_values() -> crate::Result {
 
         let actual = config.path("core", None, "location").expect("present");
         assert_eq!(&*actual, "~/tmp");
+        let actual = config.path_by_key("core.location").expect("present");
+        assert_eq!(&*actual, "~/tmp");
 
         let actual = config.path("core", None, "location-quoted").expect("present");
         assert_eq!(&*actual, "~/quoted");

git-config/tests/file/init/comfort.rs

@@ -43,6 +43,7 @@ fn from_git_dir() -> crate::Result {
         "value",
         "a value from the local repo configuration"
     );
+    assert_eq!(config.string_by_key("a.local").expect("present").as_ref(), "value",);
     assert_eq!(
         config.string("a", None, "local-include").expect("present").as_ref(),
         "from-a.config",

git-config/tests/file/init/from_env.rs

@@ -44,7 +44,7 @@ fn single_key_value_pair() -> crate::Result {
     let config = File::from_env(Default::default())?.unwrap();
     assert_eq!(config.raw_value("core", None, "key")?, Cow::<[u8]>::Borrowed(b"value"));
     assert_eq!(
-        config.section("core", None)?.meta(),
+        config.section_by_key("core")?.meta(),
         &git_config::file::Metadata::from(git_config::Source::Env),
         "source if configured correctly"
     );

git-config/tests/file/init/from_paths/includes/unconditional.rs

@@ -122,6 +122,7 @@ fn respect_max_depth() -> crate::Result {
     let config =
         File::from_paths_metadata(into_meta(vec![dir.path().join("0")]), follow_options())?.expect("non-empty");
     assert_eq!(config.integers("core", None, "i"), Some(Ok(vec![0, 1, 2, 3, 4])));
+    assert_eq!(config.integers_by_key("core.i"), Some(Ok(vec![0, 1, 2, 3, 4])));
 
     fn make_options(max_depth: u8, error_on_max_depth_exceeded: bool) -> init::Options<'static> {
         init::Options {
@@ -139,6 +140,7 @@ fn respect_max_depth() -> crate::Result {
     let options = make_options(1, false);
     let config = File::from_paths_metadata(into_meta(vec![dir.path().join("0")]), options)?.expect("non-empty");
     assert_eq!(config.integer("core", None, "i"), Some(Ok(1)));
+    assert_eq!(config.integer_by_key("core.i"), Some(Ok(1)));
 
     // with default max_allowed_depth of 10 and 4 levels of includes, last level is read
     let options = init::Options {