JSON::Pointer(3pm)

📦
version 0.07 · 4 versions
, in debian bookworm, debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking

💖 JSON::Pointer 💖

okay bestie, so this is JSON::Pointer — a whole Perl implementation of JSON Pointer, and yes it's the RFC6901 one, it's giving standards-compliant and we LOVE that for us. From the JSON::Pointer(3pm) manual, User Contributed Perl Documentation, no less. 🎀

✨ VERSION ✨

This doc is describing JSON::Pointer version 0.07. periodt.

🌸 SYNOPSIS 🌸

okay here's the whole vibe in one go, look at her:

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]

like. she just reaches in and grabs the thing. iconic. 💅

🦋 DESCRIPTION 🦋

This library implements JSON Pointer (<http://tools.ietf.org/html/rfc6901>) and also some genuinely useful operators from JSON Patch (<http://tools.ietf.org/html/rfc6902>). two specs, one module, main character energy fr fr.

JSON Pointer is how you point at one specific value inside a JSON document, and lowkey it's a lot like XPath. if you want the full tea, go read both of the specifications for details. no cap.

👑 METHODS 👑

get($document :HashRef/ArrayRef/Scalar, $pointer :Str, $strict :Int) :Scalar

  • $document :HashRef/ArrayRef/Scalar — the target perl data structure, has to be something that could be shown in JSON format.
  • $pointer :Str — the JSON Pointer string that identifies the value you want in the document.
  • $strict :Int — strict mode! when this is a true value, the method might throw an exception on error 😭. when it's a false value, the method just returns undef on error instead.

Gets the value that $pointer points at, out of $document. for example:

use JSON::Pointer;
print JSON::Pointer->get({ foo => 1, bar => { "qux" => "hello" } }, "/bar/qux"); ### hello

get_relative($document :HashRef/ArrayRef/Scalar, $current_pointer :Str, $relative_pointer :Str, $strict :Int) :Scalar

🚨 this method is highly EXPERIMENTAL 🚨 because it depends on the <http://tools.ietf.org/html/draft-luff-relative-json-pointer-00> draft spec. draft spec!! so like, be aware, bestie.
  • $document :HashRef/ArrayRef/Scalar — the target perl data structure, has to be presentable in JSON format.
  • $current_pointer : Str — a JSON Pointer string identifying your current position in the document.
  • $relative_pointer : Str — a JSON Relative Pointer string that identifies the value relative to that current position in the document.
  • $strict :Int — strict mode. true value means it may throw an exception on error. false value means it returns undef on error.

contains($document :HashRef/ArrayRef/Scalar, $pointer :Str) :Int

  • $document :HashRef/ArrayRef/Scalar — the target perl data structure, presentable by JSON format.
  • $pointer :Str — the JSON Pointer string identifying the value in the document.

Returns whether the target location identified by $pointer exists in $document or not. a lil yes/no moment ✨

use JSON::Pointer;

my $document = { foo => 1 };
if (JSON::Pointer->contains($document, "/foo")) {
  print "/foo exists";
}

add($document :HashRef/ArrayRef/Scalar, $pointer :Str, $value :HashRef/ArrayRef/Scalar) :HashRef/ArrayRef/Scalar

  • $document :HashRef/ArrayRef/Scalar — target perl data structure, presentable by JSON format.
  • $pointer :Str — JSON Pointer string identifying the value in the document.
  • $value :HashRef/ArrayRef/Scalar — the perl data structure that's presentable by JSON format.

Adds $value at the target location identified by $pointer inside $document. for example:

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

remove($document, $pointer) :Array/Scalar

  • $document :HashRef/ArrayRef/Scalar — target perl data structure, presentable by JSON format.
  • $pointer :Str — JSON Pointer string identifying the value in the document.

Removes the target location identified by $pointer from $document. bye bye 🫶

use JSON::Pointer;

my $document = { foo => 1 };
my $patched_document = JSON::Pointer->remove($document, "/foo");
unless (exists $patched_document->{foo}) {
  print "removed /foo";
}

This method's return value is contextual. when the return value of wantarray is true, it returns $patched_document and $removed_value. otherwise it returns $patched_document only. she's versatile like that 💅

replace($document :HashRef/ArrayRef/Scalar, $pointer :Str, $value :HashRef/ArrayRef/Scalar) :Array/HashRef/ArrayRef/Scalar

  • $document :HashRef/ArrayRef/Scalar — target perl data structure, presentable by JSON format.
  • $pointer :Str — JSON Pointer string identifying the value in the document.
  • $value :HashRef/ArrayRef/Scalar — the perl data structure presentable by JSON format.

Replaces the value at the target location specified by $pointer with $value in $document.

use JSON::Pointer;

my $document = { foo => 1 };
my $patched_document = JSON::Pointer->replace($document, "/foo", 2);
print $patched_document->{foo}; ## 2

This one's return value is contextual too. when wantarray returns true, you get $patched_document and $replaced_value; otherwise just $patched_document.

set($document :HashRef/ArrayRef/Scalar, $pointer :Str, $value :HashRef/ArrayRef/Scalar) :Array/HashRef/ArrayRef/Scalar

This method is literally just an alias of the replace method. same girl, different name. ✨

copy($document :HashRef/ArrayRef/Scalar, $from_pointer :Str, $to_pointer :Str) :HashRef/ArrayRef/Scalar

  • $document :HashRef/ArrayRef/Scalar — target perl data structure, presentable by JSON format.
  • $from_pointer :Str — JSON Pointer string identifying the value in the document.
  • $to_pointer :Str — JSON Pointer string identifying the value in the document.

Copies the value identified by $from_pointer over to the target location identified by $to_pointer. for example:

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
heads up bestie: the "-" notation means next of last element in the array. in this example, "-" means 1. iykyk 💖

move($document :HashRef/ArrayRef/Scalar, $from_pointer :Str, $to_pointer :Str) :HashRef/ArrayRef/Scalar

  • $document :HashRef/ArrayRef/Scalar — target perl data structure, presentable by JSON format.
  • $from_pointer :Str — JSON Pointer string identifying the value in the document.
  • $to_pointer :Str — JSON Pointer string identifying the value in the document.

Moves the value identified by $from_pointer to the target location identified by $to_pointer. she's not copying, she's relocating. for example:

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":[{}]}

test($document :HashRef/ArrayRef/Scalar, $pointer :Str, $value :HashRef/ArrayRef/Scalar) :Int

  • $document :HashRef/ArrayRef/Scalar — target perl data structure, presentable by JSON format.
  • $pointer :Str — JSON Pointer string identifying the value in the document.
  • $value :HashRef/ArrayRef/Scalar — the perl data structure presentable by JSON format.

Returns whether the value identified by $pointer equals $value or not, in $document. and important: this method distinguishes the type of each value. like, a number is not a string, bestie, we do not blur those lines.

use JSON::Pointer;

my $document = { foo => 1 };

print JSON::Pointer->test($document, "/foo", 1); ### 1
print JSON::Pointer->test($document, "/foo", "1"); ### 0

traverse($document, $pointer, $opts) : JSON::Pointer::Context

This method is used as internal implementation only. don't touch her, she's working. 🙈

🍓 DEPENDENCIES 🍓

Perl 5.8.1 or later. old-school but she's stable, okay?

💀 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. i'm begging, please tell me instead of suffering in silence 😭

🌈 SEE ALSO 🌈

💜 AUTHOR 💜

Toru Yamaguchi <zigorou at cpan.org>

Copyright (c) 2013, Toru Yamaguchi. All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

and that's the whole page bestie ✨ this was documented for perl v5.34.0 and dated 2022-06-15 — go forth and point at things responsibly, JSON::Pointer(3pm) out 💅💖

📦 where this page comes from