rsonpath-syntax 0.4.0

A JSONPath parser.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74

# `rsonpath-syntax` – JSONPath parser

[![Rust](https://github.com/V0ldek/rsonpath/actions/workflows/rust.yml/badge.svg)](https://github.com/V0ldek/rsonpath/actions/workflows/rust.yml)
[![docs.rs](https://img.shields.io/docsrs/rsonpath-syntax?logo=docs.rs)](https://docs.rs/crate/rsonpath-syntax/latest)

[![Crates.io](https://img.shields.io/crates/v/rsonpath-syntax?logo=docs.rs)](https://crates.io/crates/rsonpath-syntax)

![MSRV](https://img.shields.io/badge/msrv-v1.67.1-orange?logo=rust "Minimum Supported Rust Version for `rsonpath-syntax`")
[![License](https://img.shields.io/crates/l/rsonpath)](https://choosealicense.com/licenses/mit/)

Complete, fast, and fully spec-compliant JSONPath query parser.

## Usage

Parse a query to its AST with the `parse` function.

```rust
let query = rsonpath_syntax::parse("$.jsonpath[*]")?;
```

For advanced usage consult the crate documentation.

## Feature flags

There are three optional features:

- `arbitrary`, which enables a dependency on the [`arbitrary` crate](https://docs.rs/arbitrary/latest/arbitrary/) to provide `Arbitrary` implementations on query types; this is used e.g. for fuzzing.
- `color`, which enables a dependency on the [`owo_colors` crate](https://docs.rs/owo-colors/latest/owo_colors/) to provide colorful `Display` representations of `ParseError` with the `colored` function.
- `serde`, which enables a dependency on the [`serde` crate](https://docs.rs/serde/latest/serde/) to provide serialization and deserialization of `JsonPathQuery` and all the underlying types.

## Examples

There are two examples programs, [`builder`](./examples/builder.rs) showcases usage of the `JsonPathQueryBuilder`
struct; [`cli`](./examples/cli.rs) is a small CLI tool that takes one argument, a query to parse, and prints a debug representation of the result query, or an error message – this is useful for debugging when developing the crate itself.

## State of the crate

This is an in-development version that supports only name, index, and wildcard selectors.
However, these are fully supported, tested, and fuzzed. The planned roadmap is:

- [x] support slices
- [x] support filters (without functions)
- [ ] support functions (including type check)
- [ ] polish the API
- [ ] 1.0.0 stable release

## Dependencies

Showing direct dependencies.

```bash
cargo tree --package rsonpath-lib --edges normal --depth 1 --target=all --all-features
```

<!-- rsonpath-syntax dependencies start -->
```ini
rsonpath-syntax v0.4.0 (/home/mat/src/rsonpath/crates/rsonpath-syntax)
├── arbitrary v1.4.1
├── nom v7.1.3
├── owo-colors v4.1.0
├── serde v1.0.217
├── thiserror v2.0.9
└── unicode-width v0.2.0
```
<!-- rsonpath-syntax dependencies end -->

### Justification

- `arbitrary` &ndash; optional `Arbitrary` support for fuzzing.
- `nom` &ndash; combinator-based parsing used throughout the crate.
- `owo-colors` &ndash; optional feature for pretty error messages.
- `serde` &ndash; optional dependency for serialization and deserialization of compiled engines.
- `thiserror` &ndash; idiomatic `Error` implementations.
- `unicode-width` &ndash; used to display error messages correctly in presence of wider Unicode characters in the query string.