Adds TOML support, refactors tests, adds Deserialize to Pointer (#48

) * adds TOML support * implements `serde::Deserialize` for `Pointer` * refactors tests * docs, comments and minor cleanup * removes `Pointer::must_parse`, `PointerBuf::must_parse` * re-exports ops traits at root
chanced · Jun 30, 2024 · 1f9853e · 1f9853e
1 parent acd4503
commit 1f9853e
Show file tree

Hide file tree

Showing 12 changed files with 1,871 additions and 603 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -25,6 +25,7 @@ This is a breaking release including:
 
 ### Changed
 
+-   JSON Pointers with leading `"#"` are no longer accepted. Previously, the erroneous leading hashtag was allowed during parsing but discarded.
 -   `Assign`, `Resolve`, `ResolveMut`, `Delete` all now use associated types `Value` and `Error`, allowing for more impls other than JSON
 -   Debug implementation now preserves type information (e.g. prints `PathBuf("/foo/bar")` instead of `"/foo/bar"`) - `Display` remains the same
 -   Original `Pointer` type renamed to `PointerBuf`

diff --git a/Cargo.toml b/Cargo.toml
@@ -20,6 +20,12 @@ quickcheck        = "1.0.3"
 quickcheck_macros = "1.0.0"
 
 [features]
-default = ["std", "json"]
-json    = ["dep:serde_json"]
-std     = ["serde/std", "serde_json?/std"]
+assign  = []
+default = ["std", "serde", "json", "toml", "resolve", "assign", "delete"]
+delete  = []
+impl    = []
+json    = ["dep:serde_json", "serde"]
+resolve = []
+serde   = []
+std     = ["serde/std", "serde_json/std"]
+toml    = ["dep:toml", "serde", "std"]
diff --git a/src/arbitrary.rs b/src/arbitrary.rs
@@ -19,7 +19,7 @@ impl Arbitrary for PointerBuf {
     }
 
     fn shrink(&self) -> Box<dyn Iterator<Item = Self>> {
-        let tokens: Vec<_> = self.tokens().map(|t| t.into_owned()).collect();
+        let tokens: Vec<_> = self.tokens().map(Token::into_owned).collect();
         Box::new((0..self.count()).map(move |i| {
             let subset: Vec<_> = tokens
                 .iter()

diff --git a/src/assign.rs b/src/assign.rs
diff --git a/src/delete.rs b/src/delete.rs
diff --git a/src/index.rs b/src/index.rs
@@ -1,16 +1,16 @@
 //! Abstract index representation for RFC 6901.
 //!
 //! [RFC 6901](https://datatracker.ietf.org/doc/html/rfc6901) defines two valid
-//! ways to represent array indices as Pointer tokens: non-negative integers, and
-//! the character `-`, which stands for the index after the last existing array
-//! member. While attempting to use `-` to access an array is an error, the token
-//! can be useful when paired with [RFC 6902](https://datatracker.ietf.org/doc/
-//! html/rfc6902) as a way to express where to put the new element when extending
-//! an array.
+//! ways to represent array indices as Pointer tokens: non-negative integers,
+//! and the character `-`, which stands for the index after the last existing
+//! array member. While attempting to use `-` to access an array is an error,
+//! the token can be useful when paired with [RFC
+//! 6902](https://datatracker.ietf.org/∑doc/html/rfc6902) as a way to express
+//! where to put the new element when extending an array.
 //!
 //! While this crate doesn't implement RFC 6902, it still must consider
-//! non-numerical indices as valid, and provide a mechanism for manipulating them.
-//! This is what this module provides.
+//! non-numerical indices as valid, and provide a mechanism for manipulating
+//! them. This is what this module provides.
 //!
 //! The main use of the `Index` type is when resolving a [`Token`] instance as a
 //! concrete index for a given array length:
@@ -70,6 +70,8 @@ impl Index {
     /// assert!(Index::Num(1).for_len(1).is_err());
     /// assert!(Index::Next.for_len(1).is_err());
     /// ```
+    /// # Errors
+    /// Returns [`OutOfBoundsError`] if the index is out of bounds.
     pub fn for_len(&self, length: usize) -> Result<usize, OutOfBoundsError> {
         match *self {
             Self::Num(index) if index < length => Ok(index),
@@ -100,6 +102,9 @@ impl Index {
     /// assert_eq!(Index::Next.for_len_incl(1), Ok(1));
     /// assert!(Index::Num(2).for_len_incl(1).is_err());
     /// ```
+    ///
+    /// # Errors
+    /// Returns [`OutOfBoundsError`] if the index is out of bounds.
     pub fn for_len_incl(&self, length: usize) -> Result<usize, OutOfBoundsError> {
         match *self {
             Self::Num(index) if index <= length => Ok(index),
@@ -122,6 +127,7 @@ impl Index {
     /// assert_eq!(Index::Num(42).for_len_unchecked(30), 42);
     /// assert_eq!(Index::Next.for_len_unchecked(30), 30);
     /// ````
+    #[must_use]
     pub fn for_len_unchecked(&self, length: usize) -> usize {
         match *self {
             Self::Num(idx) => idx,

diff --git a/src/lib.rs b/src/lib.rs
@@ -2,17 +2,32 @@
 #![warn(missing_docs)]
 #![deny(clippy::all, clippy::pedantic)]
 #![cfg_attr(not(feature = "std"), no_std)]
+#![allow(
+    clippy::module_name_repetitions,
+    clippy::into_iter_without_iter,
+    clippy::needless_pass_by_value,
+    clippy::expect_fun_call
+)]
 extern crate alloc;
 
 use core::{fmt, num::ParseIntError};
 
 pub mod prelude;
 
+#[cfg(feature = "assign")]
 pub mod assign;
+#[cfg(feature = "assign")]
+pub use assign::Assign;
 
+#[cfg(feature = "delete")]
 pub mod delete;
+#[cfg(feature = "delete")]
+pub use delete::Delete;
 
+#[cfg(feature = "resolve")]
 pub mod resolve;
+#[cfg(feature = "resolve")]
+pub use resolve::{Resolve, ResolveMut};
 
 mod tokens;
 pub use tokens::*;
@@ -29,6 +44,16 @@ pub use index::Index;
 #[cfg(test)]
 mod arbitrary;
 
+/*
+░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
+╔══════════════════════════════════════════════════════════════════════════════╗
+║                                                                              ║
+║                                  ParseError                                  ║
+║                                 ¯¯¯¯¯¯¯¯¯¯¯¯                                 ║
+╚══════════════════════════════════════════════════════════════════════════════╝
+░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
+*/
+
 /// Indicates that a `Pointer` was malformed and unable to be parsed.
 #[derive(Debug, PartialEq)]
 pub enum ParseError {
@@ -63,12 +88,14 @@ impl fmt::Display for ParseError {
 impl ParseError {
     /// Returns `true` if this error is `NoLeadingBackslash`; otherwise returns
     /// `false`.
+    #[must_use]
     pub fn is_no_leading_backslash(&self) -> bool {
         matches!(self, Self::NoLeadingBackslash { .. })
     }
 
     /// Returns `true` if this error is `InvalidEncoding`; otherwise returns
     /// `false`.
+    #[must_use]
     pub fn is_invalid_encoding(&self) -> bool {
         matches!(self, Self::InvalidEncoding { .. })
     }
@@ -85,6 +112,7 @@ impl ParseError {
     /// let err = PointerBuf::parse("/foo/invalid~tilde/invalid").unwrap_err();
     /// assert_eq!(err.pointer_offset(), 4)
     /// ```
+    #[must_use]
     pub fn pointer_offset(&self) -> usize {
         match *self {
             Self::NoLeadingBackslash { .. } => 0,
@@ -93,7 +121,7 @@ impl ParseError {
     }
 
     /// Offset of the character index from within the first token of
-    /// [Self::pointer_offset])
+    /// [`Self::pointer_offset`])
     /// ```text
     /// "/foo/invalid~tilde/invalid"
     ///              ↑
@@ -104,6 +132,7 @@ impl ParseError {
     /// let err = PointerBuf::parse("/foo/invalid~tilde/invalid").unwrap_err();
     /// assert_eq!(err.source_offset(), 8)
     /// ```
+    #[must_use]
     pub fn source_offset(&self) -> usize {
         match self {
             Self::NoLeadingBackslash { .. } => 0,
@@ -122,6 +151,7 @@ impl ParseError {
     /// let err = PointerBuf::parse("/foo/invalid~tilde/invalid").unwrap_err();
     /// assert_eq!(err.pointer_offset(), 4)
     /// ```
+    #[must_use]
     pub fn complete_offset(&self) -> usize {
         self.source_offset() + self.pointer_offset()
     }
@@ -132,11 +162,21 @@ impl std::error::Error for ParseError {
     fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
         match self {
             Self::InvalidEncoding { source, .. } => Some(source),
-            _ => None,
+            Self::NoLeadingBackslash => None,
         }
     }
 }
 
+/*
+░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
+╔══════════════════════════════════════════════════════════════════════════════╗
+║                                                                              ║
+║                               ParseIndexError                                ║
+║                              ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯                               ║
+╚══════════════════════════════════════════════════════════════════════════════╝
+░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
+*/
+
 /// Indicates that the `Token` could not be parsed as valid RFC 6901 index.
 #[derive(Debug, PartialEq, Eq)]
 pub struct ParseIndexError {
@@ -163,6 +203,16 @@ impl std::error::Error for ParseIndexError {
     }
 }
 
+/*
+░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
+╔══════════════════════════════════════════════════════════════════════════════╗
+║                                                                              ║
+║                             InvalidEncodingError                             ║
+║                            ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯                            ║
+╚══════════════════════════════════════════════════════════════════════════════╝
+░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
+*/
+
 /// A token within a json pointer contained invalid encoding (`~` not followed
 /// by `0` or `1`).
 ///
@@ -174,6 +224,7 @@ pub struct InvalidEncodingError {
 
 impl InvalidEncodingError {
     /// The byte offset of the first invalid `~`.
+    #[must_use]
     pub fn offset(&self) -> usize {
         self.offset
     }
@@ -210,6 +261,16 @@ impl std::error::Error for IndexError {
     }
 }
 
+/*
+░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
+╔══════════════════════════════════════════════════════════════════════════════╗
+║                                                                              ║
+║                               OutOfBoundsError                               ║
+║                              ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯                              ║
+╚══════════════════════════════════════════════════════════════════════════════╝
+░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
+*/
+
 /// Indicates that an `Index` is not within the given bounds.
 #[derive(Debug, PartialEq, Eq)]
 pub struct OutOfBoundsError {
@@ -239,10 +300,20 @@ impl fmt::Display for OutOfBoundsError {
 #[cfg(feature = "std")]
 impl std::error::Error for OutOfBoundsError {}
 
-/// NotFoundError indicates that a Pointer's path was not found in the data.
+/*
+░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
+╔══════════════════════════════════════════════════════════════════════════════╗
+║                                                                              ║
+║                                NotFoundError                                 ║
+║                               ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯                                ║
+╚══════════════════════════════════════════════════════════════════════════════╝
+░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
+*/
+
+/// An error that indicates a [`Pointer`]'s path was not found in the data.
 #[derive(Debug, PartialEq, Eq)]
 pub struct NotFoundError {
-    /// The starting offset of the `Token` within the `Pointer` which could not
+    /// The starting offset of the [`Token`] within the [`Pointer`] which could not
     /// be resolved.
     pub offset: usize,
 }
@@ -256,6 +327,16 @@ impl fmt::Display for NotFoundError {
 #[cfg(feature = "std")]
 impl std::error::Error for NotFoundError {}
 
+/*
+░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
+╔══════════════════════════════════════════════════════════════════════════════╗
+║                                                                              ║
+║                              ReplaceTokenError                               ║
+║                             ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯                              ║
+╚══════════════════════════════════════════════════════════════════════════════╝
+░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
+*/
+
 /// Returned from `Pointer::replace_token` when the provided index is out of
 /// bounds.
 #[derive(Debug, PartialEq, Eq)]