NAME
    JSON::Pointer - A Perl implementation of JSON Pointer

VERSION
    This document describes JSON::Pointer version 0.01.

SYNOPSIS
      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]

DESCRIPTION
    This library is implemented JSON Pointer draft-09
    (http://tools.ietf.org/html/draft-ietf-appsawg-json-pointer-09) and some
    useful operator from JSON Patch draft-10
    (http://tools.ietf.org/html/draft-ietf-appsawg-json-patch-10).

    JSON Pointer is available to identify a specified value, and it is
    simillar to XPath. Please see the both of specifications for details.

METHODS
  get($document :HashRef/ArrayRef/Scalar, $pointer :Str, $strict :Int) :Scalar
    $document :HashRef/ArrayRef/Scalar
        Target perl data structure that is able to be presented by JSON
        format.

    $pointer :Str
        JSON Pointer string to identify specified value in the document.

    $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.

    Get specified value identified by *$pointer* from *$document*. For
    example,

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

  contains($document :HashRef/ArrayRef/Scalar, $pointer :Str) :Int
    $document :HashRef/ArrayRef/Scalar
        Target perl data structure that is able to present by JSON format.

    $pointer :Str
        JSON Pointer string to identify specified value in the document.

    Return which the target location identified by *$pointer* exists or not
    in the *$document*.

      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 that is able to be presented by JSON
        format.

    $pointer :Str
        JSON Pointer string to identify specified value in the document.

    $value :HashRef/ArrayRef/Scalar
        The perl data structure that is able to be presented by JSON format.

    Add specified *$value* on target location identified by *$pointer* in
    the *$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 that is able to be presented by JSON
        format.

    $pointer :Str
        JSON Pointer string to identify specified value in the document.

    Remove target location identified by *$pointer* in the *$document*.

      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 is contextial return value. When the return value of
    *wantarray* equals true, return *$patched_document* and
    *$removed_value*, or not return *$patched_document* only.

  replace($document :HashRef/ArrayRef/Scalar, $pointer :Str, $value :HashRef/ArrayRef/Scalar) :Array/HashRef/ArrayRef/Scalar
    $document :HashRef/ArrayRef/Scalar
        Target perl data structure that is able to be presented by JSON
        format.

    $pointer :Str
        JSON Pointer string to identify specified value in the document.

    $value :HashRef/ArrayRef/Scalar
        The perl data structure that is able to be presented by JSON format.

    Replace the value of target location specified by *$pointer* to the
    *$value* in the *$document*.

      use JSON::Pointer;

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

    This method is contextial return value. When the return value of
    *wantarray* equals true, return *$patched_document* and
    *$replaced_value*, or not return *$patched_document* only.

  set($document :HashRef/ArrayRef/Scalar, $pointer :Str, $value :HashRef/ArrayRef/Scalar) :Array/HashRef/ArrayRef/Scalar
    This method is alias of replace method.

  copy($document :HashRef/ArrayRef/Scalar, $from_pointer :Str, $to_pointer :Str) :HashRef/ArrayRef/Scalar
    $document :HashRef/ArrayRef/Scalar
        Target perl data structure that is able to be presented by JSON
        format.

    $from_pointer :Str
        JSON Pointer string to identify specified value in the document.

    $to_pointer :Str
        JSON Pointer string to identify specified value in the document.

    Copy the value identified by *$from_pointer* to 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

    Note that "-" notation means next of last element in the array. In this
    example, "-" means 1.

  move($document :HashRef/ArrayRef/Scalar, $from_pointer :Str, $to_pointer :Str) :HashRef/ArrayRef/Scalar
    $document :HashRef/ArrayRef/Scalar
        Target perl data structure that is able to be presented by JSON
        format.

    $from_pointer :Str
        JSON Pointer string to identify specified value in the document.

    $to_pointer :Str
        JSON Pointer string to identify specified value in the document.

    Move the value identified by *$from_pointer* to target location
    identified by *$to_pointer*. 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 that is able to be presented by JSON
        format.

    $pointer :Str
        JSON Pointer string to identify specified value in the document.

    $value :HashRef/ArrayRef/Scalar
        The perl data structure that is able to be presented by JSON format.

    Return which the value identified by *$pointer* equals *$value* or not
    in the *$document*. This method distinguish type of each values.

      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, $strict) : JSON::Pointer::Context
    This method is used as internal implementation only.

DEPENDENCIES
    Perl 5.8.1 or later.

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.

SEE ALSO
    perl
    Mojo::JSON::Pointer
        Many codes in this module is inspired by the module.

    <http://tools.ietf.org/html/draft-ietf-appsawg-json-pointer-09>
    <http://tools.ietf.org/html/draft-ietf-appsawg-json-patch-10>

AUTHOR
    Toru Yamaguchi <zigorou at cpan.org>

LICENSE AND COPYRIGHT
    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.