Crate rsonpath_syntax

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

The crate exposes the JsonPathQuery type and the parse function that converts a query string into the AST representation. The parsing complies with the proposed JSONPath RFC specification.

A JSONPath query is a sequence of segments, each containing one or more selectors. There are two types of segments:

• child (Segment::Child), and
• descendant (Segment::Descendant);

and five different types of selectors:

• name (Selector::Name),
• wildcard (Selector::Wildcard),
• index (Selector::Index),
• slice (Selector::Slice),
• and filter (Selector::Filter).

Descriptions of each segment and selector can be found in the documentation of the relevant type in this crate, while the formal grammar is described in the RFC.

State of the crate

This is an in-development version that does not yet support functions in filter expressions. However, all other constructs are fully supported, tested, and fuzzed. The planned roadmap is:

• support slices
• support filters (without functions)
• support functions (including type check)
• polish the API
• 1.0.0 stable release

Examples

To create a query from a query string:

use rsonpath_syntax::prelude::*;
let query_string = "$..phoneNumbers[*].number";
let query = rsonpath_syntax::parse(query_string)?;

// Query structure is a linear sequence of segments:
// Descendant '..phoneNumbers', child wildcard, child 'number'.
assert_eq!(query.segments().len(), 3);
assert_eq!(
  query.segments()[0],
  Segment::Descendant(
    Selectors::one(
      Selector::Name(
        JsonString::new("phoneNumbers")
))));
assert_eq!(
  query.segments()[1],
  Segment::Child(
    Selectors::one(
      Selector::Wildcard
)));
assert_eq!(
  query.segments()[2],
  Segment::Child(
    Selectors::one(
      Selector::Name(
        JsonString::new("number")
))));

// Queries stringify to a canonical representation.
assert_eq!(query.to_string(), "$..['phoneNumbers'][*]['number']");

Constructing queries programmatically is more ergonomic with the provided builder interface. For example, to construct the same query as above:

use rsonpath_syntax::builder::JsonPathQueryBuilder;

let mut query_builder = JsonPathQueryBuilder::new();
query_builder
  .descendant_name("phoneNumbers")
  .child_wildcard()
  .child_name("number");
let query = query_builder.into_query();

assert_eq!(query.to_string(), "$..['phoneNumbers'][*]['number']");

Crate features

There are two optional features:

• arbitrary, which enables a dependency on the arbitrary crate to provide Arbitrary implementations on query types; this is used e.g. for fuzzing.
• color, which enables a dependency on the owo_colors crate to provide colorful Display representations of ParseError; see ParseError::colored.

Modules

• builder
  Utility for building a JsonPathQuery programmatically.
• error
  Error types for the crate.
• num
  JSON number types expressible in a JSONPath query.
• prelude
  Public reexports of the JSONPath query object model, parsing and building entrypoints.
• str
  JSON string types expressible in a JSONPath query.

Structs

• ComparisonExpr
  Comparison based on two singular values and a comparison operator.
• JsonPathQuery
  JSONPath query structure represented by a sequence of Segments.
• Parser
  JSONPath query parser.
• ParserBuilder
  Configurable builder for a Parser instance.
• Selectors
  Collection of one or more Selector instances.
• SingularJsonPathQuery
  Singular JSONPath query.
• Slice
  Slice selector defining the start and end bounds, as well as the step value and direction.

Enums

• Comparable
  One of the sides of a ComparisonExpr, either a constant literal or a singular JSONPath query.
• ComparisonOp
  Comparison operator usable in a ComparisonExpr.
• Index
  Directional index into a JSON array.
• Literal
  JSON literal value available in comparison expressions of a filter selector.
• LogicalExpr
  Logical expression used in a Filter selector.
• Segment
  JSONPath query segment.
• Selector
  Each Segment defines one or more selectors. A selector produces one or more children/descendants of the node it is applied to.
• SingularSegment
  Segment allowed in a SingularJsonPathQuery.
• Step
  Directional step offset within a JSON array.
• TestExpr
  Existence test based on a relative or absolute JsonPathQuery.

Functions

• parse
  Parse a JSONPath query string using default Parser configuration.

Type Aliases

• Result
  Convenience alias for Result values returned by this crate.