Nits + SafelyIndexMut.

Author: Ethiraric

saphyr/src/annotated/marked_yaml.rs

@@ -7,7 +7,9 @@ use std::borrow::Cow;
 use hashlink::LinkedHashMap;
 use saphyr_parser::{Marker, ScalarStyle, Span, Tag};
 
-use crate::{Accessor, LoadableYamlNode, SafelyIndex, Scalar, Yaml, YamlData};
+use crate::{
+    index::SafelyIndexMut, Accessor, LoadableYamlNode, SafelyIndex, Scalar, Yaml, YamlData,
+};
 
 /// A YAML node with [`Span`]s pointing to the start of the node.
 ///
@@ -129,6 +131,15 @@ impl SafelyIndex for MarkedYaml<'_> {
     }
 }
 
+impl SafelyIndexMut for MarkedYaml<'_> {
+    fn get_mut(&mut self, key: impl Into<Accessor>) -> Option<&mut Self> {
+        match key.into() {
+            Accessor::Field(f) => self.data.as_mapping_get_mut(f.as_str()),
+            Accessor::Index(i) => self.data.as_sequence_get_mut(i),
+        }
+    }
+}
+
 impl<'input> LoadableYamlNode<'input> for MarkedYaml<'input> {
     type HashKey = MarkedYaml<'input>;
 

saphyr/src/annotated/marked_yaml_owned.rs

@@ -7,7 +7,10 @@ use std::borrow::Cow;
 use hashlink::LinkedHashMap;
 use saphyr_parser::{ScalarStyle, Span, Tag};
 
-use crate::{Accessor, LoadableYamlNode, SafelyIndex, ScalarOwned, Yaml, YamlDataOwned};
+use crate::{
+    index::SafelyIndexMut, Accessor, LoadableYamlNode, SafelyIndex, ScalarOwned, Yaml,
+    YamlDataOwned,
+};
 
 /// A YAML node with [`Span`]s pointing to the start of the node.
 ///
@@ -135,6 +138,15 @@ impl SafelyIndex for MarkedYamlOwned {
     }
 }
 
+impl SafelyIndexMut for MarkedYamlOwned {
+    fn get_mut(&mut self, key: impl Into<Accessor>) -> Option<&mut Self> {
+        match key.into() {
+            Accessor::Field(f) => self.data.as_mapping_get_mut(f.as_str()),
+            Accessor::Index(i) => self.data.as_sequence_get_mut(i),
+        }
+    }
+}
+
 impl LoadableYamlNode<'_> for MarkedYamlOwned {
     type HashKey = MarkedYamlOwned;
 

saphyr/src/index.rs

@@ -1,15 +1,46 @@
-/// A trait to safely index into a structure with an `Accessor`.
-/// This will never panic and return an `Option::None` on failure.
-pub trait SafelyIndex<X = Self> {
-    /// Attempt to access a field
-    fn get(&self, key: impl Into<Accessor>) -> Option<&X>;
+/// A trait to index without panicking into a structure through an [`Accessor`].
+///
+/// [`SafelyIndex`] is implemented on YAML objects to provide the [`get`] method to conveniently
+/// access sequence or mapping elements. This is similar to [`Index`]ing, except that the [`get`]
+/// method returns an [`Option`], using [`None`] rather than panicking when the requested index is
+/// out of range.
+///
+/// [`get`]: SafelyIndex::get
+/// [`Index`]: std::ops::Index
+pub trait SafelyIndex<Node = Self> {
+    /// Access a field of the given YAML object.
+    ///
+    /// # Return
+    /// If the given index is valid within `self`, [`Some`] is returned with a reference to the
+    /// indexed object. If `self` is not indexable or the index is out of bounds, this function
+    /// returns [`None`].
+    fn get(&self, key: impl Into<Accessor>) -> Option<&Node>;
 }
 
-/// A way to access fields via the [`SafelyIndex`] trait
+/// A trait to index without panicking into a structure through an [`Accessor`] (mutable).
+///
+/// [`SafelyIndexMut`] is implemented on YAML objects to provide the [`get_mut`] method to
+/// conveniently access sequence or mapping elements. This is similar to [`IndexMut`]ing, except
+/// that the [`get_mut`] method returns an [`Option`], using [`None`] rather than panicking when
+/// the requested index is out of range.
+///
+/// [`get_mut`]: SafelyIndexMut::get_mut
+/// [`IndexMut`]: std::ops::Index
+pub trait SafelyIndexMut<Node = Self> {
+    /// Access a field of the given YAML object (mutable).
+    ///
+    /// # Return
+    /// If the given index is valid within `self`, [`Some`] is returned with a reference to the
+    /// indexed object. If `self` is not indexable or the index is out of bounds, this function
+    /// returns [`None`].
+    fn get_mut(&mut self, key: impl Into<Accessor>) -> Option<&mut Node>;
+}
+
+/// A [`SafelyIndex`] / [`SafelyIndexMut`] accessor.
 pub enum Accessor {
-    /// Accessing a string field from a mapping
+    /// Accessing a string field from a mapping.
     Field(String),
-    /// Accessing an element from a sequence
+    /// Accessing an element from a sequence or a mapping.
     Index(usize),
 }
 
@@ -31,63 +62,26 @@ impl From<&str> for Accessor {
     }
 }
 
-impl<Z: SafelyIndex> SafelyIndex<Z> for Option<Z> {
-    fn get(&self, key: impl Into<Accessor>) -> Option<&Z> {
+impl<Node: SafelyIndex> SafelyIndex<Node> for Option<Node> {
+    fn get(&self, key: impl Into<Accessor>) -> Option<&Node> {
         self.as_ref().and_then(|data| data.get(key))
     }
 }
 
-impl<Z: SafelyIndex> SafelyIndex<Z> for Option<&Z> {
-    fn get(&self, key: impl Into<Accessor>) -> Option<&Z> {
-        self.as_ref().and_then(|data| data.get(key))
+impl<Node: SafelyIndexMut> SafelyIndexMut<Node> for Option<Node> {
+    fn get_mut(&mut self, key: impl Into<Accessor>) -> Option<&mut Node> {
+        self.as_mut().and_then(|data| data.get_mut(key))
     }
 }
 
-impl<T: SafelyIndex> SafelyIndex<T> for &T {
-    fn get(&self, key: impl Into<Accessor>) -> Option<&T> {
-        (*self).get(key)
+impl<Node: SafelyIndex> SafelyIndex<Node> for Option<&Node> {
+    fn get(&self, key: impl Into<Accessor>) -> Option<&Node> {
+        self.as_ref().and_then(|data| data.get(key))
     }
 }
 
-#[cfg(test)]
-mod test {
-    use std::string::ToString;
-
-    use crate::{LoadableYamlNode, SafelyIndex, Yaml};
-
-    #[test]
-    fn indexing_into_available_structures() {
-        let node = Yaml::load_from_str(
-            r#"
-person:
-  name: "Jim Halpert"
-  workplace:
-    - name: "Dunder Mifflin"
-      role: "Manager"
-  tenure_years: 5
-"#,
-        )
-        .unwrap()
-        .first()
-        .cloned()
-        .unwrap();
-
-        let name = node
-            .get("person")
-            .get("name")
-            .and_then(|name| name.as_str())
-            .map(ToString::to_string);
-
-        assert!(name.is_some_and(|n| n == "Jim Halpert"));
-
-        let role = node
-            .get("person")
-            .get("workplace")
-            .get(0)
-            .get("role".to_string()) //just for example...
-            .and_then(|role| role.as_str())
-            .map(ToString::to_string);
-
-        assert!(role.is_some_and(|r| r == "Manager"));
+impl<Node: SafelyIndexMut> SafelyIndexMut<Node> for Option<&mut Node> {
+    fn get_mut(&mut self, key: impl Into<Accessor>) -> Option<&mut Node> {
+        self.as_mut().and_then(|data| data.get_mut(key))
     }
 }

saphyr/src/lib.rs

@@ -145,7 +145,7 @@ pub use crate::annotated::{
     AnnotatedSequenceOwned, AnnotatedYamlIter, YamlData, YamlDataOwned,
 };
 pub use crate::emitter::{EmitError, YamlEmitter};
-pub use crate::index::{Accessor, SafelyIndex};
+pub use crate::index::{Accessor, SafelyIndex, SafelyIndexMut};
 pub use crate::loader::{LoadError, LoadableYamlNode, YamlLoader};
 pub use crate::scalar::{parse_core_schema_fp, Scalar, ScalarOwned};
 pub use crate::yaml::{Mapping, Sequence, Yaml, YamlIter};

saphyr/src/macros.rs

@@ -711,6 +711,16 @@ impl $(< $( $generic ),+ >)? crate::index::SafelyIndex<$nodetype> for $yaml $(wh
         }
     }
 }
+
+#[allow(clippy::needless_lifetimes)]
+impl $(< $( $generic ),+ >)? crate::index::SafelyIndexMut<$nodetype> for $yaml $(where $($whereclause)+)? {
+    fn get_mut(&mut self, key: impl Into<crate::index::Accessor>) -> Option<&mut $nodetype> {
+        match key.into() {
+            crate::index::Accessor::Field(f) => self.as_mapping_get_mut(f.as_str()),
+            crate::index::Accessor::Index(i) => self.as_sequence_get_mut(i),
+        }
+    }
+}
     );
 );
 

saphyr/tests/index.rs

@@ -1,4 +1,6 @@
-use saphyr::{LoadableYamlNode, MarkedYaml, Scalar, Yaml, YamlData};
+use std::string::ToString;
+
+use saphyr::{LoadableYamlNode, MarkedYaml, SafelyIndex, SafelyIndexMut, Scalar, Yaml, YamlData};
 
 fn get_yaml_mapping() -> Yaml<'static> {
     let s = "
@@ -188,3 +190,83 @@ fn marked_yaml_index_integer_wrong_variant() {
     let node: MarkedYaml<'_> = YamlData::Value(Scalar::Integer(3)).into();
     let _ = node.data[12];
 }
+
+#[test]
+fn safely_indexing_into_available_structures() {
+    let node = Yaml::load_from_str(
+        r#"
+person:
+  name: "Jim Halpert"
+  workplace:
+    - name: "Dunder Mifflin"
+      role: "Manager"
+  tenure_years: 5
+"#,
+    )
+    .unwrap()
+    .first()
+    .cloned()
+    .unwrap();
+
+    let name = node
+        .get("person")
+        .get("name")
+        .and_then(|name| name.as_str())
+        .map(ToString::to_string);
+
+    assert!(name.is_some_and(|n| n == "Jim Halpert"));
+
+    let role = node
+        .get("person")
+        .get("workplace")
+        .get(0)
+        .get("role".to_string()) //just for example...
+        .and_then(|role| role.as_str())
+        .map(ToString::to_string);
+
+    assert!(role.is_some_and(|r| r == "Manager"));
+}
+
+#[test]
+fn safely_indexing_mut_into_available_structures() {
+    let mut node = Yaml::load_from_str(
+        r#"
+person:
+  name: "Jim Halpert"
+  workplace:
+    - name: "Dunder Mifflin"
+      role: "Manager"
+  tenure_years: 5
+"#,
+    )
+    .unwrap()
+    .first()
+    .cloned()
+    .unwrap();
+
+    *node.get_mut("person").get_mut("name").unwrap() = Yaml::value_from_str("Dwight Schrute");
+    *node
+        .get_mut("person")
+        .get_mut("workplace")
+        .get_mut(0)
+        .get_mut("role")
+        .unwrap() = Yaml::value_from_str("Assistant");
+
+    let name = node
+        .get("person")
+        .get("name")
+        .and_then(|name| name.as_str())
+        .map(ToString::to_string);
+
+    assert!(name.is_some_and(|n| n == "Dwight Schrute"));
+
+    let role = node
+        .get("person")
+        .get("workplace")
+        .get(0)
+        .get("role".to_string()) //just for example...
+        .and_then(|role| role.as_str())
+        .map(ToString::to_string);
+
+    assert!(role.is_some_and(|r| r == "Assistant"));
+}