Crate jmespath_community

JMESPath Community is the community implementation of JMESPath, a query and transformation language for JSON.

Evaluating JMESPath Expression

Use the search function to evaluate a JMESPath expression.

Example

use jmespath_community as jmespath;
use jmespath::{search, Value};

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

let result = search("foo.bar | baz", &data).unwrap();
assert_eq!(true, result);

A JMESPath expression can be parsed once and evaluated multiple times using the parse function.

Example

use jmespath_community as jmespath;
use jmespath::{parse, Value};

let ast = parse("foo").unwrap();
let data = Value::from_json(r#"{"foo": "bar"}"#).unwrap();
let result = ast.search(&data).unwrap();
assert_eq!("bar", result);

Registering Custom Functions

JMESPath Community comes with a host of useful builtin functions. However, it can be extended with third-party functions.

Example

mod custom_functions {

   	use jmespath_community as jmespath;

    use jmespath::function;

    use jmespath::errors::Error as RuntimeError;

    use jmespath::FunctionContext;
    use jmespath::Value;

    use jmespath::functions::ReturnValue;
    use jmespath::functions::Function;

    use jmespath::functions::DataType;
    use jmespath::functions::ParamTypes::*;
    use jmespath::functions::Parameter;
    use jmespath::functions::Parameter::*;

    function!(
        add,
        [
            left => Required(Of(DataType::Number)),
            right => Required(Of(DataType::Number))
        ],
        arguments,
        {
            // type checking has been performed by the runtime
            // safe to unwrap

            let i = arguments[0].as_f64().unwrap();
            let j = arguments[1].as_f64().unwrap();

            Value::from_f64(i + j)
        }
    );
}

Create a new instance of the JMESPath Runtime object and register your custom function:

Example

use jmespath_community as jmespath;
use jmespath::FunctionRegistrar;
use jmespath::{Runtime, Value};

let add = Box::new(custom_functions::add::new());
let mut runtime = Runtime::create_runtime();
runtime.register(add);

let expression = "foo";
let root = Value::Null;
let result = runtime.search(expression, &root).unwrap();

assert_eq!(None, result);

Re-exports

pub use errors::Error;

Modules

errors

Contains the types supporting error handling for this crate.

functions

Defines the builtin JMESPath function implementations and various helpers for authoring custom third-party functions.

Macros

function

Utility helper to implement a JMESPath Function trait.

map

Creates a Map from a list of key-value pairs This macro is taken from the maplit crate to minimize external dependencies.

Structs

AST

Represents an abstract syntax tree node.

ByFunctionHolder

Represents an expression type as runtime.

Number

Represents a JSON f64 number that can be safely ordered.

Runtime

Represents a processing runtime for JMESPath function evaluation.

Slice

Represents the parameters for a slice NodeType::Projection.

Enums

NodeType

Represents the contents of an abstract syntax tree node.

Value

Represents any valid value that is processed during evaluation of a JMESPath expression or used as an argument to a JMESPath Function.

Traits

FunctionContext

A type that represents a context accessible to JMESPath function implementations.

FunctionRegistrar

A type that represents a registry of JMESPath functions.

Functions

parse

Parses a JMESPath expression and returns an AST that represents the compiled abstract syntax tree.

search

Evaluates a JMESPath expression and returns a Value.

Type Aliases

JmesPathFunction

A type that represents a JMESPath function that can be stored into a thread-safe registry.

Map

A type that represents an abstraction over an associative array.