.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "JSON::Pointer 3pm" .TH JSON::Pointer 3pm "2022-06-15" "perl v5.34.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" JSON::Pointer \- A Perl implementation of JSON Pointer (RFC6901) .SH "VERSION" .IX Header "VERSION" This document describes JSON::Pointer version 0.07. .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use JSON::Pointer; \& \& my $obj = { \& foo => 1, \& bar => [ { qux => "hello" }, 3 ], \& baz => { boo => [ 1, 3, 5, 7 ] } \& }; \& \& JSON::Pointer\->get($obj, "/foo"); ### $obj\->{foo} \& JSON::Pointer\->get($obj, "/bar/0"); ### $obj\->{bar}[0] \& JSON::Pointer\->get($obj, "/bar/0/qux"); ### $obj\->{bar}[0]{qux} \& JSON::Pointer\->get($obj, "/bar/1"); ### $obj\->{bar}[1] \& JSON::Pointer\->get($obj, "/baz/boo/2"); ### $obj\->{baz}{boo}[2] .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This library is implemented \s-1JSON\s0 Pointer () and some useful operator from \s-1JSON\s0 Patch (). .PP \&\s-1JSON\s0 Pointer is available to identify a specified value in \s-1JSON\s0 document, and it is simillar to XPath. Please read the both of specifications for details. .SH "METHODS" .IX Header "METHODS" .ie n .SS "get($document :HashRef/ArrayRef/Scalar, $pointer :Str, $strict :Int) :Scalar" .el .SS "get($document :HashRef/ArrayRef/Scalar, \f(CW$pointer\fP :Str, \f(CW$strict\fP :Int) :Scalar" .IX Subsection "get($document :HashRef/ArrayRef/Scalar, $pointer :Str, $strict :Int) :Scalar" .ie n .IP "$document :HashRef/ArrayRef/Scalar" 4 .el .IP "\f(CW$document\fR :HashRef/ArrayRef/Scalar" 4 .IX Item "$document :HashRef/ArrayRef/Scalar" Target perl data structure that is able to be presented by \s-1JSON\s0 format. .ie n .IP "$pointer :Str" 4 .el .IP "\f(CW$pointer\fR :Str" 4 .IX Item "$pointer :Str" \&\s-1JSON\s0 Pointer string to identify specified value in the document. .ie n .IP "$strict :Int" 4 .el .IP "\f(CW$strict\fR :Int" 4 .IX Item "$strict :Int" Strict mode. When this value equals true value, this method may throw exception on error. When this value equals false value, this method return undef value on error. .PP Get specified value identified by \fI\f(CI$pointer\fI\fR from \fI\f(CI$document\fI\fR. For example, .PP .Vb 2 \& use JSON::Pointer; \& print JSON::Pointer\->get({ foo => 1, bar => { "qux" => "hello" } }, "/bar/qux"); ### hello .Ve .ie n .SS "get_relative($document :HashRef/ArrayRef/Scalar, $current_pointer :Str, $relative_pointer :Str, $strict :Int) :Scalar" .el .SS "get_relative($document :HashRef/ArrayRef/Scalar, \f(CW$current_pointer\fP :Str, \f(CW$relative_pointer\fP :Str, \f(CW$strict\fP :Int) :Scalar" .IX Subsection "get_relative($document :HashRef/ArrayRef/Scalar, $current_pointer :Str, $relative_pointer :Str, $strict :Int) :Scalar" \&\fBThis method is highly \s-1EXPERIMENTAL\s0\fR. Because this method depends on draft spec. .ie n .IP "$document :HashRef/ArrayRef/Scalar" 4 .el .IP "\f(CW$document\fR :HashRef/ArrayRef/Scalar" 4 .IX Item "$document :HashRef/ArrayRef/Scalar" Target perl data structure that is able to be presented by \s-1JSON\s0 format. .ie n .IP "$current_pointer : Str" 4 .el .IP "\f(CW$current_pointer\fR : Str" 4 .IX Item "$current_pointer : Str" \&\s-1JSON\s0 Pointer string to identify specified current position in the document. .ie n .IP "$relative_pointer : Str" 4 .el .IP "\f(CW$relative_pointer\fR : Str" 4 .IX Item "$relative_pointer : Str" \&\s-1JSON\s0 Relative Pointer string to identify specified value from current position in the document .ie n .IP "$strict :Int" 4 .el .IP "\f(CW$strict\fR :Int" 4 .IX Item "$strict :Int" Strict mode. When this value equals true value, this method may throw exception on error. When this value equals false value, this method return undef value on error. .ie n .SS "contains($document :HashRef/ArrayRef/Scalar, $pointer :Str) :Int" .el .SS "contains($document :HashRef/ArrayRef/Scalar, \f(CW$pointer\fP :Str) :Int" .IX Subsection "contains($document :HashRef/ArrayRef/Scalar, $pointer :Str) :Int" .ie n .IP "$document :HashRef/ArrayRef/Scalar" 4 .el .IP "\f(CW$document\fR :HashRef/ArrayRef/Scalar" 4 .IX Item "$document :HashRef/ArrayRef/Scalar" Target perl data structure that is able to present by \s-1JSON\s0 format. .ie n .IP "$pointer :Str" 4 .el .IP "\f(CW$pointer\fR :Str" 4 .IX Item "$pointer :Str" \&\s-1JSON\s0 Pointer string to identify specified value in the document. .PP Return which the target location identified by \fI\f(CI$pointer\fI\fR exists or not in the \fI\f(CI$document\fI\fR. .PP .Vb 1 \& use JSON::Pointer; \& \& my $document = { foo => 1 }; \& if (JSON::Pointer\->contains($document, "/foo")) { \& print "/foo exists"; \& } .Ve .ie n .SS "add($document :HashRef/ArrayRef/Scalar, $pointer :Str, $value :HashRef/ArrayRef/Scalar) :HashRef/ArrayRef/Scalar" .el .SS "add($document :HashRef/ArrayRef/Scalar, \f(CW$pointer\fP :Str, \f(CW$value\fP :HashRef/ArrayRef/Scalar) :HashRef/ArrayRef/Scalar" .IX Subsection "add($document :HashRef/ArrayRef/Scalar, $pointer :Str, $value :HashRef/ArrayRef/Scalar) :HashRef/ArrayRef/Scalar" .ie n .IP "$document :HashRef/ArrayRef/Scalar" 4 .el .IP "\f(CW$document\fR :HashRef/ArrayRef/Scalar" 4 .IX Item "$document :HashRef/ArrayRef/Scalar" Target perl data structure that is able to be presented by \s-1JSON\s0 format. .ie n .IP "$pointer :Str" 4 .el .IP "\f(CW$pointer\fR :Str" 4 .IX Item "$pointer :Str" \&\s-1JSON\s0 Pointer string to identify specified value in the document. .ie n .IP "$value :HashRef/ArrayRef/Scalar" 4 .el .IP "\f(CW$value\fR :HashRef/ArrayRef/Scalar" 4 .IX Item "$value :HashRef/ArrayRef/Scalar" The perl data structure that is able to be presented by \s-1JSON\s0 format. .PP Add specified \fI\f(CI$value\fI\fR on target location identified by \fI\f(CI$pointer\fI\fR in the \fI\f(CI$document\fI\fR. For example, .PP .Vb 1 \& use JSON::Pointer; \& \& my $document = +{ foo => 1, }; \& my $value = +{ qux => "hello" }; \& \& my $patched_document = JSON::Pointer\->add($document, "/bar", $value); \& print $patched_document\->{bar}{qux}; ### hello .Ve .ie n .SS "remove($document, $pointer) :Array/Scalar" .el .SS "remove($document, \f(CW$pointer\fP) :Array/Scalar" .IX Subsection "remove($document, $pointer) :Array/Scalar" .ie n .IP "$document :HashRef/ArrayRef/Scalar" 4 .el .IP "\f(CW$document\fR :HashRef/ArrayRef/Scalar" 4 .IX Item "$document :HashRef/ArrayRef/Scalar" Target perl data structure that is able to be presented by \s-1JSON\s0 format. .ie n .IP "$pointer :Str" 4 .el .IP "\f(CW$pointer\fR :Str" 4 .IX Item "$pointer :Str" \&\s-1JSON\s0 Pointer string to identify specified value in the document. .PP Remove target location identified by \fI\f(CI$pointer\fI\fR in the \fI\f(CI$document\fI\fR. .PP .Vb 1 \& use JSON::Pointer; \& \& my $document = { foo => 1 }; \& my $patched_document = JSON::Pointer\->remove($document, "/foo"); \& unless (exists $patched_document\->{foo}) { \& print "removed /foo"; \& } .Ve .PP This method is contextial return value. When the return value of \fIwantarray\fR equals true, return \fI\f(CI$patched_document\fI\fR and \fI\f(CI$removed_value\fI\fR, or not return \fI\f(CI$patched_document\fI\fR only. .ie n .SS "replace($document :HashRef/ArrayRef/Scalar, $pointer :Str, $value :HashRef/ArrayRef/Scalar) :Array/HashRef/ArrayRef/Scalar" .el .SS "replace($document :HashRef/ArrayRef/Scalar, \f(CW$pointer\fP :Str, \f(CW$value\fP :HashRef/ArrayRef/Scalar) :Array/HashRef/ArrayRef/Scalar" .IX Subsection "replace($document :HashRef/ArrayRef/Scalar, $pointer :Str, $value :HashRef/ArrayRef/Scalar) :Array/HashRef/ArrayRef/Scalar" .ie n .IP "$document :HashRef/ArrayRef/Scalar" 4 .el .IP "\f(CW$document\fR :HashRef/ArrayRef/Scalar" 4 .IX Item "$document :HashRef/ArrayRef/Scalar" Target perl data structure that is able to be presented by \s-1JSON\s0 format. .ie n .IP "$pointer :Str" 4 .el .IP "\f(CW$pointer\fR :Str" 4 .IX Item "$pointer :Str" \&\s-1JSON\s0 Pointer string to identify specified value in the document. .ie n .IP "$value :HashRef/ArrayRef/Scalar" 4 .el .IP "\f(CW$value\fR :HashRef/ArrayRef/Scalar" 4 .IX Item "$value :HashRef/ArrayRef/Scalar" The perl data structure that is able to be presented by \s-1JSON\s0 format. .PP Replace the value of target location specified by \fI\f(CI$pointer\fI\fR to the \fI\f(CI$value\fI\fR in the \fI\f(CI$document\fI\fR. .PP .Vb 1 \& use JSON::Pointer; \& \& my $document = { foo => 1 }; \& my $patched_document = JSON::Pointer\->replace($document, "/foo", 2); \& print $patched_document\->{foo}; ## 2 .Ve .PP This method is contextial return value. When the return value of \fIwantarray\fR equals true, return \fI\f(CI$patched_document\fI\fR and \fI\f(CI$replaced_value\fI\fR, or not return \fI\f(CI$patched_document\fI\fR only. .ie n .SS "set($document :HashRef/ArrayRef/Scalar, $pointer :Str, $value :HashRef/ArrayRef/Scalar) :Array/HashRef/ArrayRef/Scalar" .el .SS "set($document :HashRef/ArrayRef/Scalar, \f(CW$pointer\fP :Str, \f(CW$value\fP :HashRef/ArrayRef/Scalar) :Array/HashRef/ArrayRef/Scalar" .IX Subsection "set($document :HashRef/ArrayRef/Scalar, $pointer :Str, $value :HashRef/ArrayRef/Scalar) :Array/HashRef/ArrayRef/Scalar" This method is alias of replace method. .ie n .SS "copy($document :HashRef/ArrayRef/Scalar, $from_pointer :Str, $to_pointer :Str) :HashRef/ArrayRef/Scalar" .el .SS "copy($document :HashRef/ArrayRef/Scalar, \f(CW$from_pointer\fP :Str, \f(CW$to_pointer\fP :Str) :HashRef/ArrayRef/Scalar" .IX Subsection "copy($document :HashRef/ArrayRef/Scalar, $from_pointer :Str, $to_pointer :Str) :HashRef/ArrayRef/Scalar" .ie n .IP "$document :HashRef/ArrayRef/Scalar" 4 .el .IP "\f(CW$document\fR :HashRef/ArrayRef/Scalar" 4 .IX Item "$document :HashRef/ArrayRef/Scalar" Target perl data structure that is able to be presented by \s-1JSON\s0 format. .ie n .IP "$from_pointer :Str" 4 .el .IP "\f(CW$from_pointer\fR :Str" 4 .IX Item "$from_pointer :Str" \&\s-1JSON\s0 Pointer string to identify specified value in the document. .ie n .IP "$to_pointer :Str" 4 .el .IP "\f(CW$to_pointer\fR :Str" 4 .IX Item "$to_pointer :Str" \&\s-1JSON\s0 Pointer string to identify specified value in the document. .PP Copy the value identified by \fI\f(CI$from_pointer\fI\fR to target location identified by \fI\f(CI$to_pointer\fI\fR. For example, .PP .Vb 1 \& use JSON::Pointer; \& \& my $document = +{ foo => [ { qux => "hello" } ], bar => [ 1 ] }; \& my $patched_document = JSON::Pointer\->copy($document, "/foo/0/qux", "/bar/\-"); \& print $patched_document\->{bar}[1]; ## hello .Ve .PP Note that \*(L"\-\*(R" notation means next of last element in the array. In this example, \*(L"\-\*(R" means 1. .ie n .SS "move($document :HashRef/ArrayRef/Scalar, $from_pointer :Str, $to_pointer :Str) :HashRef/ArrayRef/Scalar" .el .SS "move($document :HashRef/ArrayRef/Scalar, \f(CW$from_pointer\fP :Str, \f(CW$to_pointer\fP :Str) :HashRef/ArrayRef/Scalar" .IX Subsection "move($document :HashRef/ArrayRef/Scalar, $from_pointer :Str, $to_pointer :Str) :HashRef/ArrayRef/Scalar" .ie n .IP "$document :HashRef/ArrayRef/Scalar" 4 .el .IP "\f(CW$document\fR :HashRef/ArrayRef/Scalar" 4 .IX Item "$document :HashRef/ArrayRef/Scalar" Target perl data structure that is able to be presented by \s-1JSON\s0 format. .ie n .IP "$from_pointer :Str" 4 .el .IP "\f(CW$from_pointer\fR :Str" 4 .IX Item "$from_pointer :Str" \&\s-1JSON\s0 Pointer string to identify specified value in the document. .ie n .IP "$to_pointer :Str" 4 .el .IP "\f(CW$to_pointer\fR :Str" 4 .IX Item "$to_pointer :Str" \&\s-1JSON\s0 Pointer string to identify specified value in the document. .PP Move the value identified by \fI\f(CI$from_pointer\fI\fR to target location identified by \fI\f(CI$to_pointer\fI\fR. For example, .PP .Vb 2 \& use JSON; \& use JSON::Pointer; \& \& my $document = +{ foo => [ { qux => "hello" } ], bar => [ 1 ] }; \& my $patched_document = JSON::Pointer\->move($document, "/foo/0/qux", "/bar/\-"); \& print encode_json($patched_document); ## {"bar":[1,"hello"],"foo":[{}]} .Ve .ie n .SS "test($document :HashRef/ArrayRef/Scalar, $pointer :Str, $value :HashRef/ArrayRef/Scalar) :Int" .el .SS "test($document :HashRef/ArrayRef/Scalar, \f(CW$pointer\fP :Str, \f(CW$value\fP :HashRef/ArrayRef/Scalar) :Int" .IX Subsection "test($document :HashRef/ArrayRef/Scalar, $pointer :Str, $value :HashRef/ArrayRef/Scalar) :Int" .ie n .IP "$document :HashRef/ArrayRef/Scalar" 4 .el .IP "\f(CW$document\fR :HashRef/ArrayRef/Scalar" 4 .IX Item "$document :HashRef/ArrayRef/Scalar" Target perl data structure that is able to be presented by \s-1JSON\s0 format. .ie n .IP "$pointer :Str" 4 .el .IP "\f(CW$pointer\fR :Str" 4 .IX Item "$pointer :Str" \&\s-1JSON\s0 Pointer string to identify specified value in the document. .ie n .IP "$value :HashRef/ArrayRef/Scalar" 4 .el .IP "\f(CW$value\fR :HashRef/ArrayRef/Scalar" 4 .IX Item "$value :HashRef/ArrayRef/Scalar" The perl data structure that is able to be presented by \s-1JSON\s0 format. .PP Return which the value identified by \fI\f(CI$pointer\fI\fR equals \fI\f(CI$value\fI\fR or not in the \fI\f(CI$document\fI\fR. This method distinguish type of each values. .PP .Vb 1 \& use JSON::Pointer; \& \& my $document = { foo => 1 }; \& \& print JSON::Pointer\->test($document, "/foo", 1); ### 1 \& print JSON::Pointer\->test($document, "/foo", "1"); ### 0 .Ve .ie n .SS "traverse($document, $pointer, $opts) : JSON::Pointer::Context" .el .SS "traverse($document, \f(CW$pointer\fP, \f(CW$opts\fP) : JSON::Pointer::Context" .IX Subsection "traverse($document, $pointer, $opts) : JSON::Pointer::Context" This method is used as internal implementation only. .SH "DEPENDENCIES" .IX Header "DEPENDENCIES" Perl 5.8.1 or later. .SH "BUGS" .IX Header "BUGS" All complex software has bugs lurking in it, and this module is no exception. If you find a bug please either email me, or add the bug to cpan-RT. .SH "SEE ALSO" .IX Header "SEE ALSO" .IP "perl" 4 .IX Item "perl" .PD 0 .IP "Mojo::JSON::Pointer" 4 .IX Item "Mojo::JSON::Pointer" .PD Many codes in this module is inspired by the module. .IP "" 4 .IX Item "" .PD 0 .IP "" 4 .IX Item "" .IP "" 4 .IX Item "" .PD .SH "AUTHOR" .IX Header "AUTHOR" Toru Yamaguchi .SH "LICENSE AND COPYRIGHT" .IX Header "LICENSE AND COPYRIGHT" Copyright (c) 2013, Toru Yamaguchi. All rights reserved. .PP This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.