1JSON::Path::Evaluator(3U)ser Contributed Perl DocumentatiJoSnON::Path::Evaluator(3)
2
3
4
6 JSON::Path::Evaluator - A module that recursively evaluates JSONPath
7 expressions with native support for Javascript-style filters
8
10 version 0.51
11
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
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
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 * wildcard. All objects/elements regardless their names.
166
167 [] subscript operator. XPath uses it to iterate over element
168 collections and for predicates. In Javascript and JSON it is the
169 native array operator.
170
171 [,] Union operator in XPath results in a combination of node sets.
172 JSONPath allows alternate names or array indices as a set.
173
174 [start:end:step]
175 array slice operator borrowed from ES4.
176
177 ?() applies a filter (script) expression. See Filtering.
178
179 () script expression, using the underlying script engine. Handled the
180 same as "?()".
181
182 Filtering
183 Filters are the most powerful feature of JSONPath. They allow the
184 caller to retrieve data conditionally, similar to Perl's "grep"
185 operator.
186
187 Filters are specified using the '?(' token, terminated by ')'. Anything
188 in between these two tokens is treated as a filter expression. Filter
189 expressions must return a boolean value.
190
191 Filtering with PseudoJS
192
193 By default, this module uses a limited subset of Javascript expressions
194 to evaluate filters. Using this script engine, specify the filter in
195 the form "<LHS> <operator> <RHS>", or "<LHS>". This latter case will be
196 evaluated as "<LHS> is true".
197
198 <LHS> must be a valid JSONPath expression. <RHS> must be a scalar
199 value; comparison of two JSONPath expressions is not supported at this
200 time.
201
202 Example:
203
204 Using the JSON in SYNOPSIS above and the JSONPath expression
205 "$..book[?(@.category == "fiction")]", the filter expression
206 "@.category == "fiction"" will match all values having a value of
207 "fiction" for the key "category".
208
209 Filtering with Perl
210 When the script engine is set to "perl", filter Using the JSON in
211 SYNOPSIS above and the JSONPath expression "$..book[?(@.category ==
212 "fiction")]",
213
214 This is understandably dangerous. Although steps have been taken (Perl
215 expressions are evaluated using Safe and a limited set of permitted
216 opcodes) to reduce the risk, callers should be aware of the risk when
217 using filters.
218
219 When filtering in Perl, there are some differences between the JSONPath
220 spec and this implementation.
221
222 • JSONPath uses the token '$' to refer to the root node. As this is
223 not valid Perl, this should be
224
225 replaced with '$root' in a filter expression.
226
227 • JSONPath uses the token '@' to refer to the current node. This is
228 also not valid Perl. Use '$_'
229
230 instead.
231
233 Kit Peters <popefelix@gmail.com>
234
236 This software is copyright (c) 2022 by Kit Peters.
237
238 This is free software; you can redistribute it and/or modify it under
239 the same terms as the Perl 5 programming language system itself.
240
242 Hey! The above document had some coding errors, which are explained
243 below:
244
245 Around line 843:
246 Expected text after =item, not a bullet
247
248
249
250perl v5.36.0 2022-07-22 JSON::Path::Evaluator(3)