Skip to content

Commit

Permalink
utilizes rustdoc link hack
Browse files Browse the repository at this point in the history
  • Loading branch information
@chanced
chanced committed Jul 8, 2024
1 parent bf0e55f commit e6e91af
Show file tree
Hide file tree
Showing 3 changed files with 107 additions and 32 deletions.
73 changes: 58 additions & 15 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,8 @@
# jsonptr - JSON Pointers (RFC 6901)
<div class="rustdoc-hidden">

# jsonptr - JSON Pointers (RFC 6901) for Rust

</div>

[<img alt="github" src="https://img.shields.io/badge/github-chanced/jsonptr-62D1FC?style=for-the-badge&labelColor=777&logo=github" height="21">](https://github.com/chanced/jsonptr)
[<img alt="crates.io" src="https://img.shields.io/crates/v/jsonptr.svg?style=for-the-badge&color=fc8d62&logo=rust" height="21">](https://crates.io/crates/jsonptr)
Expand All @@ -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
Expand Down Expand Up @@ -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.

<div class="rustdoc-hidden">
## 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

</div>

[`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
22 changes: 22 additions & 0 deletions src/lib.rs
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,25 @@
// rustdoc + README hack: https://linebender.org/blog/doc-include
//! <style>
//! .rustdoc-hidden { display: none; }
//! </style>
//!
//! [`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)]
Expand Down
44 changes: 27 additions & 17 deletions src/pointer.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand Down Expand Up @@ -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`

Check failure on line 268 in src/pointer.rs

View workflow job for this annotation

GitHub Actions / clippy

[clippy] src/pointer.rs#L268 

error: doc list item missing indentation
   --> src/pointer.rs:268:9
    |
268 |     /// [`R::Value`]: `crate::resolve::Resolve::Value`
    |         ^
    |
    = help: if this is supposed to be its own paragraph, add a blank line
    = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#doc_lazy_continuation
help: indent this line
    |
268 |     ///   [`R::Value`]: `crate::resolve::Resolve::Value`
    |         ++
Raw output 
src/pointer.rs:268:9:e:error: doc list item missing indentation
   --> src/pointer.rs:268:9
    |
268 |     /// [`R::Value`]: `crate::resolve::Resolve::Value`
    |         ^
    |
    = help: if this is supposed to be its own paragraph, add a blank line
    = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#doc_lazy_continuation
help: indent this line
    |
268 |     ///   [`R::Value`]: `crate::resolve::Resolve::Value`
    |         ++


__END__
/// [`R::Error`]: `crate::resolve::Resolve::Error`

Check failure on line 269 in src/pointer.rs

View workflow job for this annotation

GitHub Actions / clippy

[clippy] src/pointer.rs#L269 

error: doc list item missing indentation
   --> src/pointer.rs:269:9
    |
269 |     /// [`R::Error`]: `crate::resolve::Resolve::Error`
    |         ^
    |
    = help: if this is supposed to be its own paragraph, add a blank line
    = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#doc_lazy_continuation
help: indent this line
    |
269 |     ///   [`R::Error`]: `crate::resolve::Resolve::Error`
    |         ++
Raw output 
src/pointer.rs:269:9:e:error: doc list item missing indentation
   --> src/pointer.rs:269:9
    |
269 |     /// [`R::Error`]: `crate::resolve::Resolve::Error`
    |         ^
    |
    = help: if this is supposed to be its own paragraph, add a blank line
    = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#doc_lazy_continuation
help: indent this line
    |
269 |     ///   [`R::Error`]: `crate::resolve::Resolve::Error`
    |         ++


__END__
/// [`Resolve`]: `crate::resolve::Resolve`

Check failure on line 270 in src/pointer.rs

View workflow job for this annotation

GitHub Actions / clippy

[clippy] src/pointer.rs#L270 

error: doc list item missing indentation
   --> src/pointer.rs:270:9
    |
270 |     /// [`Resolve`]: `crate::resolve::Resolve`
    |         ^
    |
    = help: if this is supposed to be its own paragraph, add a blank line
    = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#doc_lazy_continuation
help: indent this line
    |
270 |     ///   [`Resolve`]: `crate::resolve::Resolve`
    |         ++
Raw output 
src/pointer.rs:270:9:e:error: doc list item missing indentation
   --> src/pointer.rs:270:9
    |
270 |     /// [`Resolve`]: `crate::resolve::Resolve`
    |         ^
    |
    = help: if this is supposed to be its own paragraph, add a blank line
    = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#doc_lazy_continuation
help: indent this line
    |
270 |     ///   [`Resolve`]: `crate::resolve::Resolve`
    |         ++


__END__
/// [`ResolveError`]: `crate::resolve::ResolveError`

Check failure on line 271 in src/pointer.rs

View workflow job for this annotation

GitHub Actions / clippy

[clippy] src/pointer.rs#L271 

error: doc list item missing indentation
   --> src/pointer.rs:271:9
    |
271 |     /// [`ResolveError`]: `crate::resolve::ResolveError`
    |         ^
    |
    = help: if this is supposed to be its own paragraph, add a blank line
    = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#doc_lazy_continuation
help: indent this line
    |
271 |     ///   [`ResolveError`]: `crate::resolve::ResolveError`
    |         ++
Raw output 
src/pointer.rs:271:9:e:error: doc list item missing indentation
   --> src/pointer.rs:271:9
    |
271 |     /// [`ResolveError`]: `crate::resolve::ResolveError`
    |         ^
    |
    = help: if this is supposed to be its own paragraph, add a blank line
    = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#doc_lazy_continuation
help: indent this line
    |
271 |     ///   [`ResolveError`]: `crate::resolve::ResolveError`
    |         ++


__END__
/// [`Token`]: crate::Token

Check failure on line 272 in src/pointer.rs

View workflow job for this annotation

GitHub Actions / clippy

[clippy] src/pointer.rs#L272 

error: doc list item missing indentation
   --> src/pointer.rs:272:9
    |
272 |     /// [`Token`]: crate::Token
    |         ^
    |
    = help: if this is supposed to be its own paragraph, add a blank line
    = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#doc_lazy_continuation
help: indent this line
    |
272 |     ///   [`Token`]: crate::Token
    |         ++
Raw output 
src/pointer.rs:272:9:e:error: doc list item missing indentation
   --> src/pointer.rs:272:9
    |
272 |     /// [`Token`]: crate::Token
    |         ^
    |
    = help: if this is supposed to be its own paragraph, add a blank line
    = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#doc_lazy_continuation
help: indent this line
    |
272 |     ///   [`Token`]: crate::Token
    |         ++


__END__

Check failure on line 272 in src/pointer.rs

View workflow job for this annotation

GitHub Actions / clippy

[clippy] src/pointer.rs#L272 

error: item in documentation is missing backticks
   --> src/pointer.rs:272:20
    |
272 |     /// [`Token`]: crate::Token
    |                    ^^^^^^^^^^^^
    |
    = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#doc_markdown
note: the lint level is defined here
   --> src/lib.rs:25:22
    |
25  | #![deny(clippy::all, clippy::pedantic)]
    |                      ^^^^^^^^^^^^^^^^
    = note: `#[deny(clippy::doc_markdown)]` implied by `#[deny(clippy::pedantic)]`
help: try
    |
272 |     /// [`Token`]: `crate::Token`
    |                    ~~~~~~~~~~~~~~
Raw output 
src/pointer.rs:272:20:e:error: item in documentation is missing backticks
   --> src/pointer.rs:272:20
    |
272 |     /// [`Token`]: crate::Token
    |                    ^^^^^^^^^^^^
    |
    = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#doc_markdown
note: the lint level is defined here
   --> src/lib.rs:25:22
    |
25  | #![deny(clippy::all, clippy::pedantic)]
    |                      ^^^^^^^^^^^^^^^^
    = note: `#[deny(clippy::doc_markdown)]` implied by `#[deny(clippy::pedantic)]`
help: try
    |
272 |     /// [`Token`]: `crate::Token`
    |                    ~~~~~~~~~~~~~~


__END__
/// [`Index`]: crate::index::Index

Check failure on line 273 in src/pointer.rs

View workflow job for this annotation

GitHub Actions / clippy

[clippy] src/pointer.rs#L273 

error: doc list item missing indentation
   --> src/pointer.rs:273:9
    |
273 |     /// [`Index`]: crate::index::Index
    |         ^
    |
    = help: if this is supposed to be its own paragraph, add a blank line
    = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#doc_lazy_continuation
help: indent this line
    |
273 |     ///   [`Index`]: crate::index::Index
    |         ++
Raw output 
src/pointer.rs:273:9:e:error: doc list item missing indentation
   --> src/pointer.rs:273:9
    |
273 |     /// [`Index`]: crate::index::Index
    |         ^
    |
    = help: if this is supposed to be its own paragraph, add a blank line
    = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#doc_lazy_continuation
help: indent this line
    |
273 |     ///   [`Index`]: crate::index::Index
    |         ++


__END__

Check failure on line 273 in src/pointer.rs

View workflow job for this annotation

GitHub Actions / clippy

[clippy] src/pointer.rs#L273 

error: item in documentation is missing backticks
   --> src/pointer.rs:273:20
    |
273 |     /// [`Index`]: crate::index::Index
    |                    ^^^^^^^^^^^^^^^^^^^
    |
    = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#doc_markdown
help: try
    |
273 |     /// [`Index`]: `crate::index::Index`
    |                    ~~~~~~~~~~~~~~~~~~~~~
Raw output 
src/pointer.rs:273:20:e:error: item in documentation is missing backticks
   --> src/pointer.rs:273:20
    |
273 |     /// [`Index`]: crate::index::Index
    |                    ^^^^^^^^^^^^^^^^^^^
    |
    = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#doc_markdown
help: try
    |
273 |     /// [`Index`]: `crate::index::Index`
    |                    ~~~~~~~~~~~~~~~~~~~~~


__END__
#[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,
Expand Down Expand Up @@ -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
Expand Down

0 comments on commit e6e91af

Please sign in to comment.