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 |