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 Definitions

• 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.