1JSON::Path::Evaluator(3U)ser Contributed Perl DocumentatiJoSnON::Path::Evaluator(3)
2
3
4

NAME

6       JSON::Path::Evaluator - A module that recursively evaluates JSONPath
7       expressions with native support for Javascript-style filters
8

VERSION

10       version 0.431
11

SYNOPSIS

13           use JSON::MaybeXS qw/decode_json/; # Or whatever JSON thing you like. I won't judge.
14           use JSON::Path::Evaluator qw/evaluate_jsonpath/;
15
16           my $obj = decode_json(q(
17               { "store": {
18                   "book": [
19                     { "category": "reference",
20                       "author": "Nigel Rees",
21                       "title": "Sayings of the Century",
22                       "price": 8.95
23                     },
24                     { "category": "fiction",
25                       "author": "Evelyn Waugh",
26                       "title": "Sword of Honour",
27                       "price": 12.99
28                     },
29                     { "category": "fiction",
30                       "author": "Herman Melville",
31                       "title": "Moby Dick",
32                       "isbn": "0-553-21311-3",
33                       "price": 8.99
34                     },
35                     { "category": "fiction",
36                       "author": "J. R. R. Tolkien",
37                       "title": "The Lord of the Rings",
38                       "isbn": "0-395-19395-8",
39                       "price": 22.99
40                     }
41                   ],
42                   "bicycle": {
43                     "color": "red",
44                     "price": 19.95
45                   }
46                 }
47               }
48           ));
49
50           my @fiction = evaluate_jsonpath( $obj, q{$..book[?(@.category == "fiction")]});
51           # @fiction = (
52           #     {   category => "fiction",
53           #         author   => "Evelyn Waugh",
54           #         title    => "Sword of Honour",
55           #         price    => 12.99
56           #     },
57           #     {   category => "fiction",
58           #         author   => "Herman Melville",
59           #         title    => "Moby Dick",
60           #         isbn     => "0-553-21311-3",
61           #         price    => 8.99
62           #     },
63           #     {   category => "fiction",
64           #         author   => "J. R. R. Tolkien",
65           #         title    => "The Lord of the Rings",
66           #         isbn     => "0-395-19395-8",
67           #         price    => 22.99
68           #     }
69           # );
70

METHODS

72   new
73       Constructor for the object-oriented interface to this module. Arguments
74       may be specified in a hash or a hashref.
75
76       Args:
77
78       root
79           Required. JSONPath expressions will be evaluated with respect to
80           this. Must be a hashref or an arrayref.
81
82       expression
83           JSONPath expression to evaluate
84
85       want_ref
86           Set this to true if you want a reference to the thing the JSONPath
87           expression matches, rather than the value of said thing. Useful if
88           you want to use this to modify hashrefs / arrayrefs in place.
89
90       script_engine
91           Defaults to "PseudoJS", which is my clever name for a subset of
92           Javascript-like operators for Boolean expressions.  See "Filtering
93           with PseudoJS". You may also specify "perl" here, in which case the
94           filter will be treated as Perl code.  See "Filtering with Perl".
95
96   evaluate_jsonpath
97       Evaluate a JSONPath expression on the given object. CLASS METHOD.
98
99       Args:
100
101       $json_object
102           JSON object for which the expression will be evaluated. If this is
103           a scalar, it will be treated as a JSON string and parsed into the
104           appropriate Perl data structure first.
105
106       $expression
107           JSONPath expression to evaluate on the object.
108
109       %args
110           Misc. arguments to this method. Currently the only supported
111           argument is 'want_ref' - set this to true in order to return a
112           reference to the matched portion of the object, rather than the
113           value of that matched portion.
114
115   evaluate
116       Evaluate a JSONPath expression on the object passed to the constructor.
117       OBJECT METHOD.
118
119       Args:
120
121       $expression
122           JSONPath expression to evaluate on the object.
123
124       %args
125           Misc. arguments to this method.
126
127           Supported keys:
128
129           want_ref
130               Set this to true in order to return a reference to the matched
131               portion of the object, rather than the value of the matched
132               portion.
133
134           want_path
135               Set this to true in order to return the canonical path(s) to
136               the elements matching the expression.
137

JSONPath

139       This code implements the JSONPath specification at JSONPath
140       specification <http://goessner.net/articles/JsonPath/>.
141
142       JSONPath is a tool, similar to XPath for XML, that allows one to
143       construct queries to pick out parts of a JSON structure.
144
145   JSONPath Expressions
146       From the spec: "JSONPath expressions always refer to a JSON structure
147       in the same way as XPath expression are used in combination with an XML
148       document. Since a JSON structure is usually anonymous and doesn't
149       necessarily have a "root member object" JSONPath assumes the abstract
150       name $ assigned to the outer level object."
151
152       Note that in JSONPath square brackets operate on the object or array
153       addressed by the previous path fragment. Indices always start by 0.
154
155   Operators
156       $   the root object/element
157
158       @   the current object/element
159
160       . or []
161           child operator
162
163       ..  recursive descent. JSONPath borrows this syntax from E4X.
164
165       '*' (literal asterisk)
166           wildcard. All objects/elements regardless their names.
167
168       []  subscript operator. XPath uses it to iterate over element
169           collections and for predicates. In Javascript and JSON it is the
170           native array operator.
171
172       [,] Union operator in XPath results in a combination of node sets.
173           JSONPath allows alternate names or array indices as a set.
174
175       [start:end:step]
176           array slice operator borrowed from ES4.
177
178       ?() applies a filter (script) expression. See Filtering.
179
180       ()  script expression, using the underlying script engine. Handled the
181           same as "?()".
182
183   Filtering
184       Filters are the most powerful feature of JSONPath. They allow the
185       caller to retrieve data conditionally, similar to Perl's "grep"
186       operator.
187
188       Filters are specified using the '?(' token, terminated by ')'. Anything
189       in between these two tokens is treated as a filter expression. Filter
190       expressions must return a boolean value.
191
192       Filtering with PseudoJS
193
194       By default, this module uses a limited subset of Javascript expressions
195       to evaluate filters. Using this script engine, specify the filter in
196       the form "<LHS> <operator> <RHS>", or "<LHS>". This latter case will be
197       evaluated as "<LHS> is true".
198
199       <LHS> must be a valid JSONPath expression. <RHS> must be a scalar
200       value; comparison of two JSONPath expressions is not supported at this
201       time.
202
203       Example:
204
205       Using the JSON in SYNOPSIS above and the JSONPath expression
206       "$..book[?(@.category == "fiction")]", the filter expression
207       "@.category == "fiction"" will match all values having a value of
208       "fiction" for the key "category".
209
210   Filtering with Perl
211       When the script engine is set to "perl", filter Using the JSON in
212       SYNOPSIS above and the JSONPath expression "$..book[?(@.category ==
213       "fiction")]",
214
215       This is understandably dangerous. Although steps have been taken (Perl
216       expressions are evaluated using Safe and a limited set of permitted
217       opcodes) to reduce the risk, callers should be aware of the risk when
218       using filters.
219
220       When filtering in Perl, there are some differences between the JSONPath
221       spec and this implementation.
222
223       •   JSONPath uses the token '$' to refer to the root node. As this is
224           not valid Perl, this should be
225
226           replaced with '$root' in a filter expression.
227
228       •   JSONPath uses the token '@' to refer to the current node. This is
229           also not valid Perl. Use '$_'
230
231           instead.
232

AUTHOR

234       Kit Peters <popefelix@gmail.com>
235
237       This software is copyright (c) 2021 by Kit Peters.
238
239       This is free software; you can redistribute it and/or modify it under
240       the same terms as the Perl 5 programming language system itself.
241
242
243
244perl v5.32.1                      2021-01-31          JSON::Path::Evaluator(3)
Impressum