1JSON::Path(3) User Contributed Perl Documentation JSON::Path(3)
2
6 JSON::Path
7
9 version 0.431
10
12 my $data = {
13 "store" => {
14 "book" => [
15 { "category" => "reference",
16 "author" => "Nigel Rees",
17 "title" => "Sayings of the Century",
18 "price" => 8.95,
19 },
20 { "category" => "fiction",
21 "author" => "Evelyn Waugh",
22 "title" => "Sword of Honour",
23 "price" => 12.99,
24 },
25 { "category" => "fiction",
26 "author" => "Herman Melville",
27 "title" => "Moby Dick",
28 "isbn" => "0-553-21311-3",
29 "price" => 8.99,
30 },
31 { "category" => "fiction",
32 "author" => "J. R. R. Tolkien",
33 "title" => "The Lord of the Rings",
34 "isbn" => "0-395-19395-8",
35 "price" => 22.99,
36 },
37 ],
38 "bicycle" => [
39 { "color" => "red",
40 "price" => 19.95,
41 },
42 ],
43 },
44 };
45 use JSON::Path 'jpath_map';
47 # All books in the store
49 my $jpath = JSON::Path->new('$.store.book[*]');
50 my @books = $jpath->values($data);
51 # The author of the last (by order) book
53 my $jpath = JSON::Path->new('$..book[-1:].author');
54 my $tolkien = $jpath->value($data);
55 # Convert all authors to uppercase
57 jpath_map { uc $_ } $data, '$.store.book[*].author';
58
60 This module implements JSONPath, an XPath-like language for searching
61 JSON-like structures.
62 JSONPath is described at <http://goessner.net/articles/JsonPath/>.
64 Constructor
66 "JSON::Path->new($string)"
67 Given a JSONPath expression $string, returns a JSON::Path object.
68 Methods
70 "values($object)"
71 Evaluates the JSONPath expression against an object. The object
72 $object can be either a nested Perl hashref/arrayref structure, or
73 a JSON string capable of being decoded by
74 JSON::MaybeXS::decode_json.
75 Returns a list of structures from within $object which match
77 against the JSONPath expression. In scalar context, returns the
78 number of matches.
79 "value($object)"
81 Like "values", but returns just the first value. This method is an
82 lvalue sub, which means you can assign to it:
83 my $person = { name => "Robert" };
85 my $path = JSON::Path->new('$.name');
86 $path->value($person) = "Bob";
87 TAKE NOTE! This will create keys in $object. E.G.:
89 my $obj = { foo => 'bar' };
91 my $path = JSON::Path->new('$.baz');
92 $path->value($obj) = 'bak'; # $obj->{baz} is created and set to 'bak';
93 "paths($object)"
95 As per "values" but instead of returning structures which match the
96 expression, returns canonical JSONPaths that point towards those
97 structures.
98 "get($object)"
100 In list context, identical to "values", but in scalar context
101 returns the first result.
102 "set($object, $value, $limit)"
104 Alters $object, setting the paths to $value. If set, then $limit
105 limits the number of changes made.
106 TAKE NOTE! This will create keys in $object. E.G.:
108 my $obj = { foo => 'bar' };
110 my $path = JSON::Path->new('$.baz');
111 $path->set($obj, 'bak'); # $obj->{baz} is created and set to 'bak'
112 Returns the number of changes made.
114 "map($object, $coderef)"
116 Conceptually similar to Perl's "map" keyword. Executes the coderef
117 (in scalar context!) for each match of the path within the object,
118 and sets a new value from the coderef's return value. Within the
119 coderef, $_ may be used to access the old value, and $. may be
120 used to access the curent canonical JSONPath.
121 "to_string"
123 Returns the original JSONPath expression as a string.
124 This method is usually not needed, as the JSON::Path should
126 automatically stringify itself as appropriate. i.e. the following
127 works:
128 my $jpath = JSON::Path->new('$.store.book[*].author');
130 print "I'm looking for: " . $jpath . "\n";
131 Functions
133 The following functions are available for export, but are not exported
134 by default:
135 "jpath($object, $path_string)"
137 Shortcut for "JSON::Path->new($path_string)->values($object)".
138 "jpath1($object, $path_string)"
140 Shortcut for "JSON::Path->new($path_string)->value($object)". Like
141 "value", it can be used as an lvalue.
142 "jpath_map { CODE } $object, $path_string"
144 Shortcut for "JSON::Path->new($path_string)->map($object, $code)".
145
147 JSON::Path - search nested hashref/arrayref structures using JSONPath
148
150 JSONPath is intended as a cross-programming-language method of
151 searching nested object structures. There are however, some things you
152 need to think about when using JSONPath in Perl...
153 JSONPath Embedded Perl Expressions
155 JSONPath expressions may contain subexpressions that are evaluated
156 using the native host language. e.g.
157 $..book[?($_->{author} =~ /tolkien/i)]
159 The stuff between "?(" and ")" is a Perl expression that must return a
161 boolean, used to filter results. As arbitrary Perl may be used, this is
162 clearly quite dangerous unless used in a controlled environment. Thus,
163 it's disabled by default. To enable, set:
164 $JSON::Path::Safe = 0;
166 There are some differences between the JSONPath spec and this
168 implementation.
169 • JSONPath uses a variable '$' to refer to the root node. This is
171 not a legal variable name in Perl, so '$root' is used instead.
172 • JSONPath uses a variable '@' to refer to the current node. This is
174 not a legal variable name in Perl, so '$_' is used instead.
175 Blessed Objects
177 Blessed objects are generally treated as atomic values; JSON::Path will
178 not follow paths inside them. The exception to this rule are blessed
179 objects where:
180 Scalar::Util::blessed($object)
182 && $object->can('typeof')
183 && $object->typeof =~ /^(ARRAY|HASH)$/
184 which are treated as an unblessed arrayref or hashref appropriately.
186
188 Please report any bugs to <http://rt.cpan.org/>.
189
191 Specification: <http://goessner.net/articles/JsonPath/>.
192 Implementations in PHP, Javascript and C#:
194 <http://code.google.com/p/jsonpath/>.
195 Related modules: JSON, JSON::JOM, JSON::T, JSON::GRDDL, JSON::Hyper,
197 JSON::Schema.
198 Similar functionality: Data::Path, Data::DPath, Data::SPath,
200 Hash::Path, Path::Resolver::Resolver::Hash, Data::Nested,
201 Data::Hierarchy... yes, the idea's not especially new. What's different
202 is that JSON::Path uses a vaguely standardised syntax with
203 implementations in at least three other programming languages.
204
206 Toby Inkster <tobyink@cpan.org>.
207
209 Kit Peters <popefelix@cpan.org>
210
212 Szymon Nieznański <s.nez@member.fsf.org>
213 Kit Peters <popefelix@cpan.org>
215 Heiko Jansen <hjansen@cpan.org>.
217 Mitsuhiro Nakamura <m.nacamura@gmail.com>
219
221 Copyright 2007 Stefan Goessner.
222 Copyright 2010-2013 Toby Inkster.
224 This module is tri-licensed. It is available under the X11 (a.k.a. MIT)
226 licence; you can also redistribute it and/or modify it under the same
227 terms as Perl itself.
228 a.k.a. "The MIT Licence"
230 Permission is hereby granted, free of charge, to any person obtaining a
231 copy of this software and associated documentation files (the
232 "Software"), to deal in the Software without restriction, including
233 without limitation the rights to use, copy, modify, merge, publish,
234 distribute, sublicense, and/or sell copies of the Software, and to
235 permit persons to whom the Software is furnished to do so, subject to
236 the following conditions:
237 The above copyright notice and this permission notice shall be included
239 in all copies or substantial portions of the Software.
240 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
242 OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
243 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
244 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
245 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
246 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
247 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
248
250 Kit Peters <popefelix@gmail.com>
251
253 This software is copyright (c) 2021 by Kit Peters.
254 This is free software; you can redistribute it and/or modify it under
256 the same terms as the Perl 5 programming language system itself.
257perl v5.34.0 2021-07-22 JSON::Path(3)