1JSON::Path(3)         User Contributed Perl Documentation        JSON::Path(3)
2
3
4

NAME

6       JSON::Path
7

VERSION

9       version 0.51
10

SYNOPSIS

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
46        use JSON::Path 'jpath_map';
47
48        # All books in the store
49        my $jpath   = JSON::Path->new('$.store.book[*]');
50        my @books   = $jpath->values($data);
51
52        # The author of the last (by order) book
53        my $jpath   = JSON::Path->new('$..book[-1:].author');
54        my $tolkien = $jpath->value($data);
55
56        # Convert all authors to uppercase
57        jpath_map { uc $_ } $data, '$.store.book[*].author';
58

DESCRIPTION

60       This module implements JSONPath, an XPath-like language for searching
61       JSON-like structures.
62
63       JSONPath is described at <http://goessner.net/articles/JsonPath/>.
64
65   Constructor
66       "JSON::Path->new($string)"
67           Given a JSONPath expression $string, returns a JSON::Path object.
68
69   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
76           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
80       "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
84             my $person = { name => "Robert" };
85             my $path = JSON::Path->new('$.name');
86             $path->value($person) = "Bob";
87
88           TAKE NOTE! This will create keys in $object. E.G.:
89
90               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
94       "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
99       "get($object)"
100           In list context, identical to "values", but in scalar context
101           returns the first result.
102
103       "set($object, $value, $limit)"
104           Alters $object, setting the paths to $value. If set, then $limit
105           limits the number of changes made.
106
107           TAKE NOTE! This will create keys in $object. E.G.:
108
109               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
113           Returns the number of changes made.
114
115       "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
122       "to_string"
123           Returns the original JSONPath expression as a string.
124
125           This method is usually not needed, as the JSON::Path should
126           automatically stringify itself as appropriate. i.e. the following
127           works:
128
129            my $jpath = JSON::Path->new('$.store.book[*].author');
130            print "I'm looking for: " . $jpath . "\n";
131
132   Functions
133       The following functions are available for export, but are not exported
134       by default:
135
136       "jpath($object, $path_string)"
137           Shortcut for "JSON::Path->new($path_string)->values($object)".
138
139       "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
143       "jpath_map { CODE } $object, $path_string"
144           Shortcut for "JSON::Path->new($path_string)->map($object, $code)".
145

NAME

147       JSON::Path - search nested hashref/arrayref structures using JSONPath
148

PERL SPECIFICS

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
154   JSONPath Embedded Perl Expressions
155       JSONPath expressions may contain subexpressions that are evaluated
156       using the native host language. e.g.
157
158        $..book[?($_->{author} =~ /tolkien/i)]
159
160       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
165        $JSON::Path::Safe = 0;
166
167       There are some differences between the JSONPath spec and this
168       implementation.
169
170       •   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
173       •   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
176   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
181         Scalar::Util::blessed($object)
182         && $object->can('typeof')
183         && $object->typeof =~ /^(ARRAY|HASH)$/
184
185       which are treated as an unblessed arrayref or hashref appropriately.
186

BUGS

188       Please report any bugs to <http://rt.cpan.org/>.
189

SEE ALSO

191       Specification: <http://goessner.net/articles/JsonPath/>.
192
193       Implementations in PHP, Javascript and C#:
194       <http://code.google.com/p/jsonpath/>.
195
196       Related modules: JSON, JSON::JOM, JSON::T, JSON::GRDDL, JSON::Hyper,
197       JSON::Schema.
198
199       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

AUTHOR

206       Toby Inkster <tobyink@cpan.org>.
207

MAINTAINER

209       Kit Peters <popefelix@cpan.org>
210

CONTRIBUTORS

212       Szymon Nieznański <s.nez@member.fsf.org>
213
214       Kit Peters <popefelix@cpan.org>
215
216       Heiko Jansen <hjansen@cpan.org>.
217
218       Mitsuhiro Nakamura <m.nacamura@gmail.com>
219
221       Copyright 2007 Stefan Goessner.
222
223       Copyright 2010-2013 Toby Inkster.
224
225       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
229   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
238       The above copyright notice and this permission notice shall be included
239       in all copies or substantial portions of the Software.
240
241       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

AUTHOR

250       Kit Peters <popefelix@gmail.com>
251
253       This software is copyright (c) 2022 by Kit Peters.
254
255       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.
257
258
259
260perl v5.36.0                      2022-07-22                     JSON::Path(3)
Impressum