Crate jmespath [−] [src]

Rust implementation of JMESPath, a query language for JSON.

Usage

This crate is on crates.io and can be used by adding jmespath to the dependencies in your project's Cargo.toml.

[dependencies]
jmespath = "0.0.1"

and this to your crate root:

extern crate jmespath;

Compiling JMESPath expressions

Use the jmespath::Expression struct to compile and execute JMESPath expressions. The Expression struct can be used multiple times on different values without having to recompile the expression.

use jmespath;

let expr = jmespath::Expression::new("foo.bar | baz").unwrap();

// Parse some JSON data into a JMESPath variable
let json_str = "{\"foo\":{\"bar\":{\"baz\":true}}}";
let data = jmespath::Variable::from_json(json_str).unwrap();

// Search the data with the compiled expression
let result = expr.search(data).unwrap();
assert_eq!(true, result.as_boolean().unwrap());

You can get the original expression as a string and the parsed expression AST from the Expression struct:

use jmespath;
use jmespath::ast::Ast;

let expr = jmespath::Expression::new("foo").unwrap();
assert_eq!("foo", expr.as_str());
assert_eq!(&Ast::Field {name: "foo".to_string(), offset: 0}, expr.as_ast());

Using `jmespath::search`

The jmespath::search function can be used for more simplified searching when expression reuse is not important. jmespath::search will compile the given expression and evaluate the expression against the provided data.

use jmespath;

let data = jmespath::Variable::from_json("{\"foo\":null}").unwrap();
let result = jmespath::search("foo", data).unwrap();
assert!(result.is_null());

JMESPath variables

In order to evaluate expressions against a known data type, the jmespath::Variable enum is used as both the input and output type. More specifically, Rc<Variable> (or jmespath::RcVar) is used to allow shared, reference counted data to be used by the JMESPath interpreter at runtime.

Because jmespath::Variable implements serde::ser::Serialize, many existing types can be searched without needing an explicit coercion, and any type that needs coercion can be implemented using serde's macros or code generation capabilities. Any value that implements the serde::ser::Serialize trait can be searched without needing explicit coercions. This includes a number of common types, including serde's serde_json::Value enum.

The return value of searching data with JMESPath is also an RcVar (an Rc<Variable>). Variable has a number of helper methods that make it a data type that can be used directly, or you can convert Variable to any serde value implementing serde::de::Deserialize.

// Search an arbitrary data type that implements serde::ser::Serialize
let data = vec![true, false];
// Get the result as an RcVar
let result = jmespath::search("[0]", data).unwrap();
// Convert the result to a type that implements serde::de::Deserialize
let my_bool: bool = result.to_deserialize().unwrap();
assert_eq!(true, my_bool);

Modules

ast	JMESPath AST
functions	JMESPath functions.
interpreter	Interprets JMESPath expressions

Macros

validate_args!

Macro used to variadically validate validate Variable and argument arity.

Structs

Coordinates	Defines the coordinates to a position in an expression string.
Error	JMESPath error
Expression	A compiled JMESPath expression.

Enums

ErrorReason	Error context provides specific details about an error.
RuntimeError	Runtime JMESPath error
Variable	JMESPath variable.

Functions

parse	Parses a JMESPath expression into an AST
search	Parses an expression and performs a search over the data.
tokenize	Tokenizes a JMESPath expression.

Type Definitions

ParseResult	Result of parsing an expression.
RcVar