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 1.0.3
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       *   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       Regular expressions are supported using the "=~" operator, for example:
210       "$..book[?(@.category =~ /Fiction/i)]".  This is an extension of the
211       Goessner specification <http://goessner.net/articles/JsonPath/>
212       introduced by Jayway JsonPath <https://github.com/json-path/JsonPath>.
213       Other Jayway operators are not currently supported.
214
215   Filtering with Perl
216       When the script engine is set to "perl", filter Using the JSON in
217       SYNOPSIS above and the JSONPath expression "$..book[?(@.category ==
218       "fiction")]",
219
220       This is understandably dangerous. Although steps have been taken (Perl
221       expressions are evaluated using Safe and a limited set of permitted
222       opcodes) to reduce the risk, callers should be aware of the risk when
223       using filters.
224
225       When filtering in Perl, there are some differences between the JSONPath
226       spec and this implementation.
227
228       •   JSONPath uses the token '$' to refer to the root node. As this is
229           not valid Perl, this should be replaced with '$root' in a filter
230           expression.
231
232       •   JSONPath uses the token '@' to refer to the current node. This is
233           also not valid Perl. Use '$_' instead.
234

AUTHOR

236       Kit Peters <popefelix@gmail.com>
237
239       This software is copyright (c) 2022 by Kit Peters.
240
241       This is free software; you can redistribute it and/or modify it under
242       the same terms as the Perl 5 programming language system itself.
243

POD ERRORS

245       Hey! The above document had some coding errors, which are explained
246       below:
247
248       Around line 860:
249           Expected text after =item, not a bullet
250
251
252
253perl v5.36.0                      2023-01-20          JSON::Path::Evaluator(3)
Impressum