README
¶
jpath - jsonpath for YAML and JSON
CLI using JSONPath with YAML and JSON. The build is called jpath to make it more concise to type. Can be used to find and print subsets of a YAML or JSON file based on a JSONPath argument. JSON input is handled by first converting to YAML. JSONPath is applied to the YAML and matches printed to stdout. Ouput can be YAML or JSON.
The package used in this project is
yaml-jsonpath. yaml-jsonpath uses a jsonpath parser that is used to
access an underlying go-yaml v3 Node structure to extract sub-document matches. yaml-jsonpath also uses a fun library
go-yit, which adds interation to go-yaml nodes.
The only thing that could be added is the ability to reference a node's parent. This is not a common feature for
JSONPath implementations but I have seen it referenced using an ^ operator. Given that JSON is implemented and used
with languages from JavaScript to Python to C to Golang
JSONPath is a proposed IETF standard.
| JSONPath | Description |
|---|---|
$ |
the root object/element |
@ |
the current object/element |
. or [] |
child operator |
.. |
nested descendants. JSONPath borrows this syntax from E4X. |
* |
wildcard. All objects/elements regardless of their names. |
[] |
subscript operator. XPath uses it to iterate over element collections |
| and for predicates. In JSON and YAML it is the native array operator | |
[,] |
JSONPath allows alternate names or array indices as a set. |
[start:end:step] |
array slice operator borrowed from ES4. |
?() |
applies a filter (script) expression. |
| JSONPath comparison operator | Description |
|---|---|
== |
equality |
!= |
inequality |
> |
numeric greater than |
>= |
numeric greater than or equal to |
< |
numeric less than |
<= |
numeric less than or equal to |
=~ |
subpath matches regular expression |
| JSONPath | Result |
|---|---|
$.store.book[*].author |
the authors of all books in the store |
$..author |
all authors |
$.store.* |
all things in store, which are some books and a red bicycle. |
$.store..price |
the price of everything in the store. |
$..book[2] |
the third book |
$..book[(@.pages < 10)] |
book with pages value < 10 |
$..book[0,1] |
the first two books |
$..book[?(@.isbn)] |
filter all books with isbn number |
$..book[?(@.price<10)] |
filter all books cheapier than 10 |
$..book[(?(@.author=~/Woodward/)] |
book with author matching regex |
$..* or $ |
all members of JSON data item. |
$.property~ |
get name of property |
Usage of this tool with a JSONPath will result in zero or more matches. The matches are returned as an array. If there is an array of length 1 it is printed out on its own. If there are more than one match they are printed out as a YAML or JSON array. For example, here is an array printed out in JSON format
$ jpath '$..color' -file test/colours.json
[
"red",
"green",
"blue",
"cyan",
"magenta",
"yellow",
"black"
]
Here is the same query with YAML output
$ jpath '$..color' -file test/colours.json -yaml
- red
- green
- blue
- cyan
- magenta
- yellow
- black
This tool uses the posener completion library. You can set it up by
typing COMP_INSTALL=1 jpath.
I will add a suite of tests to ensure that the library used works and to illustrate as much as possible of jsonpath.
A YAML array can be turned into a list that can be read by bash as an array.
$ jpath -yaml '$..color' -file test/colours.json | \
awk 'BEGIN {IFS=/\s+/} {printf "%s ", $2}' | xargs
red green blue cyan magenta yellow black
Usage
jpath -h
jpath
-----
Commit: 7920948
Date: 2022-06-13T00:58:08Z
Tag: v0.1.15
OS: darwin
ARCH: arm64
Usage: jpath [--json] [--yaml] [--file FILE] [--type] [--summary] [--notes] [PATH]
Positional arguments:
PATH jsonpath to use
Options:
--json, -j output json
--yaml, -y output yaml
--file FILE, -f FILE file to use instead of stdin
--type, -t Show inferred type of input
--summary, -s Show summary
--notes, -n show jsonpath notes
--help, -h display this help and exit
--version display version and exit
Directories