JSON::Pointer(3pm)

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

NAME

6       JSON::Pointer - A Perl implementation of JSON Pointer (RFC6901)
7

VERSION

9       This document describes JSON::Pointer version 0.07.
10

SYNOPSIS

12         use JSON::Pointer;
13
14         my $obj = {
15           foo => 1,
16           bar => [ { qux => "hello" }, 3 ],
17           baz => { boo => [ 1, 3, 5, 7 ] }
18         };
19
20         JSON::Pointer->get($obj, "/foo");       ### $obj->{foo}
21         JSON::Pointer->get($obj, "/bar/0");     ### $obj->{bar}[0]
22         JSON::Pointer->get($obj, "/bar/0/qux"); ### $obj->{bar}[0]{qux}
23         JSON::Pointer->get($obj, "/bar/1");     ### $obj->{bar}[1]
24         JSON::Pointer->get($obj, "/baz/boo/2"); ### $obj->{baz}{boo}[2]
25

DESCRIPTION

27       This library is implemented JSON Pointer
28       (<http://tools.ietf.org/html/rfc6901>) and some useful operator from
29       JSON Patch (<http://tools.ietf.org/html/rfc6902>).
30
31       JSON Pointer is available to identify a specified value in JSON
32       document, and it is simillar to XPath.  Please read the both of
33       specifications for details.
34

METHODS

36   get($document :HashRef/ArrayRef/Scalar, $pointer :Str, $strict :Int)
37       :Scalar
38       $document :HashRef/ArrayRef/Scalar
39           Target perl data structure that is able to be presented by JSON
40           format.
41
42       $pointer :Str
43           JSON Pointer string to identify specified value in the document.
44
45       $strict :Int
46           Strict mode. When this value equals true value, this method may
47           throw exception on error.  When this value equals false value, this
48           method return undef value on error.
49
50       Get specified value identified by $pointer from $document.  For
51       example,
52
53         use JSON::Pointer;
54         print JSON::Pointer->get({ foo => 1, bar => { "qux" => "hello" } }, "/bar/qux"); ### hello
55
56   get_relative($document :HashRef/ArrayRef/Scalar, $current_pointer :Str,
57       $relative_pointer :Str, $strict :Int) :Scalar
58       This method is highly EXPERIMENTAL. Because this method depends on
59       <http://tools.ietf.org/html/draft-luff-relative-json-pointer-00> draft
60       spec.
61
62       $document :HashRef/ArrayRef/Scalar
63           Target perl data structure that is able to be presented by JSON
64           format.
65
66       $current_pointer : Str
67           JSON Pointer string to identify specified current position in the
68           document.
69
70       $relative_pointer : Str
71           JSON Relative Pointer string to identify specified value from
72           current position in the document
73
74       $strict :Int
75           Strict mode. When this value equals true value, this method may
76           throw exception on error.  When this value equals false value, this
77           method return undef value on error.
78
79   contains($document :HashRef/ArrayRef/Scalar, $pointer :Str) :Int
80       $document :HashRef/ArrayRef/Scalar
81           Target perl data structure that is able to present by JSON format.
82
83       $pointer :Str
84           JSON Pointer string to identify specified value in the document.
85
86       Return which the target location identified by $pointer exists or not
87       in the $document.
88
89         use JSON::Pointer;
90
91         my $document = { foo => 1 };
92         if (JSON::Pointer->contains($document, "/foo")) {
93           print "/foo exists";
94         }
95
96   add($document :HashRef/ArrayRef/Scalar, $pointer :Str, $value
97       :HashRef/ArrayRef/Scalar) :HashRef/ArrayRef/Scalar
98       $document :HashRef/ArrayRef/Scalar
99           Target perl data structure that is able to be presented by JSON
100           format.
101
102       $pointer :Str
103           JSON Pointer string to identify specified value in the document.
104
105       $value :HashRef/ArrayRef/Scalar
106           The perl data structure that is able to be presented by JSON
107           format.
108
109       Add specified $value on target location identified by $pointer in the
110       $document.  For example,
111
112         use JSON::Pointer;
113
114         my $document = +{ foo => 1, };
115         my $value = +{ qux => "hello" };
116
117         my $patched_document = JSON::Pointer->add($document, "/bar", $value);
118         print $patched_document->{bar}{qux}; ### hello
119
120   remove($document, $pointer) :Array/Scalar
121       $document :HashRef/ArrayRef/Scalar
122           Target perl data structure that is able to be presented by JSON
123           format.
124
125       $pointer :Str
126           JSON Pointer string to identify specified value in the document.
127
128       Remove target location identified by $pointer in the $document.
129
130         use JSON::Pointer;
131
132         my $document = { foo => 1 };
133         my $patched_document = JSON::Pointer->remove($document, "/foo");
134         unless (exists $patched_document->{foo}) {
135           print "removed /foo";
136         }
137
138       This method is contextial return value. When the return value of
139       wantarray equals true, return $patched_document and $removed_value, or
140       not return $patched_document only.
141
142   replace($document :HashRef/ArrayRef/Scalar, $pointer :Str, $value
143       :HashRef/ArrayRef/Scalar) :Array/HashRef/ArrayRef/Scalar
144       $document :HashRef/ArrayRef/Scalar
145           Target perl data structure that is able to be presented by JSON
146           format.
147
148       $pointer :Str
149           JSON Pointer string to identify specified value in the document.
150
151       $value :HashRef/ArrayRef/Scalar
152           The perl data structure that is able to be presented by JSON
153           format.
154
155       Replace the value of target location specified by $pointer to the
156       $value in the $document.
157
158         use JSON::Pointer;
159
160         my $document = { foo => 1 };
161         my $patched_document = JSON::Pointer->replace($document, "/foo", 2);
162         print $patched_document->{foo}; ## 2
163
164       This method is contextial return value. When the return value of
165       wantarray equals true, return $patched_document and $replaced_value, or
166       not return $patched_document only.
167
168   set($document :HashRef/ArrayRef/Scalar, $pointer :Str, $value
169       :HashRef/ArrayRef/Scalar) :Array/HashRef/ArrayRef/Scalar
170       This method is alias of replace method.
171
172   copy($document :HashRef/ArrayRef/Scalar, $from_pointer :Str, $to_pointer
173       :Str) :HashRef/ArrayRef/Scalar
174       $document :HashRef/ArrayRef/Scalar
175           Target perl data structure that is able to be presented by JSON
176           format.
177
178       $from_pointer :Str
179           JSON Pointer string to identify specified value in the document.
180
181       $to_pointer :Str
182           JSON Pointer string to identify specified value in the document.
183
184       Copy the value identified by $from_pointer to target location
185       identified by $to_pointer.  For example,
186
187         use JSON::Pointer;
188
189         my $document = +{ foo => [ { qux => "hello" } ], bar => [ 1 ] };
190         my $patched_document = JSON::Pointer->copy($document, "/foo/0/qux", "/bar/-");
191         print $patched_document->{bar}[1]; ## hello
192
193       Note that "-" notation means next of last element in the array.  In
194       this example, "-" means 1.
195
196   move($document :HashRef/ArrayRef/Scalar, $from_pointer :Str, $to_pointer
197       :Str) :HashRef/ArrayRef/Scalar
198       $document :HashRef/ArrayRef/Scalar
199           Target perl data structure that is able to be presented by JSON
200           format.
201
202       $from_pointer :Str
203           JSON Pointer string to identify specified value in the document.
204
205       $to_pointer :Str
206           JSON Pointer string to identify specified value in the document.
207
208       Move the value identified by $from_pointer to target location
209       identified by $to_pointer.  For example,
210
211         use JSON;
212         use JSON::Pointer;
213
214         my $document = +{ foo => [ { qux => "hello" } ], bar => [ 1 ] };
215         my $patched_document = JSON::Pointer->move($document, "/foo/0/qux", "/bar/-");
216         print encode_json($patched_document); ## {"bar":[1,"hello"],"foo":[{}]}
217
218   test($document :HashRef/ArrayRef/Scalar, $pointer :Str, $value
219       :HashRef/ArrayRef/Scalar) :Int
220       $document :HashRef/ArrayRef/Scalar
221           Target perl data structure that is able to be presented by JSON
222           format.
223
224       $pointer :Str
225           JSON Pointer string to identify specified value in the document.
226
227       $value :HashRef/ArrayRef/Scalar
228           The perl data structure that is able to be presented by JSON
229           format.
230
231       Return which the value identified by $pointer equals $value or not in
232       the $document.  This method distinguish type of each values.
233
234         use JSON::Pointer;
235
236         my $document = { foo => 1 };
237
238         print JSON::Pointer->test($document, "/foo", 1); ### 1
239         print JSON::Pointer->test($document, "/foo", "1"); ### 0
240
241   traverse($document, $pointer, $opts) : JSON::Pointer::Context
242       This method is used as internal implementation only.
243

DEPENDENCIES

245       Perl 5.8.1 or later.
246

BUGS

248       All complex software has bugs lurking in it, and this module is no
249       exception. If you find a bug please either email me, or add the bug to
250       cpan-RT.
251

AUTHOR

262       Toru Yamaguchi <zigorou at cpan.org>
263

LICENSE AND COPYRIGHT

265       Copyright (c) 2013, Toru Yamaguchi. All rights reserved.
266
267       This library is free software; you can redistribute it and/or modify it
268       under the same terms as Perl itself.
269
270
271
272perl v5.30.0                      2019-07-26                  JSON::Pointer(3)