Crate jmespath

Rust implementation of JMESPath, a query language for JSON.

Compiling JMESPath expressions

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

use jmespath;

let expr = jmespath::compile("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::compile("foo").unwrap();
assert_eq!("foo", expr.as_str());
assert_eq!(&Ast::Field {name: "foo".to_string(), offset: 0}, expr.as_ast());

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, Rcvar (or jmespath::Rcvar) is used to allow shared, reference counted data to be used by the JMESPath interpreter at runtime.

By default, Rcvar is an std::rc::Rc<Variable>. However, by specifying the sync feature, you can utilize an std::sync::Arc<Variable> to share Expression structs across threads.

Any type that implements jmespath::ToJmespath can be used in a JMESPath Expression. Various types have default ToJmespath implementations, including serde::ser::Serialize. 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. 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. 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.

Custom Functions

You can register custom functions with a JMESPath expression by using a custom Runtime. When you call jmespath::compile, you are using a shared Runtime instance that is created lazily using lazy_static. This shared Runtime utilizes all of the builtin JMESPath functions by default. However, custom functions may be utilized by creating a custom Runtime and compiling expressions directly from the Runtime.

use jmespath::{Runtime, Context, Rcvar};
use jmespath::functions::{CustomFunction, Signature, ArgumentType};

// Create a new Runtime and register the builtin JMESPath functions.
let mut runtime = Runtime::new();
runtime.register_builtin_functions();

// Create an identity string function that returns string values as-is.
runtime.register_function("str_identity", Box::new(CustomFunction::new(
    Signature::new(vec![ArgumentType::String], None),
    Box::new(|args: &[Rcvar], _: &mut Context| Ok(args[0].clone()))
)));

// You can also use normal closures as functions.
runtime.register_function("identity",
    Box::new(|args: &[Rcvar], _: &mut Context| Ok(args[0].clone())));

let expr = runtime.compile("str_identity('foo')").unwrap();
assert_eq!("foo", expr.search(()).unwrap().as_string().unwrap());

let expr = runtime.compile("identity('bar')").unwrap();
assert_eq!("bar", expr.search(()).unwrap().as_string().unwrap());

Modules

ast

JMESPath abstract syntax tree (AST).

functions

JMESPath functions.

Structs

Context

Context object used for error reporting.

DEFAULT_RUNTIME

Expression

A compiled JMESPath expression.

JmespathError

JMESPath error.

Runtime

Compiles JMESPath expressions.

Enums

ErrorReason

Error context to provide specific details about an error.

RuntimeError

Runtime JMESPath error

Variable

JMESPath variable.

Traits

ToJmespath

Converts a value into a reference-counted JMESPath Variable.

Functions

compile

Compiles a JMESPath expression using the default Runtime.

parse

Parses a JMESPath expression into an AST.

Type Aliases

ParseResult

Result of parsing an expression.

Rcvar

Rc reference counted JMESPath Variable.