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,
• and 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 supports only name, index, and wildcard selectors. However, these 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:

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")
))));

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.
• str
  JSON string types expressible in a JSONPath query.

Structs

• 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.
• Slice
  Slice selector defining the start and end bounds, as well as the step value and direction.
• SliceBuilder
  Helper API for programmatically constructing Slice instances.

Enums

• Index
  Directional index into a JSON array.
• 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.
• Step
  Directional step offset within a JSON array.

Functions

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

Type Aliases

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