Releases: hiltontj/serde_json_path
v0.6.7
v0.6.6
v0.6.5
0.6.5 (3 February 2024)
Added:NormalizedPathandPathElementtypes (#78)
TheNormalizedPathstruct represents the location of a node within a JSON object. Its representation is like so:
pubstructNormalizedPath<'a>(Vec<PathElement<'a>);
pubenumPathElement<'a>{
Name(&'astr),
Index(usize),
}Several methods were included to interact with aNormalizedPath,e.g.,first,last,get,iter,etc., but notably there is ato_json_pointermethod, which allows direct conversion to a JSON Pointer to be used with theserde_json::Value::pointerorserde_json::Value::pointer_mutmethods.
The newPathElementtype also comes equipped with several methods, and both it andNormalizedPathhave eagerly implemented traits from the standard library /serdeto help improve interoperability.
Added:LocatedNodeListandLocatedNodetypes (#78)
TheLocatedNodeListstruct was built to have a similar API surface to theNodeListstruct, but includes additional methods that give access to the location of each node produced by the original query. For example, it has thelocationsandnodesmethods to provide dedicated iterators over locations or nodes, respectively, but also provides theitermethod to iterate over the location/node pairs. Here is an example:
useserde_json::{json,Value};
useserde_json_path::JsonPath;
letvalue =json!({"foo":{"bar":1,"baz":2}});
letpath =JsonPath::parse("$.foo.*")?;
letquery = path.query_located(&value);
letnodes:Vec<&Value>= query.nodes().collect();
assert_eq!(nodes, vec![1,2]);
letlocs:Vec<String>= query
.locations()
.map(|loc| loc.to_string())
.collect();
assert_eq!(locs,["$['foo']['bar']","$['foo']['baz']"]);The location/node pairs are represented by theLocatedNodetype.
TheLocatedNodeListprovides one unique bit of functionality overNodeList:deduplication of the query results, via theLocatedNodeList::dedupandLocatedNodeList::dedup_in_placemethods.
Other Changes
v0.6.4
v0.6.3
0.6.3 (17 September 2023)
- documentation:Add line describing Descendant Operator (#53)
- documentation:Improve example in Filter Selector section of main docs (#54)
- documentation:Improve examples in Slice Slector section of main docs (#55)
- documentation:Other improvements to documentation (#56)
- fixed:Formulate the regex used by the
matchfunction to correctly handle regular expressions with leading or trailing|characters (#61)
v0.6.2
v0.6.1
v0.6.0
0.6.0 (2 April 2023)
Function Extensions (#32)
This release introduces the implementation ofFunction Extensionsinserde_json_path.
This release ships with support for the standard built-in functions that are part of the base JSONPath specification:
lengthcountmatchsearchvalue
These can now be used in your JSONPath query filter selectors, and are defined in the crate documentation
in thefunctionsmodule.
In addition, the#[function]attribute macro was introduced to enable users ofserde_json_pathto define
their own custom functions for use in their JSONPath queries.
Thefunctionsmodule (added)
In addition to the documentation/definitions for built-in functions, thefunctionsmodule includes three new types:
ValueTypeNodesTypeLogicalType
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 ofserde_json_pathto define their
own custom functions for use in their JSONPath queries.
Along with the new types introduced by thefunctionsmodule, it can be used like so:
useserde_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]
fnfirst(nodes:NodesType)->ValueType{
matchnodes.first(){
Some(v)=>ValueType::Node(v),
None=>ValueType::Nothing,
}
}Which will then allow you to use afirstfunction in your JSONPath queries:
$[? first(@.*) > 5 ]
Usage offirstin you JSONPath queries, like any of the built-in functions, will be validated at parse-time.
The#[function]macro is gated behind thefunctionsfeature, 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 theErrortype (breaking)
TheErrortype was renamed toParseErrorand 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 ofnom's built-inVerboseErrortype.
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_pathis split into four separate crates:
serde_json_pathserde_json_path_macrosserde_json_path_macros_internalserde_json_path_core
serde_json_pathis still the entry point for general consumption. It still contains some of the key
components of the API, e.g.,JsonPath,JsonPathExt,andError,as well as the entireparsermodule.
However, many of the core types used to represent the JSONPath model, as defined in the specification,
were moved intoserde_json_path_core.
This split was done to accommodate the new#[function]attribute macro, which is defined within the
serde_json_path_macros/macros_internalcrates, and discussed below.