diff --git a/README.md b/README.md index bc92461..0f8e04a 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,8 @@ -# jsonptr - JSON Pointers (RFC 6901) +
+ +# jsonptr - JSON Pointers (RFC 6901) for Rust + +
[github](https://github.com/chanced/jsonptr) [crates.io](https://crates.io/crates/jsonptr) @@ -17,15 +21,14 @@ either `'/'` or the end of the string. [`Token`]s are lightly encoded, where `'~'` is escaped as `"~0"` and `'/'` as `"~1"`. [`Token`]s can be iterated over using either [`Tokens`], returned from the -[`tokens`](`Pointer::tokens`) method of a pointer or [`Components`], returned -from the [`components`](`Pointer::components`) method. The difference being that -[`Tokens`] iterates over each [`Token`] in the [`Pointer`], while a -[`Component`] can represent the [`Root`](Component::Root) document or a single -[`Token`](Component::Token). +[`tokens`] method of a pointer or [`Components`], returned from the +[`components`] method. The difference being that [`Tokens`] iterates over each +[`Token`] in the [`Pointer`], while a [`Component`] can represent the +[`Root`](Component::Root) document or a single [`Token`](Component::Token). Operations [`resolve`], [`assign`] and [`delete`] are provided as traits with corresponding methods on [`Pointer`]. Implementations of each trait are provided -for [`serde_json::Value`] and [`toml::Value`](https://docs.rs/toml/0.8). All +for [`serde_json::Value`] and [`toml::Value`]. All operations are enabled by default but are gated by [feature flags](#feature-flags). ## Usage @@ -100,17 +103,57 @@ assert_eq!(data, json!({"secret": { "universe": 34 }})); | `"std"` | Implements `std::error::Error` for error types | | ✓ | | `"serde"` | Enables [`serde`] support for types | | ✓ | | `"json"` | Implements ops for [`serde_json::Value`] | `"serde"` | ✓ | -| `"toml"` | Implements ops for [`toml::Value`](https://docs.rs/toml/0.8) | `"std"`, `toml` | | +| `"toml"` | Implements ops for [`toml::Value`] | `"std"`, `toml` | | | `"assign"` | Enables the [`assign`] module and related pointer methods, providing a means to assign a value to a specific location within a document | | ✓ | | `"resolve"` | Enables the [`resolve`] module and related pointer methods, providing a means to resolve a value at a specific location within a document | | ✓ | | `"delete"` | Enables the [`delete`] module and related pointer methods, providing a means to delete a value at a specific location within a document | `"resolve"` | ✓ | -## Contributions / Issues - -Contributions and feedback are always welcome and appreciated. - -If you find an issue, please open a ticket or a pull request. - +
## License -MIT or Apache 2.0. +Licensed under either of + +- Apache License, Version 2.0 + ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0) +- MIT license + ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT) + +at your option. + +## Contribution + +Contributions and feedback are always welcome and appreciated. If you find an +issue, please open a ticket or a pull request. + +Unless you explicitly state otherwise, any contribution intentionally submitted +for inclusion in the work by you, as defined in the Apache-2.0 license, shall be +dual licensed as above, without any additional terms or conditions. + +[LICENSE-APACHE]: LICENSE-APACHE +[LICENSE-MIT]: LICENSE-MIT + +
+ +[`Pointer::components`]: (https://docs.rs/jsonptr/latest/jsonptrstruct.Pointer.html#method.components) +[`Pointer::tokens`]: (https://docs.rs/jsonptr/latest/jsonptrstruct.Pointer.html#method.tokens) +[`Pointer`]: https://docs.rs/jsonptr/latest/jsonptr/struct.Pointer.html +[`PointerBuf`]: https://docs.rs/jsonptr/latest/jsonptr/struct.PointerBuf.html +[`Token`]: https://docs.rs/jsonptr/latest/jsonptr/struct.Token.html +[`Tokens`]: https://docs.rs/jsonptr/latest/jsonptr/struct.Tokens.html +[`Components`]: https://docs.rs/jsonptr/latest/jsonptr/struct.Components.html +[`Component`]: https://docs.rs/jsonptr/latest/jsonptr/enum.Component.html +[`Root`]: https://docs.rs/jsonptr/latest/jsonptr/enum.Component.html#variant.Root +[`index`]: https://doc.rust-lang.org/std/primitive.usize.html +[`tokens`]: https://docs.rs/jsonptr/latest/jsonptr/struct.Pointer.html#method.tokens +[`components`]: https://docs.rs/jsonptr/latest/jsonptr/struct.Pointer.html#method.components +[`resolve`]: https://docs.rs/jsonptr/latest/jsonptr/resolve/index.html +[`assign`]: https://docs.rs/jsonptr/latest/jsonptr/assign/index.html +[`delete`]: https://docs.rs/jsonptr/latest/jsonptr/delete/index.html +[`Resolve`]: https://docs.rs/jsonptr/latest/jsonptr/resolve/trait.Resolve.html +[`ResolveMut`]: https://docs.rs/jsonptr/latest/jsonptr/resolve/trait.ResolveMut.html +[`Assign`]: https://docs.rs/jsonptr/latest/jsonptr/assign/trait.Assign.html +[`Delete`]: https://docs.rs/jsonptr/latest/jsonptr/delete/trait.Delete.html +[`serde`]: https://docs.rs/serde/1.0.120/serde/index +[`serde_json::Value`]: https://docs.rs/serde_json/1.0.120/serde_json/enum.Value.html +[`str`]: https://doc.rust-lang.org/std/primitive.str.html +[`String`]: https://doc.rust-lang.org/std/string/struct.String.html diff --git a/src/lib.rs b/src/lib.rs index 2428dc5..4dbe9f0 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,3 +1,25 @@ +// rustdoc + README hack: https://linebender.org/blog/doc-include +//! +//! +//! [`Pointer`]: crate::Pointer +//! [`PointerBuf`]: crate::PointerBuf +//! [`Token`]: crate::Token +//! [`Tokens`]: crate::Tokens +//! [`Component`]: crate::Component +//! [`Components`]: crate::Components +//! [`Resolve`]: crate::resolve::Resolve +//! [`ResolveMut`]: crate::resolve::ResolveMut +//! [`resolve`]: crate::resolve +//! [`assign`]: crate::assign +//! [delete]: crate::delete +//! [index]: crate::index +//! [str]: str +//! [String]: String +//! [serde_json::Value]: serde_json::Value +//! [toml::Value]: https://docs.rs/toml/0.8/toml/enum.Value.html + #![doc = include_str!("../README.md")] #![warn(missing_docs)] #![deny(clippy::all, clippy::pedantic)] diff --git a/src/pointer.rs b/src/pointer.rs index 7a1b6f5..3db4009 100644 --- a/src/pointer.rs +++ b/src/pointer.rs @@ -18,7 +18,7 @@ use core::{borrow::Borrow, cmp::Ordering, ops::Deref, str::FromStr}; */ /// A JSON Pointer is a string containing a sequence of zero or more reference -/// tokens, each prefixed by a '/' character. +/// [`Token`]s, each prefixed by a `'/'` character. /// /// See [RFC 6901 for more /// information](https://datatracker.ietf.org/doc/html/rfc6901). @@ -252,43 +252,53 @@ impl Pointer { self.tokens().nth(index).clone() } - /// Attempts to resolve a `Value` based on the path in this `Pointer`. + /// Attempts to resolve a [`R::Value`] based on the path in this [`Pointer`]. /// /// ## Errors - /// Returns [`R::Error`](`Resolve::Error`) if an error occurs while - /// resolving. + /// Returns [`R::Error`] if an error occurs while resolving. /// /// The rules of such are determined by the `R`'s implementation of - /// [`Resolve`] but provided implementations return - /// [`ResolveError`](crate::resolve::ResolveError) if: + /// [`Resolve`] but provided implementations return [`ResolveError`] if: /// - The path is unreachable (e.g. a scalar is encountered prior to the end /// of the path) /// - The path is not found (e.g. a key in an object or an index in an array /// does not exist) - /// - A [`Token`](crate::Token) cannot be parsed as an array - /// [`Index`](crate::index::Index) - /// - An array [`Index`](crate::index::Index) is out of bounds + /// - A [`Token`] cannot be parsed as an array [`Index`] + /// - An array [`Index`] is out of bounds + /// [`R::Value`]: `crate::resolve::Resolve::Value` + /// [`R::Error`]: `crate::resolve::Resolve::Error` + /// [`Resolve`]: `crate::resolve::Resolve` + /// [`ResolveError`]: `crate::resolve::ResolveError` + /// [`Token`]: crate::Token + /// [`Index`]: crate::index::Index #[cfg(feature = "resolve")] pub fn resolve<'v, R: crate::Resolve>(&self, value: &'v R) -> Result<&'v R::Value, R::Error> { value.resolve(self) } - /// Attempts to resolve a mutable `Value` based on the path in this `Pointer`. + /// Attempts to resolve a mutable [`R::Value`] based on the path in this + /// `Pointer`. /// /// ## Errors - /// Returns [`R::Error`](`ResolveMut::Error`) if an error occurs while + /// Returns [`R::Error`] if an error occurs while /// resolving. /// /// The rules of such are determined by the `R`'s implementation of - /// [`ResolveMut`] but provided implementations return - /// [`ResolveError`](crate::resolve::ResolveError) if: + /// [`ResolveMut`] but provided implementations return [`ResolveError`] if: /// - The path is unreachable (e.g. a scalar is encountered prior to the end /// of the path) /// - The path is not found (e.g. a key in an object or an index in an array /// does not exist) - /// - A [`Token`](crate::Token) cannot be parsed as an array - /// [`Index`](crate::index::Index) - /// - An array [`Index`](crate::index::Index) is out of bounds + /// - A [`Token`] cannot be parsed as an array [`Index`] + /// - An array [`Index`] is out of bounds + /// + /// [`R::Value`]: `crate::resolve::ResolveMut::Value` + /// [`R::Error`]: `crate::resolve::ResolveMut::Error` + /// [`ResolveMut`]: `crate::resolve::ResolveMut` + /// [`ResolveError`]: `crate::resolve::ResolveError` + /// [`Token`]: crate::Token + /// [`Index`]: crate::index::Index + #[cfg(feature = "resolve")] pub fn resolve_mut<'v, R: crate::ResolveMut>( &self, @@ -684,7 +694,7 @@ impl<'a> IntoIterator for &'a Pointer { ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ */ -/// An owned, mutable Pointer (akin to String). +/// An owned, mutable [`Pointer`] (akin to `String`). /// /// This type provides methods like [`PointerBuf::push_back`] and /// [`PointerBuf::replace_token`] that mutate the pointer in place. It also