1JSON::Path(3) User Contributed Perl Documentation JSON::Path(3)
2
6 JSON::Path
7
9 version 1.0.3
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 David Escribano García https://github.com/DavidEGx
221
223 Copyright 2007 Stefan Goessner.
224 Copyright 2010-2013 Toby Inkster.
226 This module is tri-licensed. It is available under the X11 (a.k.a. MIT)
228 licence; you can also redistribute it and/or modify it under the same
229 terms as Perl itself.
230 a.k.a. "The MIT Licence"
232 Permission is hereby granted, free of charge, to any person obtaining a
233 copy of this software and associated documentation files (the
234 "Software"), to deal in the Software without restriction, including
235 without limitation the rights to use, copy, modify, merge, publish,
236 distribute, sublicense, and/or sell copies of the Software, and to
237 permit persons to whom the Software is furnished to do so, subject to
238 the following conditions:
239 The above copyright notice and this permission notice shall be included
241 in all copies or substantial portions of the Software.
242 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
244 OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
245 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
246 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
247 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
248 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
249 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
250
252 Kit Peters <popefelix@gmail.com>
253
255 This software is copyright (c) 2022 by Kit Peters.
256 This is free software; you can redistribute it and/or modify it under
258 the same terms as the Perl 5 programming language system itself.
259perl v5.38.0 2023-07-20 JSON::Path(3)