v0.6.0
0.6.0 (2 April 2023)
Function Extensions (#32)
This release introduces the implementation of Function Extensions in serde_json_path
.
This release ships with support for the standard built-in functions that are part of the base JSONPath specification:
length
count
match
search
value
These can now be used in your JSONPath query filter selectors, and are defined in the crate documentation
in the functions
module.
In addition, the #[function]
attribute macro was introduced to enable users of serde_json_path
to define
their own custom functions for use in their JSONPath queries.
The functions
module (added)
In addition to the documentation/definitions for built-in functions, the functions
module includes three new types:
ValueType
NodesType
LogicalType
These reflect the type system defined in the JSONPath spec. Each is available through the public API, to be used in custom
function definitions, along with the #[function]
attribute macro.
The #[function]
attribute macro (added)
A new attribute macro: #[function]
was introduced to allow users of serde_json_path
to define their
own custom functions for use in their JSONPath queries.
Along with the new types introduced by the functions
module, it can be used like so:
use serde_json_path::functions::{NodesType, ValueType};
/// A function that takes a node list, and optionally produces the first element as
/// a value, if there are any elements in the list.
#[serde_json_path::function]
fn first(nodes: NodesType) -> ValueType {
match nodes.first() {
Some(v) => ValueType::Node(v),
None => ValueType::Nothing,
}
}
Which will then allow you to use a first
function in your JSONPath queries:
$[? first(@.*) > 5 ]
Usage of first
in you JSONPath queries, like any of the built-in functions, will be validated at parse-time.
The #[function]
macro is gated behind the functions
feature, which is enabled by default.
Functions defined using the #[function]
macro will override any of the built-in functions that are part
of the standard, e.g., length
, count
, etc.
Changed the Error
type (breaking)
The Error
type was renamed to ParseError
and was updated to have more concise error messages. It was
refactored internally to better support future improvements to the parser. It is now a struct, vs. an enum,
with a private implementation, and two core APIs:
message()
: the parser error messageposition()
: indicate where the parser error was encountered in the JSONPath query string
This gives far more concise errors than the pre-existing usage of nom
's built-in VerboseError
type.
However, for now, this leads to somewhat of a trade-off, in that errors that are not specially handled
by the parser will present as just "parser error"
with a position. Over time, the objective is to
isolate cases where specific errors can be propagated up, and give better error messages.
Repository switched to a workspace
With this release, serde_json_path
is split into four separate crates:
serde_json_path
serde_json_path_macros
serde_json_path_macros_internal
serde_json_path_core
serde_json_path
is still the entry point for general consumption. It still contains some of the key
components of the API, e.g., JsonPath
, JsonPathExt
, and Error
, as well as the entire parser
module.
However, many of the core types used to represent the JSONPath model, as defined in the specification,
were moved into serde_json_path_core
.
This split was done to accommodate the new #[function]
attribute macro, which is defined within the
serde_json_path_macros
/macros_internal
crates, and discussed below.