Crate jmespath [−] [src]
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. |
to_variable |
Shortcut function to encode a |
Type Definitions
ParseResult |
Result of parsing an expression. |
Rcvar |
|