.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "JSON::Path::Evaluator 3pm"
.TH JSON::Path::Evaluator 3pm "2021-01-31" "perl v5.32.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
JSON::Path::Evaluator \- A module that recursively evaluates JSONPath expressions with native support for Javascript\-style filters
.SH "VERSION"
.IX Header "VERSION"
version 0.431
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\& use JSON::MaybeXS qw/decode_json/; # Or whatever JSON thing you like. I won\*(Aqt judge.
\& use JSON::Path::Evaluator qw/evaluate_jsonpath/;
\&
\& my $obj = decode_json(q(
\& { "store": {
\& "book": [
\& { "category": "reference",
\& "author": "Nigel Rees",
\& "title": "Sayings of the Century",
\& "price": 8.95
\& },
\& { "category": "fiction",
\& "author": "Evelyn Waugh",
\& "title": "Sword of Honour",
\& "price": 12.99
\& },
\& { "category": "fiction",
\& "author": "Herman Melville",
\& "title": "Moby Dick",
\& "isbn": "0\-553\-21311\-3",
\& "price": 8.99
\& },
\& { "category": "fiction",
\& "author": "J. R. R. Tolkien",
\& "title": "The Lord of the Rings",
\& "isbn": "0\-395\-19395\-8",
\& "price": 22.99
\& }
\& ],
\& "bicycle": {
\& "color": "red",
\& "price": 19.95
\& }
\& }
\& }
\& ));
\&
\& my @fiction = evaluate_jsonpath( $obj, q{$..book[?(@.category == "fiction")]});
\& # @fiction = (
\& # { category => "fiction",
\& # author => "Evelyn Waugh",
\& # title => "Sword of Honour",
\& # price => 12.99
\& # },
\& # { category => "fiction",
\& # author => "Herman Melville",
\& # title => "Moby Dick",
\& # isbn => "0\-553\-21311\-3",
\& # price => 8.99
\& # },
\& # { category => "fiction",
\& # author => "J. R. R. Tolkien",
\& # title => "The Lord of the Rings",
\& # isbn => "0\-395\-19395\-8",
\& # price => 22.99
\& # }
\& # );
.Ve
.SH "METHODS"
.IX Header "METHODS"
.SS "new"
.IX Subsection "new"
Constructor for the object-oriented interface to this module. Arguments may be specified in a hash or a hashref.
.PP
Args:
.IP "root" 4
.IX Item "root"
Required. JSONPath expressions will be evaluated with respect to this. Must be a hashref or an arrayref.
.IP "expression" 4
.IX Item "expression"
JSONPath expression to evaluate
.IP "want_ref" 4
.IX Item "want_ref"
Set this to true if you want a reference to the thing the JSONPath expression matches, rather than the value
of said thing. Useful if you want to use this to modify hashrefs / arrayrefs in place.
.IP "script_engine" 4
.IX Item "script_engine"
Defaults to \*(L"PseudoJS\*(R", which is my clever name for a subset of Javascript\-\fBlike\fR operators for Boolean expressions.
See \*(L"Filtering with PseudoJS\*(R". You may also specify \*(L"perl\*(R" here, in which case the filter will be treated as Perl code.
See \*(L"Filtering with Perl\*(R".
.SS "evaluate_jsonpath"
.IX Subsection "evaluate_jsonpath"
Evaluate a JSONPath expression on the given object. \s-1CLASS METHOD.\s0
.PP
Args:
.ie n .IP "$json_object" 4
.el .IP "\f(CW$json_object\fR" 4
.IX Item "$json_object"
\&\s-1JSON\s0 object for which the expression will be evaluated. If this is a scalar, it will be treated
as a \s-1JSON\s0 string and parsed into the appropriate Perl data structure first.
.ie n .IP "$expression" 4
.el .IP "\f(CW$expression\fR" 4
.IX Item "$expression"
JSONPath expression to evaluate on the object.
.ie n .IP "%args" 4
.el .IP "\f(CW%args\fR" 4
.IX Item "%args"
Misc. arguments to this method. Currently the only supported argument is 'want_ref' \- set this to
true in order to return a reference to the matched portion of the object, rather than the value
of that matched portion.
.SS "evaluate"
.IX Subsection "evaluate"
Evaluate a JSONPath expression on the object passed to the constructor. \s-1OBJECT METHOD.\s0
.PP
Args:
.ie n .IP "$expression" 4
.el .IP "\f(CW$expression\fR" 4
.IX Item "$expression"
JSONPath expression to evaluate on the object.
.ie n .IP "%args" 4
.el .IP "\f(CW%args\fR" 4
.IX Item "%args"
Misc. arguments to this method.
.Sp
Supported keys:
.RS 4
.IP "want_ref" 4
.IX Item "want_ref"
Set this to true in order to return a reference to the matched portion of the object, rather than
the value of the matched portion.
.IP "want_path" 4
.IX Item "want_path"
Set this to true in order to return the canonical path(s) to the elements matching the expression.
.RE
.RS 4
.RE
.SH "JSONPath"
.IX Header "JSONPath"
This code implements the JSONPath specification at JSONPath specification .
.PP
JSONPath is a tool, similar to XPath for \s-1XML,\s0 that allows one to construct queries to pick out parts of a \s-1JSON\s0 structure.
.SS "JSONPath Expressions"
.IX Subsection "JSONPath Expressions"
From the spec: \*(L"JSONPath expressions always refer to a \s-1JSON\s0 structure in the same way as XPath
expression are used in combination with an \s-1XML\s0 document. Since a \s-1JSON\s0 structure is usually anonymous
and doesn't necessarily have a \*(R"root member object\*(L" JSONPath assumes the abstract name $ assigned
to the outer level object.\*(R"
.PP
Note that in JSONPath square brackets operate on the object or array addressed by the previous path fragment. Indices always start by 0.
.SS "Operators"
.IX Subsection "Operators"
.IP "$" 4
the root object/element
.IP "@" 4
the current object/element
.IP ". or []" 4
.IX Item ". or []"
child operator
.IP ".." 4
recursive descent. JSONPath borrows this syntax from E4X.
.IP "'*' (literal asterisk)" 4
.IX Item "'*' (literal asterisk)"
wildcard. All objects/elements regardless their names.
.IP "[]" 4
subscript operator. XPath uses it to iterate over element collections and for predicates. In Javascript and \s-1JSON\s0 it is the native array operator.
.IP "[,]" 4
Union operator in XPath results in a combination of node sets. JSONPath allows alternate names or array indices as a set.
.IP "[start:end:step]" 4
.IX Item "[start:end:step]"
array slice operator borrowed from \s-1ES4.\s0
.IP "?()" 4
applies a filter (script) expression. See Filtering.
.IP "()" 4
script expression, using the underlying script engine. Handled the same as \*(L"?()\*(R".
.SS "Filtering"
.IX Subsection "Filtering"
Filters are the most powerful feature of JSONPath. They allow the caller to retrieve data
conditionally, similar to Perl's \f(CW\*(C`grep\*(C'\fR operator.
.PP
Filters are specified using the '?(' token, terminated by ')'. Anything in between these
two tokens is treated as a filter expression. Filter expressions must return a boolean value.
.PP
\fIFiltering with PseudoJS\fR
.IX Subsection "Filtering with PseudoJS"
.PP
By default, this module uses a limited subset of Javascript expressions to evaluate filters. Using
this script engine, specify the filter in the form \*(L"<\s-1LHS\s0> <\s-1RHS\s0>\*(R", or \*(L"<\s-1LHS\s0>\*(R". This latter
case will be evaluated as \*(L"<\s-1LHS\s0> is true\*(R".
.PP
<\s-1LHS\s0> must be a valid JSONPath expression. <\s-1RHS\s0> must be a scalar value; comparison of two JSONPath
expressions is not supported at this time.
.PP
Example:
.PP
Using the \s-1JSON\s0 in \s-1SYNOPSIS\s0 above and the JSONPath expression \f(CW\*(C`$..book[?(@.category == "fiction")]\*(C'\fR,
the filter expression \f(CW\*(C`@.category == "fiction"\*(C'\fR will match all values having a value of \*(L"fiction\*(R" for
the key \*(L"category\*(R".
.SS "Filtering with Perl"
.IX Subsection "Filtering with Perl"
When the script engine is set to \*(L"perl\*(R", filter
Using the \s-1JSON\s0 in \s-1SYNOPSIS\s0 above and the JSONPath expression \f(CW\*(C`$..book[?(@.category == "fiction")]\*(C'\fR,
.PP
This is understandably dangerous. Although steps have been taken (Perl expressions are evaluated using
Safe and a limited set of permitted opcodes) to reduce the risk, callers should be aware of the risk
when using filters.
.PP
When filtering in Perl, there are some differences between the JSONPath spec and this implementation.
.IP "*" 4
JSONPath uses the token '$' to refer to the root node. As this is not valid Perl, this should be
.Sp
replaced with '$root' in a filter expression.
.IP "*" 4
JSONPath uses the token '@' to refer to the current node. This is also not valid Perl. Use '$_'
.Sp
instead.
.SH "AUTHOR"
.IX Header "AUTHOR"
Kit Peters
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2021 by Kit Peters.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.