initial import

.gitignore

···
+_build

dune-project

···
+(lang dune 3.17)
+(name jsont-pointer)
+(version 0.1.0)
+
+(generate_opam_files true)
+
+(source (github avsm/jsont-pointer))
+(license ISC)
+(authors "Anil Madhavapeddy")
+(maintainers "[e-mail]")
+
+(package
+ (name jsont-pointer)
+ (synopsis "RFC 6901 JSON Pointer implementation for jsont")
+ (description "This library provides RFC 6901 JSON Pointer parsing, serialization, and evaluation compatible with jsont codecs. It also provides mutation operations suitable for implementing RFC 6902 JSON Patch.")
+ (depends
+  (ocaml (>= 4.14.0))
+  (jsont (>= 0.2.0))))

jsont-pointer.opam

···
+# This file is generated by dune, edit dune-project instead
+opam-version: "2.0"
+version: "0.1.0"
+synopsis: "RFC 6901 JSON Pointer implementation for jsont"
+description:
+  "This library provides RFC 6901 JSON Pointer parsing, serialization, and evaluation compatible with jsont codecs. It also provides mutation operations suitable for implementing RFC 6902 JSON Patch."
+maintainer: ["[e-mail]"]
+authors: ["Anil Madhavapeddy"]
+license: "ISC"
+homepage: "https://github.com/avsm/jsont-pointer"
+bug-reports: "https://github.com/avsm/jsont-pointer/issues"
+depends: [
+  "dune" {>= "3.17"}
+  "ocaml" {>= "4.14.0"}
+  "jsont" {>= "0.2.0"}
+  "odoc" {with-doc}
+]
+build: [
+  ["dune" "subst"] {dev}
+  [
+    "dune"
+    "build"
+    "-p"
+    name
+    "-j"
+    jobs
+    "@install"
+    "@runtest" {with-test}
+    "@doc" {with-doc}
+  ]
+]
+dev-repo: "git+https://github.com/avsm/jsont-pointer.git"

spec/rfc6901.txt

···
+
+
+
+
+
+
+Internet Engineering Task Force (IETF)                     P. Bryan, Ed.
+Request for Comments: 6901                                Salesforce.com
+Category: Standards Track                                         K. Zyp
+ISSN: 2070-1721                                            SitePen (USA)
+                                                      M. Nottingham, Ed.
+                                                                  Akamai
+                                                              April 2013
+
+
+               JavaScript Object Notation (JSON) Pointer
+
+Abstract
+
+   JSON Pointer defines a string syntax for identifying a specific value
+   within a JavaScript Object Notation (JSON) document.
+
+Status of This Memo
+
+   This is an Internet Standards Track document.
+
+   This document is a product of the Internet Engineering Task Force
+   (IETF).  It represents the consensus of the IETF community.  It has
+   received public review and has been approved for publication by the
+   Internet Engineering Steering Group (IESG).  Further information on
+   Internet Standards is available in Section 2 of RFC 5741.
+
+   Information about the current status of this document, any errata,
+   and how to provide feedback on it may be obtained at
+   http://www.rfc-editor.org/info/rfc6901.
+
+Copyright Notice
+
+   Copyright (c) 2013 IETF Trust and the persons identified as the
+   document authors.  All rights reserved.
+
+   This document is subject to BCP 78 and the IETF Trust's Legal
+   Provisions Relating to IETF Documents
+   (http://trustee.ietf.org/license-info) in effect on the date of
+   publication of this document.  Please review these documents
+   carefully, as they describe your rights and restrictions with respect
+   to this document.  Code Components extracted from this document must
+   include Simplified BSD License text as described in Section 4.e of
+   the Trust Legal Provisions and are provided without warranty as
+   described in the Simplified BSD License.
+
+
+
+
+
+
+
+Bryan, et al.                Standards Track                    [Page 1]
+
+RFC 6901                      JSON Pointer                    April 2013
+
+
+Table of Contents
+
+   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . . . 2
+   2.  Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . 2
+   3.  Syntax  . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
+   4.  Evaluation  . . . . . . . . . . . . . . . . . . . . . . . . . . 3
+   5.  JSON String Representation  . . . . . . . . . . . . . . . . . . 4
+   6.  URI Fragment Identifier Representation  . . . . . . . . . . . . 5
+   7.  Error Handling  . . . . . . . . . . . . . . . . . . . . . . . . 6
+   8.  Security Considerations . . . . . . . . . . . . . . . . . . . . 6
+   9.  Acknowledgements  . . . . . . . . . . . . . . . . . . . . . . . 7
+   10. References  . . . . . . . . . . . . . . . . . . . . . . . . . . 7
+     10.1.  Normative References . . . . . . . . . . . . . . . . . . . 7
+     10.2.  Informative References . . . . . . . . . . . . . . . . . . 7
+
+1.  Introduction
+
+   This specification defines JSON Pointer, a string syntax for
+   identifying a specific value within a JavaScript Object Notation
+   (JSON) document [RFC4627].  JSON Pointer is intended to be easily
+   expressed in JSON string values as well as Uniform Resource
+   Identifier (URI) [RFC3986] fragment identifiers.
+
+2.  Conventions
+
+   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
+   document are to be interpreted as described in [RFC2119].
+
+   This specification expresses normative syntax rules using Augmented
+   Backus-Naur Form (ABNF) [RFC5234] notation.
+
+3.  Syntax
+
+   A JSON Pointer is a Unicode string (see [RFC4627], Section 3)
+   containing a sequence of zero or more reference tokens, each prefixed
+   by a '/' (%x2F) character.
+
+   Because the characters '~' (%x7E) and '/' (%x2F) have special
+   meanings in JSON Pointer, '~' needs to be encoded as '~0' and '/'
+   needs to be encoded as '~1' when these characters appear in a
+   reference token.
+
+
+
+
+
+
+
+
+
+Bryan, et al.                Standards Track                    [Page 2]
+
+RFC 6901                      JSON Pointer                    April 2013
+
+
+   The ABNF syntax of a JSON Pointer is:
+
+      json-pointer    = *( "/" reference-token )
+      reference-token = *( unescaped / escaped )
+      unescaped       = %x00-2E / %x30-7D / %x7F-10FFFF
+         ; %x2F ('/') and %x7E ('~') are excluded from 'unescaped'
+      escaped         = "~" ( "0" / "1" )
+        ; representing '~' and '/', respectively
+
+   It is an error condition if a JSON Pointer value does not conform to
+   this syntax (see Section 7).
+
+   Note that JSON Pointers are specified in characters, not as bytes.
+
+4.  Evaluation
+
+   Evaluation of a JSON Pointer begins with a reference to the root
+   value of a JSON document and completes with a reference to some value
+   within the document.  Each reference token in the JSON Pointer is
+   evaluated sequentially.
+
+   Evaluation of each reference token begins by decoding any escaped
+   character sequence.  This is performed by first transforming any
+   occurrence of the sequence '~1' to '/', and then transforming any
+   occurrence of the sequence '~0' to '~'.  By performing the
+   substitutions in this order, an implementation avoids the error of
+   turning '~01' first into '~1' and then into '/', which would be
+   incorrect (the string '~01' correctly becomes '~1' after
+   transformation).
+
+   The reference token then modifies which value is referenced according
+   to the following scheme:
+
+   o  If the currently referenced value is a JSON object, the new
+      referenced value is the object member with the name identified by
+      the reference token.  The member name is equal to the token if it
+      has the same number of Unicode characters as the token and their
+      code points are byte-by-byte equal.  No Unicode character
+      normalization is performed.  If a referenced member name is not
+      unique in an object, the member that is referenced is undefined,
+      and evaluation fails (see below).
+
+
+
+
+
+
+
+
+
+
+Bryan, et al.                Standards Track                    [Page 3]
+
+RFC 6901                      JSON Pointer                    April 2013
+
+
+   o  If the currently referenced value is a JSON array, the reference
+      token MUST contain either:
+
+      *  characters comprised of digits (see ABNF below; note that
+         leading zeros are not allowed) that represent an unsigned
+         base-10 integer value, making the new referenced value the
+         array element with the zero-based index identified by the
+         token, or
+
+      *  exactly the single character "-", making the new referenced
+         value the (nonexistent) member after the last array element.
+
+   The ABNF syntax for array indices is:
+
+   array-index = %x30 / ( %x31-39 *(%x30-39) )
+                 ; "0", or digits without a leading "0"
+
+   Implementations will evaluate each reference token against the
+   document's contents and will raise an error condition if it fails to
+   resolve a concrete value for any of the JSON pointer's reference
+   tokens.  For example, if an array is referenced with a non-numeric
+   token, an error condition will be raised.  See Section 7 for details.
+
+   Note that the use of the "-" character to index an array will always
+   result in such an error condition because by definition it refers to
+   a nonexistent array element.  Thus, applications of JSON Pointer need
+   to specify how that character is to be handled, if it is to be
+   useful.
+
+   Any error condition for which a specific action is not defined by the
+   JSON Pointer application results in termination of evaluation.
+
+5.  JSON String Representation
+
+   A JSON Pointer can be represented in a JSON string value.  Per
+   [RFC4627], Section 2.5, all instances of quotation mark '"' (%x22),
+   reverse solidus '\' (%x5C), and control (%x00-1F) characters MUST be
+   escaped.
+
+   Note that before processing a JSON string as a JSON Pointer,
+   backslash escape sequences must be unescaped.
+
+
+
+
+
+
+
+
+
+
+Bryan, et al.                Standards Track                    [Page 4]
+
+RFC 6901                      JSON Pointer                    April 2013
+
+
+   For example, given the JSON document
+
+   {
+      "foo": ["bar", "baz"],
+      "": 0,
+      "a/b": 1,
+      "c%d": 2,
+      "e^f": 3,
+      "g|h": 4,
+      "i\\j": 5,
+      "k\"l": 6,
+      " ": 7,
+      "m~n": 8
+   }
+
+   The following JSON strings evaluate to the accompanying values:
+
+    ""           // the whole document
+    "/foo"       ["bar", "baz"]
+    "/foo/0"     "bar"
+    "/"          0
+    "/a~1b"      1
+    "/c%d"       2
+    "/e^f"       3
+    "/g|h"       4
+    "/i\\j"      5
+    "/k\"l"      6
+    "/ "         7
+    "/m~0n"      8
+
+6.  URI Fragment Identifier Representation
+
+   A JSON Pointer can be represented in a URI fragment identifier by
+   encoding it into octets using UTF-8 [RFC3629], while percent-encoding
+   those characters not allowed by the fragment rule in [RFC3986].
+
+   Note that a given media type needs to specify JSON Pointer as its
+   fragment identifier syntax explicitly (usually, in its registration
+   [RFC6838]).  That is, just because a document is JSON does not imply
+   that JSON Pointer can be used as its fragment identifier syntax.  In
+   particular, the fragment identifier syntax for application/json is
+   not JSON Pointer.
+
+
+
+
+
+
+
+
+
+Bryan, et al.                Standards Track                    [Page 5]
+
+RFC 6901                      JSON Pointer                    April 2013
+
+
+   Given the same example document as above, the following URI fragment
+   identifiers evaluate to the accompanying values:
+
+    #            // the whole document
+    #/foo        ["bar", "baz"]
+    #/foo/0      "bar"
+    #/           0
+    #/a~1b       1
+    #/c%25d      2
+    #/e%5Ef      3
+    #/g%7Ch      4
+    #/i%5Cj      5
+    #/k%22l      6
+    #/%20        7
+    #/m~0n       8
+
+7.  Error Handling
+
+   In the event of an error condition, evaluation of the JSON Pointer
+   fails to complete.
+
+   Error conditions include, but are not limited to:
+
+   o  Invalid pointer syntax
+
+   o  A pointer that references a nonexistent value
+
+   This specification does not define how errors are handled.  An
+   application of JSON Pointer SHOULD specify the impact and handling of
+   each type of error.
+
+   For example, some applications might stop pointer processing upon an
+   error, while others may attempt to recover from missing values by
+   inserting default ones.
+
+8.  Security Considerations
+
+   A given JSON Pointer is not guaranteed to reference an actual JSON
+   value.  Therefore, applications using JSON Pointer should anticipate
+   this situation by defining how a pointer that does not resolve ought
+   to be handled.
+
+   Note that JSON pointers can contain the NUL (Unicode U+0000)
+   character.  Care is needed not to misinterpret this character in
+   programming languages that use NUL to mark the end of a string.
+
+
+
+
+
+
+Bryan, et al.                Standards Track                    [Page 6]
+
+RFC 6901                      JSON Pointer                    April 2013
+
+
+9.  Acknowledgements
+
+   The following individuals contributed ideas, feedback, and wording to
+   this specification:
+
+      Mike Acar, Carsten Bormann, Tim Bray, Jacob Davies, Martin J.
+      Duerst, Bjoern Hoehrmann, James H. Manger, Drew Perttula, and
+      Julian Reschke.
+
+10.  References
+
+10.1.  Normative References
+
+   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
+              Requirement Levels", BCP 14, RFC 2119, March 1997.
+
+   [RFC3629]  Yergeau, F., "UTF-8, a transformation format of ISO
+              10646", STD 63, RFC 3629, November 2003.
+
+   [RFC3986]  Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
+              Resource Identifier (URI): Generic Syntax", STD 66,
+              RFC 3986, January 2005.
+
+   [RFC4627]  Crockford, D., "The application/json Media Type for
+              JavaScript Object Notation (JSON)", RFC 4627, July 2006.
+
+   [RFC5234]  Crocker, D. and P. Overell, "Augmented BNF for Syntax
+              Specifications: ABNF", STD 68, RFC 5234, January 2008.
+
+10.2.  Informative References
+
+   [RFC6838]  Freed, N., Klensin, J., and T. Hansen, "Media Type
+              Specifications and Registration Procedures", BCP 13,
+              RFC 6838, January 2013.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bryan, et al.                Standards Track                    [Page 7]
+
+RFC 6901                      JSON Pointer                    April 2013
+
+
+Authors' Addresses
+
+   Paul C. Bryan (editor)
+   Salesforce.com
+
+   Phone: [phone]
+   EMail: [e-mail]
+
+
+   Kris Zyp
+   SitePen (USA)
+
+   Phone: [phone]
+   EMail: [e-mail]
+
+
+   Mark Nottingham (editor)
+   Akamai
+
+   EMail: [e-mail]
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bryan, et al.                Standards Track                    [Page 8]
+

src/dune

···
+(library
+ (name jsont_pointer)
+ (public_name jsont-pointer)
+ (libraries jsont))

src/jsont_pointer.ml

···
+(*---------------------------------------------------------------------------
+   Copyright (c) 2024 The jsont programmers. All rights reserved.
+   SPDX-License-Identifier: ISC
+  ---------------------------------------------------------------------------*)
+
+(* Token escaping/unescaping per RFC 6901 Section 3-4 *)
+module Token = struct
+  type t = string
+
+  let escape s =
+    let b = Buffer.create (String.length s) in
+    String.iter (function
+      | '~' -> Buffer.add_string b "~0"
+      | '/' -> Buffer.add_string b "~1"
+      | c -> Buffer.add_char b c
+    ) s;
+    Buffer.contents b
+
+  let unescape s =
+    let len = String.length s in
+    let b = Buffer.create len in
+    let rec loop i =
+      if i >= len then Buffer.contents b
+      else match s.[i] with
+        | '~' when i + 1 >= len ->
+          Jsont.Error.msgf Jsont.Meta.none
+            "Invalid JSON Pointer: incomplete escape sequence at end"
+        | '~' ->
+          (match s.[i + 1] with
+           | '0' -> Buffer.add_char b '~'; loop (i + 2)
+           | '1' -> Buffer.add_char b '/'; loop (i + 2)
+           | c ->
+             Jsont.Error.msgf Jsont.Meta.none
+               "Invalid JSON Pointer: invalid escape sequence ~%c" c)
+        | c -> Buffer.add_char b c; loop (i + 1)
+    in
+    loop 0
+
+  (* Check if a token is a valid array index per RFC 6901 ABNF:
+     array-index = %x30 / ( %x31-39 *(%x30-39) )
+     i.e., "0" or a non-zero digit followed by any digits *)
+  let is_valid_array_index s =
+    let len = String.length s in
+    let is_digit c = c >= '0' && c <= '9' in
+    if len = 0 then None
+    else if len = 1 && s.[0] = '0' then Some 0
+    else if s.[0] >= '1' && s.[0] <= '9' then
+      let rec all_digits i =
+        if i >= len then true
+        else if is_digit s.[i] then all_digits (i + 1)
+        else false
+      in
+      if all_digits 1 then int_of_string_opt s else None
+    else None
+end
+
+(* Index type - represents how a token is interpreted in context *)
+module Index = struct
+  type t =
+    | Mem of string
+    | Nth of int
+    | End
+
+  let pp ppf = function
+    | Mem s -> Format.fprintf ppf "/%s" (Token.escape s)
+    | Nth n -> Format.fprintf ppf "/%d" n
+    | End -> Format.fprintf ppf "/-"
+
+  let equal i1 i2 = match i1, i2 with
+    | Mem s1, Mem s2 -> String.equal s1 s2
+    | Nth n1, Nth n2 -> Int.equal n1 n2
+    | End, End -> true
+    | _ -> false
+
+  let compare i1 i2 = match i1, i2 with
+    | Mem s1, Mem s2 -> String.compare s1 s2
+    | Mem _, _ -> -1
+    | _, Mem _ -> 1
+    | Nth n1, Nth n2 -> Int.compare n1 n2
+    | Nth _, End -> -1
+    | End, Nth _ -> 1
+    | End, End -> 0
+
+  let of_path_index (idx : Jsont.Path.index) : t =
+    match idx with
+    | Jsont.Path.Mem (s, _meta) -> Mem s
+    | Jsont.Path.Nth (n, _meta) -> Nth n
+
+  let to_path_index (idx : t) : Jsont.Path.index option =
+    match idx with
+    | Mem s -> Some (Jsont.Path.Mem (s, Jsont.Meta.none))
+    | Nth n -> Some (Jsont.Path.Nth (n, Jsont.Meta.none))
+    | End -> None
+end
+
+(* Internal representation: raw unescaped tokens.
+   Per RFC 6901, interpretation as member name vs array index
+   depends on the JSON value type at evaluation time. *)
+module Segment = struct
+  type t =
+    | Token of string  (* Unescaped reference token *)
+    | End              (* The "-" token for end-of-array *)
+
+  let of_escaped_string s =
+    if s = "-" then End
+    else Token (Token.unescape s)
+
+  let to_escaped_string = function
+    | Token s -> Token.escape s
+    | End -> "-"
+
+  (* Convert to Index for a given JSON value type *)
+  let to_index seg ~for_array =
+    match seg with
+    | End -> Index.End
+    | Token s ->
+      if for_array then
+        match Token.is_valid_array_index s with
+        | Some n -> Index.Nth n
+        | None -> Index.Mem s  (* Invalid index becomes member for error msg *)
+      else
+        Index.Mem s
+
+  (* Convert from Index *)
+  let of_index = function
+    | Index.End -> End
+    | Index.Mem s -> Token s
+    | Index.Nth n -> Token (string_of_int n)
+end
+
+(* Pointer type - list of segments *)
+type t = Segment.t list
+
+let root = []
+
+let is_root p = p = []
+
+(* Convert indices to segments *)
+let make indices = List.map Segment.of_index indices
+
+(* Convert segments to indices, assuming array context for numeric tokens *)
+let indices p = List.map (fun seg -> Segment.to_index seg ~for_array:true) p
+
+let append p idx = p @ [Segment.of_index idx]
+
+let concat p1 p2 = p1 @ p2
+
+let parent p = match List.rev p with
+  | [] -> None
+  | _ :: rest -> Some (List.rev rest)
+
+let last p = match List.rev p with
+  | [] -> None
+  | seg :: _ -> Some (Segment.to_index seg ~for_array:true)
+
+(* Parsing *)
+
+let of_string s =
+  if s = "" then root
+  else if s.[0] <> '/' then
+    Jsont.Error.msgf Jsont.Meta.none
+      "Invalid JSON Pointer: must be empty or start with '/': %s" s
+  else
+    let rest = String.sub s 1 (String.length s - 1) in
+    let tokens = String.split_on_char '/' rest in
+    List.map Segment.of_escaped_string tokens
+
+let of_string_result s =
+  try Ok (of_string s)
+  with Jsont.Error (_, _, _) as e ->
+    Error (Jsont.Error.to_string (match e with Jsont.Error e -> e | _ -> assert false))
+
+(* URI fragment percent-decoding *)
+let hex_value c =
+  if c >= '0' && c <= '9' then Char.code c - Char.code '0'
+  else if c >= 'A' && c <= 'F' then Char.code c - Char.code 'A' + 10
+  else if c >= 'a' && c <= 'f' then Char.code c - Char.code 'a' + 10
+  else -1
+
+let percent_decode s =
+  let len = String.length s in
+  let b = Buffer.create len in
+  let rec loop i =
+    if i >= len then Buffer.contents b
+    else match s.[i] with
+      | '%' when i + 2 < len ->
+        let h1 = hex_value s.[i + 1] in
+        let h2 = hex_value s.[i + 2] in
+        if h1 >= 0 && h2 >= 0 then begin
+          Buffer.add_char b (Char.chr ((h1 lsl 4) lor h2));
+          loop (i + 3)
+        end else
+          Jsont.Error.msgf Jsont.Meta.none
+            "Invalid percent-encoding at position %d" i
+      | '%' ->
+        Jsont.Error.msgf Jsont.Meta.none
+          "Incomplete percent-encoding at position %d" i
+      | c -> Buffer.add_char b c; loop (i + 1)
+  in
+  loop 0
+
+let of_uri_fragment s =
+  of_string (percent_decode s)
+
+let of_uri_fragment_result s =
+  try Ok (of_uri_fragment s)
+  with Jsont.Error (_, _, _) as e ->
+    Error (Jsont.Error.to_string (match e with Jsont.Error e -> e | _ -> assert false))
+
+(* Serialization *)
+
+let to_string p =
+  if p = [] then ""
+  else
+    let b = Buffer.create 64 in
+    List.iter (fun seg ->
+      Buffer.add_char b '/';
+      Buffer.add_string b (Segment.to_escaped_string seg)
+    ) p;
+    Buffer.contents b
+
+(* URI fragment percent-encoding *)
+let needs_percent_encoding c =
+  (* RFC 3986 fragment: unreserved / pct-encoded / sub-delims / ":" / "@" / "/" / "?" *)
+  (* unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~" *)
+  (* sub-delims = "!" / "$" / "&" / "'" / "(" / ")" / "*" / "+" / "," / ";" / "=" *)
+  not (
+    (c >= 'A' && c <= 'Z') ||
+    (c >= 'a' && c <= 'z') ||
+    (c >= '0' && c <= '9') ||
+    c = '-' || c = '.' || c = '_' || c = '~' ||
+    c = '!' || c = '$' || c = '&' || c = '\'' ||
+    c = '(' || c = ')' || c = '*' || c = '+' ||
+    c = ',' || c = ';' || c = '=' ||
+    c = ':' || c = '@' || c = '/' || c = '?'
+  )
+
+let hex_char n =
+  if n < 10 then Char.chr (Char.code '0' + n)
+  else Char.chr (Char.code 'A' + n - 10)
+
+let percent_encode s =
+  let b = Buffer.create (String.length s * 3) in
+  String.iter (fun c ->
+    if needs_percent_encoding c then begin
+      let code = Char.code c in
+      Buffer.add_char b '%';
+      Buffer.add_char b (hex_char (code lsr 4));
+      Buffer.add_char b (hex_char (code land 0xF))
+    end else
+      Buffer.add_char b c
+  ) s;
+  Buffer.contents b
+
+let to_uri_fragment p =
+  percent_encode (to_string p)
+
+let pp ppf p =
+  Format.pp_print_string ppf (to_string p)
+
+(* Comparison *)
+
+let segment_equal s1 s2 = match s1, s2 with
+  | Segment.Token t1, Segment.Token t2 -> String.equal t1 t2
+  | Segment.End, Segment.End -> true
+  | _ -> false
+
+let segment_compare s1 s2 = match s1, s2 with
+  | Segment.Token t1, Segment.Token t2 -> String.compare t1 t2
+  | Segment.Token _, Segment.End -> -1
+  | Segment.End, Segment.Token _ -> 1
+  | Segment.End, Segment.End -> 0
+
+let equal p1 p2 =
+  List.length p1 = List.length p2 &&
+  List.for_all2 segment_equal p1 p2
+
+let compare p1 p2 =
+  let rec loop l1 l2 = match l1, l2 with
+    | [], [] -> 0
+    | [], _ -> -1
+    | _, [] -> 1
+    | h1 :: t1, h2 :: t2 ->
+      let c = segment_compare h1 h2 in
+      if c <> 0 then c else loop t1 t2
+  in
+  loop p1 p2
+
+(* Path conversion *)
+
+let segment_of_path_index (idx : Jsont.Path.index) : Segment.t =
+  match idx with
+  | Jsont.Path.Mem (s, _meta) -> Segment.Token s
+  | Jsont.Path.Nth (n, _meta) -> Segment.Token (string_of_int n)
+
+let of_path (p : Jsont.Path.t) : t =
+  List.rev_map segment_of_path_index (Jsont.Path.rev_indices p)
+
+let to_path p =
+  let rec convert acc = function
+    | [] -> Some acc
+    | Segment.End :: _ -> None
+    | Segment.Token s :: rest ->
+      (* For path conversion, we need to decide if it's a member or index.
+         We use array context for numeric tokens since Jsont.Path distinguishes. *)
+      let acc' = match Token.is_valid_array_index s with
+        | Some n -> Jsont.Path.nth ~meta:Jsont.Meta.none n acc
+        | None -> Jsont.Path.mem ~meta:Jsont.Meta.none s acc
+      in
+      convert acc' rest
+  in
+  convert Jsont.Path.root p
+
+let to_path_exn p =
+  match to_path p with
+  | Some path -> path
+  | None ->
+    Jsont.Error.msgf Jsont.Meta.none
+      "Cannot convert JSON Pointer with '-' index to Jsont.Path"
+
+(* Evaluation helpers *)
+
+let json_sort_string (j : Jsont.json) =
+  match j with
+  | Null _ -> "null"
+  | Bool _ -> "boolean"
+  | Number _ -> "number"
+  | String _ -> "string"
+  | Array _ -> "array"
+  | Object _ -> "object"
+
+let get_member name (obj : Jsont.object') =
+  List.find_opt (fun ((n, _), _) -> String.equal n name) obj
+
+let get_nth n (arr : Jsont.json list) =
+  if n < 0 || n >= List.length arr then None
+  else Some (List.nth arr n)
+
+(* Evaluation *)
+
+let rec eval_get p json =
+  match p with
+  | [] -> json
+  | Segment.End :: _ ->
+    Jsont.Error.msgf (Jsont.Json.meta json)
+      "JSON Pointer: '-' (end marker) refers to nonexistent array element"
+  | Segment.Token token :: rest ->
+    (match json with
+     | Jsont.Object (members, _) ->
+       (* For objects, token is always a member name *)
+       (match get_member token members with
+        | Some (_, value) -> eval_get rest value
+        | None ->
+          Jsont.Error.msgf (Jsont.Json.meta json)
+            "JSON Pointer: member '%s' not found" token)
+     | Jsont.Array (elements, _) ->
+       (* For arrays, token must be a valid array index *)
+       (match Token.is_valid_array_index token with
+        | Some n ->
+          (match get_nth n elements with
+           | Some value -> eval_get rest value
+           | None ->
+             Jsont.Error.msgf (Jsont.Json.meta json)
+               "JSON Pointer: index %d out of bounds (array has %d elements)"
+               n (List.length elements))
+        | None ->
+          Jsont.Error.msgf (Jsont.Json.meta json)
+            "JSON Pointer: invalid array index '%s'" token)
+     | _ ->
+       Jsont.Error.msgf (Jsont.Json.meta json)
+         "JSON Pointer: cannot index into %s with '%s'"
+         (json_sort_string json) token)
+
+let get p json = eval_get p json
+
+let get_result p json =
+  try Ok (get p json)
+  with Jsont.Error e -> Error e
+
+let find p json =
+  try Some (get p json)
+  with Jsont.Error _ -> None
+
+(* Mutation helpers *)
+
+let set_member name value (obj : Jsont.object') : Jsont.object' =
+  let found = ref false in
+  let result = List.map (fun ((n, m), v) ->
+    if String.equal n name then begin
+      found := true;
+      ((n, m), value)
+    end else
+      ((n, m), v)
+  ) obj in
+  if !found then result
+  else obj @ [((name, Jsont.Meta.none), value)]
+
+let remove_member name (obj : Jsont.object') : Jsont.object' =
+  List.filter (fun ((n, _), _) -> not (String.equal n name)) obj
+
+let insert_at n value lst =
+  let rec loop i acc = function
+    | [] when i = n -> List.rev (value :: acc)
+    | [] -> List.rev acc (* shouldn't happen if n is valid *)
+    | h :: t when i = n -> List.rev_append (value :: acc) (h :: t)
+    | h :: t -> loop (i + 1) (h :: acc) t
+  in
+  loop 0 [] lst
+
+let remove_at n lst =
+  let rec loop i acc = function
+    | [] -> List.rev acc
+    | _ :: t when i = n -> List.rev_append acc t
+    | h :: t -> loop (i + 1) (h :: acc) t
+  in
+  loop 0 [] lst
+
+let replace_at n value lst =
+  List.mapi (fun i v -> if i = n then value else v) lst
+
+(* Mutation: set *)
+
+let rec eval_set p value json =
+  match p with
+  | [] -> value
+  | [Segment.End] ->
+    (match json with
+     | Jsont.Array (elements, meta) ->
+       Jsont.Array (elements @ [value], meta)
+     | _ ->
+       Jsont.Error.msgf (Jsont.Json.meta json)
+         "JSON Pointer: '-' can only be used on arrays, got %s"
+         (json_sort_string json))
+  | Segment.End :: _ ->
+    Jsont.Error.msgf (Jsont.Json.meta json)
+      "JSON Pointer: '-' (end marker) refers to nonexistent array element"
+  | [Segment.Token token] ->
+    (match json with
+     | Jsont.Object (members, meta) ->
+       if Option.is_some (get_member token members) then
+         Jsont.Object (set_member token value members, meta)
+       else
+         Jsont.Error.msgf (Jsont.Json.meta json)
+           "JSON Pointer: member '%s' not found for set" token
+     | Jsont.Array (elements, meta) ->
+       (match Token.is_valid_array_index token with
+        | Some n when n >= 0 && n < List.length elements ->
+          Jsont.Array (replace_at n value elements, meta)
+        | Some n ->
+          Jsont.Error.msgf (Jsont.Json.meta json)
+            "JSON Pointer: index %d out of bounds for set" n
+        | None ->
+          Jsont.Error.msgf (Jsont.Json.meta json)
+            "JSON Pointer: invalid array index '%s'" token)
+     | _ ->
+       Jsont.Error.msgf (Jsont.Json.meta json)
+         "JSON Pointer: cannot set in %s" (json_sort_string json))
+  | Segment.Token token :: rest ->
+    (match json with
+     | Jsont.Object (members, meta) ->
+       (match get_member token members with
+        | Some (_, child) ->
+          Jsont.Object (set_member token (eval_set rest value child) members, meta)
+        | None ->
+          Jsont.Error.msgf (Jsont.Json.meta json)
+            "JSON Pointer: member '%s' not found" token)
+     | Jsont.Array (elements, meta) ->
+       (match Token.is_valid_array_index token with
+        | Some n ->
+          (match get_nth n elements with
+           | Some child ->
+             Jsont.Array (replace_at n (eval_set rest value child) elements, meta)
+           | None ->
+             Jsont.Error.msgf (Jsont.Json.meta json)
+               "JSON Pointer: index %d out of bounds" n)
+        | None ->
+          Jsont.Error.msgf (Jsont.Json.meta json)
+            "JSON Pointer: invalid array index '%s'" token)
+     | _ ->
+       Jsont.Error.msgf (Jsont.Json.meta json)
+         "JSON Pointer: cannot navigate through %s" (json_sort_string json))
+
+let set p json ~value = eval_set p value json
+
+(* Mutation: add (RFC 6902 semantics) *)
+
+let rec eval_add p value json =
+  match p with
+  | [] -> value
+  | [Segment.End] ->
+    (match json with
+     | Jsont.Array (elements, meta) ->
+       Jsont.Array (elements @ [value], meta)
+     | _ ->
+       Jsont.Error.msgf (Jsont.Json.meta json)
+         "JSON Pointer: '-' can only be used on arrays, got %s"
+         (json_sort_string json))
+  | Segment.End :: _ ->
+    Jsont.Error.msgf (Jsont.Json.meta json)
+      "JSON Pointer: '-' in non-final position"
+  | [Segment.Token token] ->
+    (match json with
+     | Jsont.Object (members, meta) ->
+       (* For objects, add/replace member *)
+       Jsont.Object (set_member token value members, meta)
+     | Jsont.Array (elements, meta) ->
+       (* For arrays, insert at index *)
+       (match Token.is_valid_array_index token with
+        | Some n ->
+          let len = List.length elements in
+          if n >= 0 && n <= len then
+            Jsont.Array (insert_at n value elements, meta)
+          else
+            Jsont.Error.msgf (Jsont.Json.meta json)
+              "JSON Pointer: index %d out of bounds for add (array has %d elements)"
+              n len
+        | None ->
+          Jsont.Error.msgf (Jsont.Json.meta json)
+            "JSON Pointer: invalid array index '%s'" token)
+     | _ ->
+       Jsont.Error.msgf (Jsont.Json.meta json)
+         "JSON Pointer: cannot add to %s" (json_sort_string json))
+  | Segment.Token token :: rest ->
+    (match json with
+     | Jsont.Object (members, meta) ->
+       (match get_member token members with
+        | Some (_, child) ->
+          Jsont.Object (set_member token (eval_add rest value child) members, meta)
+        | None ->
+          Jsont.Error.msgf (Jsont.Json.meta json)
+            "JSON Pointer: member '%s' not found" token)
+     | Jsont.Array (elements, meta) ->
+       (match Token.is_valid_array_index token with
+        | Some n ->
+          (match get_nth n elements with
+           | Some child ->
+             Jsont.Array (replace_at n (eval_add rest value child) elements, meta)
+           | None ->
+             Jsont.Error.msgf (Jsont.Json.meta json)
+               "JSON Pointer: index %d out of bounds" n)
+        | None ->
+          Jsont.Error.msgf (Jsont.Json.meta json)
+            "JSON Pointer: invalid array index '%s'" token)
+     | _ ->
+       Jsont.Error.msgf (Jsont.Json.meta json)
+         "JSON Pointer: cannot navigate through %s" (json_sort_string json))
+
+let add p json ~value = eval_add p value json
+
+(* Mutation: remove *)
+
+let rec eval_remove p json =
+  match p with
+  | [] ->
+    Jsont.Error.msgf Jsont.Meta.none
+      "JSON Pointer: cannot remove root document"
+  | [Segment.End] ->
+    Jsont.Error.msgf (Jsont.Json.meta json)
+      "JSON Pointer: '-' refers to nonexistent element"
+  | Segment.End :: _ ->
+    Jsont.Error.msgf (Jsont.Json.meta json)
+      "JSON Pointer: '-' in non-final position"
+  | [Segment.Token token] ->
+    (match json with
+     | Jsont.Object (members, meta) ->
+       if Option.is_some (get_member token members) then
+         Jsont.Object (remove_member token members, meta)
+       else
+         Jsont.Error.msgf (Jsont.Json.meta json)
+           "JSON Pointer: member '%s' not found for remove" token
+     | Jsont.Array (elements, meta) ->
+       (match Token.is_valid_array_index token with
+        | Some n when n >= 0 && n < List.length elements ->
+          Jsont.Array (remove_at n elements, meta)
+        | Some n ->
+          Jsont.Error.msgf (Jsont.Json.meta json)
+            "JSON Pointer: index %d out of bounds for remove" n
+        | None ->
+          Jsont.Error.msgf (Jsont.Json.meta json)
+            "JSON Pointer: invalid array index '%s'" token)
+     | _ ->
+       Jsont.Error.msgf (Jsont.Json.meta json)
+         "JSON Pointer: cannot remove from %s" (json_sort_string json))
+  | Segment.Token token :: rest ->
+    (match json with
+     | Jsont.Object (members, meta) ->
+       (match get_member token members with
+        | Some (_, child) ->
+          Jsont.Object (set_member token (eval_remove rest child) members, meta)
+        | None ->
+          Jsont.Error.msgf (Jsont.Json.meta json)
+            "JSON Pointer: member '%s' not found" token)
+     | Jsont.Array (elements, meta) ->
+       (match Token.is_valid_array_index token with
+        | Some n ->
+          (match get_nth n elements with
+           | Some child ->
+             Jsont.Array (replace_at n (eval_remove rest child) elements, meta)
+           | None ->
+             Jsont.Error.msgf (Jsont.Json.meta json)
+               "JSON Pointer: index %d out of bounds" n)
+        | None ->
+          Jsont.Error.msgf (Jsont.Json.meta json)
+            "JSON Pointer: invalid array index '%s'" token)
+     | _ ->
+       Jsont.Error.msgf (Jsont.Json.meta json)
+         "JSON Pointer: cannot navigate through %s" (json_sort_string json))
+
+let remove p json = eval_remove p json
+
+(* Mutation: replace *)
+
+let replace p json ~value =
+  (* Replace requires the target to exist, unlike add *)
+  let _ = get p json in (* Will raise if not found *)
+  eval_set p value json
+
+(* Mutation: move *)
+
+let is_prefix_of p1 p2 =
+  let rec loop l1 l2 = match l1, l2 with
+    | [], _ -> true
+    | _, [] -> false
+    | h1 :: t1, h2 :: t2 ->
+      segment_equal h1 h2 && loop t1 t2
+  in
+  loop p1 p2
+
+let move ~from ~path json =
+  (* Check for cycle: path cannot be a proper prefix of from *)
+  if is_prefix_of path from && not (equal path from) then
+    Jsont.Error.msgf Jsont.Meta.none
+      "JSON Pointer: move would create cycle (path is prefix of from)";
+  let value = get from json in
+  let json' = remove from json in
+  add path json' ~value
+
+(* Mutation: copy *)
+
+let copy ~from ~path json =
+  let value = get from json in
+  add path json ~value
+
+(* Mutation: test *)
+
+let test p json ~expected =
+  match find p json with
+  | None -> false
+  | Some value -> Jsont.Json.equal value expected
+
+(* Jsont codec *)
+
+let jsont : t Jsont.t =
+  let dec _meta s = of_string s in
+  let enc p = to_string p in
+  Jsont.Base.string (Jsont.Base.map
+    ~kind:"JSON Pointer"
+    ~doc:"RFC 6901 JSON Pointer"
+    ~dec ~enc ())
+
+let jsont_uri_fragment : t Jsont.t =
+  let dec _meta s = of_uri_fragment s in
+  let enc p = to_uri_fragment p in
+  Jsont.Base.string (Jsont.Base.map
+    ~kind:"JSON Pointer (URI fragment)"
+    ~doc:"RFC 6901 JSON Pointer in URI fragment encoding"
+    ~dec ~enc ())
+
+(* Query combinators *)
+
+let path ?absent p t =
+  let dec json =
+    match find p json with
+    | Some value ->
+      (match Jsont.Json.decode' t value with
+       | Ok v -> v
+       | Error e -> raise (Jsont.Error e))
+    | None ->
+      match absent with
+      | Some v -> v
+      | None ->
+        Jsont.Error.msgf Jsont.Meta.none
+          "JSON Pointer %s: path not found" (to_string p)
+  in
+  Jsont.map Jsont.json ~dec ~enc:(fun _ ->
+    Jsont.Error.msgf Jsont.Meta.none "path: encode not supported")
+
+let set_path ?(allow_absent = false) t p v =
+  let encoded = match Jsont.Json.encode' t v with
+    | Ok json -> json
+    | Error e -> raise (Jsont.Error e)
+  in
+  let dec json =
+    if allow_absent then
+      add p json ~value:encoded
+    else
+      set p json ~value:encoded
+  in
+  Jsont.map Jsont.json ~dec ~enc:(fun j -> j)
+
+let update_path ?absent p t =
+  let dec json =
+    let value = match find p json with
+      | Some v -> v
+      | None ->
+        match absent with
+        | Some v ->
+          (match Jsont.Json.encode' t v with
+           | Ok j -> j
+           | Error e -> raise (Jsont.Error e))
+        | None ->
+          Jsont.Error.msgf Jsont.Meta.none
+            "JSON Pointer %s: path not found" (to_string p)
+    in
+    let decoded = match Jsont.Json.decode' t value with
+      | Ok v -> v
+      | Error e -> raise (Jsont.Error e)
+    in
+    let re_encoded = match Jsont.Json.encode' t decoded with
+      | Ok j -> j
+      | Error e -> raise (Jsont.Error e)
+    in
+    set p json ~value:re_encoded
+  in
+  Jsont.map Jsont.json ~dec ~enc:(fun j -> j)
+
+let delete_path ?(allow_absent = false) p =
+  let dec json =
+    if allow_absent then
+      match find p json with
+      | Some _ -> remove p json
+      | None -> json
+    else
+      remove p json
+  in
+  Jsont.map Jsont.json ~dec ~enc:(fun j -> j)

src/jsont_pointer.mli

···
+(*---------------------------------------------------------------------------
+   Copyright (c) 2024 The jsont programmers. All rights reserved.
+   SPDX-License-Identifier: ISC
+  ---------------------------------------------------------------------------*)
+
+(** RFC 6901 JSON Pointer implementation for jsont.
+
+    This module provides {{:https://www.rfc-editor.org/rfc/rfc6901}RFC 6901}
+    JSON Pointer parsing, serialization, and evaluation compatible with
+    {!Jsont} codecs.
+
+    A JSON Pointer is a string syntax for identifying a specific value within
+    a JSON document. For example, given the JSON document:
+    {v
+    {
+      "foo": ["bar", "baz"],
+      "": 0,
+      "a/b": 1,
+      "m~n": 2
+    }
+    v}
+
+    The following JSON Pointers evaluate to:
+    {ul
+    {- [""] - the whole document}
+    {- ["/foo"] - the array [\["bar", "baz"\]]}
+    {- ["/foo/0"] - the string ["bar"]}
+    {- ["/"] - the integer [0] (empty string key)}
+    {- ["/a~1b"] - the integer [1] ([~1] escapes [/])}
+    {- ["/m~0n"] - the integer [2] ([~0] escapes [~])}}
+
+    {1:tokens Reference Tokens}
+
+    JSON Pointer uses escape sequences for special characters in reference
+    tokens. The character [~] must be encoded as [~0] and [/] as [~1].
+    When unescaping, [~1] is processed before [~0] to correctly handle
+    sequences like [~01] which should become [~1], not [/]. *)
+
+(** {1 Reference tokens}
+
+    Reference tokens are the individual segments between [/] characters
+    in a JSON Pointer string. They require escaping of [~] and [/]. *)
+module Token : sig
+
+  type t = string
+  (** The type for unescaped reference tokens. These are plain strings
+      representing object member names or array index strings. *)
+
+  val escape : t -> string
+  (** [escape s] escapes special characters in [s] for use in a JSON Pointer.
+      Specifically, [~] becomes [~0] and [/] becomes [~1]. *)
+
+  val unescape : string -> t
+  (** [unescape s] unescapes a JSON Pointer reference token.
+      Specifically, [~1] becomes [/] and [~0] becomes [~].
+
+      @raise Jsont.Error if [s] contains invalid escape sequences
+      (a [~] not followed by [0] or [1]). *)
+end
+
+(** {1 Indices}
+
+    Indices represent individual navigation steps in a JSON Pointer.
+    For objects, this is a member name. For arrays, this is either
+    a numeric index or the special end-of-array marker [-]. *)
+module Index : sig
+
+  type t =
+    | Mem of string
+    (** [Mem name] indexes into an object member with the given [name].
+        The name is unescaped (i.e., [/] and [~] appear literally). *)
+    | Nth of int
+    (** [Nth n] indexes into an array at position [n] (zero-based).
+        Must be non-negative and without leading zeros in string form
+        (except for [0] itself). *)
+    | End
+    (** [End] represents the [-] token, indicating the position after
+        the last element of an array. This is used for append operations
+        in {!Jsont_pointer.add} and similar mutation functions.
+        Evaluating a pointer containing [End] with {!Jsont_pointer.get}
+        will raise an error since it refers to a nonexistent element. *)
+
+  val pp : Format.formatter -> t -> unit
+  (** [pp] formats an index in JSON Pointer string notation. *)
+
+  val equal : t -> t -> bool
+  (** [equal i1 i2] is [true] iff [i1] and [i2] are the same index. *)
+
+  val compare : t -> t -> int
+  (** [compare i1 i2] is a total order on indices. *)
+
+  (** {2:jsont_conv Conversion with Jsont.Path} *)
+
+  val of_path_index : Jsont.Path.index -> t
+  (** [of_path_index idx] converts a {!Jsont.Path.index} to an index. *)
+
+  val to_path_index : t -> Jsont.Path.index option
+  (** [to_path_index idx] converts to a {!Jsont.Path.index}.
+      Returns [None] for {!End} since it has no equivalent in
+      {!Jsont.Path}. *)
+end
+
+(** {1 Pointers} *)
+
+type t
+(** The type for JSON Pointers. A pointer is a sequence of {!Index.t}
+    values representing a path from the root of a JSON document to
+    a specific value. *)
+
+val root : t
+(** [root] is the empty pointer that references the whole document.
+    In string form this is [""]. *)
+
+val is_root : t -> bool
+(** [is_root p] is [true] iff [p] is the {!root} pointer. *)
+
+val make : Index.t list -> t
+(** [make indices] creates a pointer from a list of indices.
+    The list is ordered from root to target (i.e., the first element
+    is the first step from the root). *)
+
+val indices : t -> Index.t list
+(** [indices p] returns the indices of [p] from root to target. *)
+
+val append : t -> Index.t -> t
+(** [append p idx] appends [idx] to the end of pointer [p]. *)
+
+val concat : t -> t -> t
+(** [concat p1 p2] appends all indices of [p2] to [p1]. *)
+
+val parent : t -> t option
+(** [parent p] returns the parent pointer of [p], or [None] if [p]
+    is the {!root}. *)
+
+val last : t -> Index.t option
+(** [last p] returns the last index of [p], or [None] if [p] is
+    the {!root}. *)
+
+(** {2:parsing Parsing} *)
+
+val of_string : string -> t
+(** [of_string s] parses a JSON Pointer from its string representation.
+
+    The string must be either empty (representing the root) or start
+    with [/]. Each segment between [/] characters is unescaped as a
+    reference token. Segments that are valid non-negative integers
+    without leading zeros become {!Index.Nth} indices; the string [-]
+    becomes {!Index.End}; all others become {!Index.Mem}.
+
+    @raise Jsont.Error if [s] has invalid syntax:
+    - Non-empty string not starting with [/]
+    - Invalid escape sequence ([~] not followed by [0] or [1])
+    - Array index with leading zeros
+    - Array index that overflows [int] *)
+
+val of_string_result : string -> (t, string) result
+(** [of_string_result s] is like {!of_string} but returns a result
+    instead of raising. *)
+
+val of_uri_fragment : string -> t
+(** [of_uri_fragment s] parses a JSON Pointer from URI fragment form.
+
+    This is like {!of_string} but first percent-decodes the string
+    according to {{:https://www.rfc-editor.org/rfc/rfc3986}RFC 3986}.
+    The leading [#] should {b not} be included in [s].
+
+    @raise Jsont.Error on invalid syntax or invalid percent-encoding. *)
+
+val of_uri_fragment_result : string -> (t, string) result
+(** [of_uri_fragment_result s] is like {!of_uri_fragment} but returns
+    a result instead of raising. *)
+
+(** {2:serializing Serializing} *)
+
+val to_string : t -> string
+(** [to_string p] serializes [p] to its JSON Pointer string representation.
+
+    Returns [""] for the root pointer, otherwise [/] followed by
+    escaped reference tokens joined by [/]. *)
+
+val to_uri_fragment : t -> string
+(** [to_uri_fragment p] serializes [p] to URI fragment form.
+
+    This is like {!to_string} but additionally percent-encodes
+    characters that are not allowed in URI fragments per RFC 3986.
+    The leading [#] is {b not} included in the result. *)
+
+val pp : Format.formatter -> t -> unit
+(** [pp] formats a pointer using {!to_string}. *)
+
+(** {2:comparison Comparison} *)
+
+val equal : t -> t -> bool
+(** [equal p1 p2] is [true] iff [p1] and [p2] have the same indices. *)
+
+val compare : t -> t -> int
+(** [compare p1 p2] is a total order on pointers, comparing indices
+    lexicographically. *)
+
+(** {2:jsont_path Conversion with Jsont.Path} *)
+
+val of_path : Jsont.Path.t -> t
+(** [of_path p] converts a {!Jsont.Path.t} to a JSON Pointer. *)
+
+val to_path : t -> Jsont.Path.t option
+(** [to_path p] converts to a {!Jsont.Path.t}.
+    Returns [None] if [p] contains an {!Index.End} index. *)
+
+val to_path_exn : t -> Jsont.Path.t
+(** [to_path_exn p] is like {!to_path} but raises {!Jsont.Error}
+    if conversion fails. *)
+
+(** {1 Evaluation}
+
+    These functions evaluate a JSON Pointer against a {!Jsont.json} value
+    to retrieve the referenced value. *)
+
+val get : t -> Jsont.json -> Jsont.json
+(** [get p json] retrieves the value at pointer [p] in [json].
+
+    @raise Jsont.Error if:
+    - The pointer references a nonexistent object member
+    - The pointer references an out-of-bounds array index
+    - The pointer contains {!Index.End} (since [-] always refers
+      to a nonexistent element)
+    - An index type doesn't match the JSON value (e.g., {!Index.Nth}
+      on an object) *)
+
+val get_result : t -> Jsont.json -> (Jsont.json, Jsont.Error.t) result
+(** [get_result p json] is like {!get} but returns a result. *)
+
+val find : t -> Jsont.json -> Jsont.json option
+(** [find p json] is like {!get} but returns [None] instead of
+    raising when the pointer doesn't resolve to a value. *)
+
+(** {1 Mutation}
+
+    These functions modify a {!Jsont.json} value at a location specified
+    by a JSON Pointer. They are designed to support
+    {{:https://www.rfc-editor.org/rfc/rfc6902}RFC 6902 JSON Patch}
+    operations.
+
+    All mutation functions return a new JSON value with the modification
+    applied; they do not mutate the input. *)
+
+val set : t -> Jsont.json -> value:Jsont.json -> Jsont.json
+(** [set p json ~value] replaces the value at pointer [p] with [value].
+
+    For {!Index.End} on arrays, appends [value] to the end of the array.
+
+    @raise Jsont.Error if the pointer doesn't resolve to an existing
+    location (except for {!Index.End} on arrays). *)
+
+val add : t -> Jsont.json -> value:Jsont.json -> Jsont.json
+(** [add p json ~value] adds [value] at the location specified by [p].
+
+    The behavior depends on the target:
+    {ul
+    {- For objects: If the member exists, it is replaced. If it doesn't
+       exist, a new member is added.}
+    {- For arrays with {!Index.Nth}: Inserts [value] {e before} the
+       specified index, shifting subsequent elements. The index must be
+       valid (0 to length inclusive).}
+    {- For arrays with {!Index.End}: Appends [value] to the array.}}
+
+    @raise Jsont.Error if:
+    - The parent of the target location doesn't exist
+    - An array index is out of bounds (except for {!Index.End})
+    - The parent is not an object or array *)
+
+val remove : t -> Jsont.json -> Jsont.json
+(** [remove p json] removes the value at pointer [p].
+
+    For objects, removes the member. For arrays, removes the element
+    and shifts subsequent elements.
+
+    @raise Jsont.Error if:
+    - [p] is the root (cannot remove the root)
+    - The pointer doesn't resolve to an existing value
+    - The pointer contains {!Index.End} *)
+
+val replace : t -> Jsont.json -> value:Jsont.json -> Jsont.json
+(** [replace p json ~value] replaces the value at pointer [p] with [value].
+
+    Unlike {!add}, this requires the target to exist.
+
+    @raise Jsont.Error if:
+    - The pointer doesn't resolve to an existing value
+    - The pointer contains {!Index.End} *)
+
+val move : from:t -> path:t -> Jsont.json -> Jsont.json
+(** [move ~from ~path json] moves the value from [from] to [path].
+
+    This is equivalent to {!remove} at [from] followed by {!add}
+    at [path] with the removed value.
+
+    @raise Jsont.Error if:
+    - [from] doesn't resolve to a value
+    - [path] is a proper prefix of [from] (would create a cycle)
+    - Either pointer contains {!Index.End} *)
+
+val copy : from:t -> path:t -> Jsont.json -> Jsont.json
+(** [copy ~from ~path json] copies the value from [from] to [path].
+
+    This is equivalent to {!get} at [from] followed by {!add}
+    at [path] with the retrieved value.
+
+    @raise Jsont.Error if:
+    - [from] doesn't resolve to a value
+    - Either pointer contains {!Index.End} *)
+
+val test : t -> Jsont.json -> expected:Jsont.json -> bool
+(** [test p json ~expected] tests if the value at [p] equals [expected].
+
+    Returns [true] if the values are equal according to {!Jsont.Json.equal},
+    [false] otherwise. Also returns [false] (rather than raising) if the
+    pointer doesn't resolve.
+
+    Note: This implements the semantics of the JSON Patch "test" operation. *)
+
+(** {1 Jsont Integration}
+
+    These types and functions integrate JSON Pointers with the {!Jsont}
+    codec system. *)
+
+val jsont : t Jsont.t
+(** [jsont] is a {!Jsont.t} codec for JSON Pointers.
+
+    On decode, parses a JSON string as a JSON Pointer using {!of_string}.
+    On encode, serializes a pointer to a JSON string using {!to_string}. *)
+
+val jsont_uri_fragment : t Jsont.t
+(** [jsont_uri_fragment] is like {!jsont} but uses URI fragment encoding.
+
+    On decode, parses using {!of_uri_fragment}.
+    On encode, serializes using {!to_uri_fragment}. *)
+
+(** {2:query Query combinators}
+
+    These combinators integrate with jsont's query system, allowing
+    JSON Pointers to be used with jsont codecs for typed access. *)
+
+val path : ?absent:'a -> t -> 'a Jsont.t -> 'a Jsont.t
+(** [path p t] decodes the value at pointer [p] using codec [t].
+
+    If [absent] is provided and the pointer doesn't resolve, returns
+    [absent] instead of raising.
+
+    This is similar to {!Jsont.path} but uses JSON Pointer syntax. *)
+
+val set_path : ?allow_absent:bool -> 'a Jsont.t -> t -> 'a -> Jsont.json Jsont.t
+(** [set_path t p v] sets the value at pointer [p] to [v] encoded with [t].
+
+    If [allow_absent] is [true] (default [false]), creates missing
+    intermediate structure as needed.
+
+    This is similar to {!Jsont.set_path} but uses JSON Pointer syntax. *)
+
+val update_path : ?absent:'a -> t -> 'a Jsont.t -> Jsont.json Jsont.t
+(** [update_path p t] recodes the value at pointer [p] with codec [t].
+
+    This is similar to {!Jsont.update_path} but uses JSON Pointer syntax. *)
+
+val delete_path : ?allow_absent:bool -> t -> Jsont.json Jsont.t
+(** [delete_path p] removes the value at pointer [p].
+
+    If [allow_absent] is [true] (default [false]), does nothing if
+    the pointer doesn't resolve instead of raising. *)

test/comprehensive.t

···
+Comprehensive JSON Pointer Tests (from json-pointer-js test suite)
+
+Additional parsing tests:
+  $ ./test_pointer.exe parse "/foo/bar"
+  OK: [Mem:foo, Mem:bar]
+  $ ./test_pointer.exe parse "/foo/-"
+  OK: [Mem:foo, End]
+  $ ./test_pointer.exe parse "/foo/1"
+  OK: [Mem:foo, Nth:1]
+  $ ./test_pointer.exe parse "/foo/~0"
+  OK: [Mem:foo, Mem:~]
+  $ ./test_pointer.exe parse "/foo/~1"
+  OK: [Mem:foo, Mem:/]
+  $ ./test_pointer.exe parse "/foo/~1~0"
+  OK: [Mem:foo, Mem:/~]
+  $ ./test_pointer.exe parse "/foo/~0~1"
+  OK: [Mem:foo, Mem:~/]
+  $ ./test_pointer.exe parse "/foo/~01"
+  OK: [Mem:foo, Mem:~1]
+  $ ./test_pointer.exe parse "/foo/~10"
+  OK: [Mem:foo, Mem:/0]
+
+Parse error tests:
+  $ ./test_pointer.exe parse "foo/bar"
+  ERROR: Invalid JSON Pointer: must be empty or start with '/': foo/bar
+  $ ./test_pointer.exe parse "~foo"
+  ERROR: Invalid JSON Pointer: must be empty or start with '/': ~foo
+  $ ./test_pointer.exe parse "/~a"
+  ERROR: Invalid JSON Pointer: invalid escape sequence ~a
+  $ ./test_pointer.exe parse "~1/foo"
+  ERROR: Invalid JSON Pointer: must be empty or start with '/': ~1/foo
+
+Get value tests:
+  $ ./test_pointer.exe eval data/rfc6901_example.json "/a~1b"
+  OK: 1
+  $ ./test_pointer.exe eval data/rfc6901_example.json "/c%d"
+  OK: 2
+  $ ./test_pointer.exe eval data/rfc6901_example.json "/e^f"
+  OK: 3
+  $ ./test_pointer.exe eval data/rfc6901_example.json "/g|h"
+  OK: 4
+  $ ./test_pointer.exe eval data/rfc6901_example.json '/i\j'
+  OK: 5
+  $ ./test_pointer.exe eval data/rfc6901_example.json '/k"l'
+  OK: 6
+  $ ./test_pointer.exe eval data/rfc6901_example.json "/ "
+  OK: 7
+  $ ./test_pointer.exe eval data/rfc6901_example.json "/m~0n"
+  OK: 8
+  $ ./test_pointer.exe eval data/rfc6901_example.json "/"
+  OK: 0
+
+Set tests (using add for replace/add semantics):
+  $ ./test_pointer.exe add '{"bar":"foo"}' '/bar' '"baz"'
+  {"bar":"baz"}
+  $ ./test_pointer.exe add '{"bar":"foo"}' '/foo' '"baz"'
+  {"bar":"foo","foo":"baz"}
+  $ ./test_pointer.exe add '["foo"]' '/0' '"bar"'
+  ["bar","foo"]
+  $ ./test_pointer.exe add '["foo"]' '/-' '"bar"'
+  ["foo","bar"]
+  $ ./test_pointer.exe add '{"foo":["bar"]}' '/foo/0' '"baz"'
+  {"foo":["baz","bar"]}
+
+Replace tests using special characters:
+  $ ./test_pointer.exe replace '{"a/b":"bar"}' '/a~1b' '"baz"'
+  {"a/b":"baz"}
+  $ ./test_pointer.exe replace '{"c%d":"bar"}' '/c%d' '"baz"'
+  {"c%d":"baz"}
+  $ ./test_pointer.exe replace '{"e^f":"bar"}' '/e^f' '"baz"'
+  {"e^f":"baz"}
+  $ ./test_pointer.exe replace '{"g|h":"bar"}' '/g|h' '"baz"'
+  {"g|h":"baz"}
+  $ ./test_pointer.exe replace '{" ":"bar"}' '/ ' '"baz"'
+  {" ":"baz"}
+  $ ./test_pointer.exe replace '{"m~n":"bar"}' '/m~0n' '"baz"'
+  {"m~n":"baz"}
+  $ ./test_pointer.exe replace '{"":"bar"}' '/' '"baz"'
+  {"":"baz"}
+
+Remove tests:
+  $ ./test_pointer.exe remove '{"foo":"bar","baz":"qux"}' '/foo'
+  {"baz":"qux"}
+  $ ./test_pointer.exe remove '["foo","baz"]' '/1'
+  ["foo"]
+  $ ./test_pointer.exe remove '["foo","baz"]' '/0'
+  ["baz"]
+  $ ./test_pointer.exe remove '{"foo":["bar"]}' '/foo/0'
+  {"foo":[]}
+
+Copy tests:
+  $ ./test_pointer.exe copy '{"foo":"bar"}' '/foo' '/baz'
+  {"foo":"bar","baz":"bar"}
+
+Test operation:
+  $ ./test_pointer.exe test '{"foo":"bar"}' '/foo' '"bar"'
+  true
+  $ ./test_pointer.exe test '{"foo":"bar"}' '/foo' '"baz"'
+  false
+  $ ./test_pointer.exe test '{"foo":["bar","baz"]}' '/foo' '["bar","baz"]'
+  true
+  $ ./test_pointer.exe test '{"foo":"bar"}' '/baz' '"qux"'
+  false
+
+Equality tests (pointers that should be equal after roundtrip):
+  $ ./test_pointer.exe roundtrip "/foo/~0"
+  OK: /foo/~0
+  $ ./test_pointer.exe roundtrip "/foo/~1"
+  OK: /foo/~1
+
+Has/exists tests (from json-pointer-js):
+  $ ./test_pointer.exe has '{"foo":"bar"}' '/foo'
+  true
+  $ ./test_pointer.exe has '{"foo":"bar"}' '/bar'
+  false
+  $ ./test_pointer.exe has '{"foo":{"bar":"baz"}}' '/foo/bar'
+  true
+  $ ./test_pointer.exe has '{"foo":{"bar":"baz"}}' '/foo/qux'
+  false
+  $ ./test_pointer.exe has '["foo","bar"]' '/0'
+  true
+  $ ./test_pointer.exe has '["foo","bar"]' '/1'
+  true
+  $ ./test_pointer.exe has '["foo","bar"]' '/2'
+  false
+  $ ./test_pointer.exe has '{"foo":["bar"]}' '/foo/0'
+  true
+  $ ./test_pointer.exe has '{"foo":["bar"]}' '/foo/1'
+  false
+  $ ./test_pointer.exe has '{}' ''
+  true
+  $ ./test_pointer.exe has '[]' ''
+  true
+  $ ./test_pointer.exe has '{"":0}' '/'
+  true
+  $ ./test_pointer.exe has '{"a/b":1}' '/a~1b'
+  true
+  $ ./test_pointer.exe has '{"m~n":8}' '/m~0n'
+  true
+
+Has with null values:
+  $ ./test_pointer.exe has '{"foo":null}' '/foo'
+  true
+  $ ./test_pointer.exe has 'null' ''
+  true
+
+Has with '-' (end marker - should be false for get, points to nonexistent):
+  $ ./test_pointer.exe has '["foo"]' '/-'
+  false
+  $ ./test_pointer.exe has '[]' '/-'
+  false

test/data/booleans.json

···
+{
+  "true": true,
+  "false": false
+}

test/data/escape.txt

···
+# Token escape/unescape tests
+# Format: unescaped -> escaped
+
+# Basic cases
+foo -> foo
+bar -> bar
+
+# Tilde escaping
+~ -> ~0
+~0 -> ~00
+~1 -> ~01
+
+# Slash escaping
+/ -> ~1
+a/b -> a~1b
+/foo/bar -> ~1foo~1bar
+
+# Combined
+~/ -> ~0~1
+/~ -> ~1~0
+a~b/c -> a~0b~1c
+
+# No escaping needed
+hello world -> hello world
+special!@#$%^&*() -> special!@#$%^&*()

test/data/eval_errors.txt

···
+# Evaluation error tests
+# Format: pointer -> error type
+
+# Nonexistent members
+/nonexistent -> member not found
+/foo/nonexistent -> type mismatch (array, not object)
+
+# Out of bounds array indices
+/foo/2 -> index out of bounds
+/foo/99 -> index out of bounds
+
+# Type mismatches
+/foo/0/bar -> type mismatch (string, not object)
+/ /0 -> type mismatch (number, not array)
+
+# End marker always errors on get
+/foo/- -> end marker not allowed
+/- -> end marker not allowed

test/data/eval_rfc6901.txt

···
+# Evaluation tests against RFC 6901 example document
+# Format: pointer -> expected JSON value
+
+# Root - whole document
+ -> {"foo":["bar","baz"],"":0,"a/b":1,"c%d":2,"e^f":3,"g|h":4,"i\\j":5,"k\"l":6," ":7,"m~n":8}
+
+# RFC 6901 Section 5 examples
+/foo -> ["bar","baz"]
+/foo/0 -> "bar"
+/foo/1 -> "baz"
+/ -> 0
+/a~1b -> 1
+/c%d -> 2
+/e^f -> 3
+/g|h -> 4
+/i\j -> 5
+/k"l -> 6
+/  -> 7
+/m~0n -> 8

test/data/mutations.json

···
+{
+  "add_tests": [
+    {
+      "doc": {"foo": "bar"},
+      "pointer": "/baz",
+      "value": "qux",
+      "expected": {"foo": "bar", "baz": "qux"}
+    },
+    {
+      "doc": {"foo": ["bar", "baz"]},
+      "pointer": "/foo/1",
+      "value": "qux",
+      "expected": {"foo": ["bar", "qux", "baz"]}
+    },
+    {
+      "doc": {"foo": ["bar"]},
+      "pointer": "/foo/-",
+      "value": "qux",
+      "expected": {"foo": ["bar", "qux"]}
+    },
+    {
+      "doc": {"foo": ["bar", "baz"]},
+      "pointer": "/foo/0",
+      "value": "qux",
+      "expected": {"foo": ["qux", "bar", "baz"]}
+    }
+  ],
+  "remove_tests": [
+    {
+      "doc": {"foo": "bar", "baz": "qux"},
+      "pointer": "/baz",
+      "expected": {"foo": "bar"}
+    },
+    {
+      "doc": {"foo": ["bar", "qux", "baz"]},
+      "pointer": "/foo/1",
+      "expected": {"foo": ["bar", "baz"]}
+    }
+  ],
+  "replace_tests": [
+    {
+      "doc": {"foo": "bar"},
+      "pointer": "/foo",
+      "value": "baz",
+      "expected": {"foo": "baz"}
+    },
+    {
+      "doc": {"foo": ["bar", "baz"]},
+      "pointer": "/foo/0",
+      "value": "qux",
+      "expected": {"foo": ["qux", "baz"]}
+    }
+  ],
+  "move_tests": [
+    {
+      "doc": {"foo": {"bar": "baz"}, "qux": {"corge": "grault"}},
+      "from": "/foo/bar",
+      "path": "/qux/thud",
+      "expected": {"foo": {}, "qux": {"corge": "grault", "thud": "baz"}}
+    },
+    {
+      "doc": {"foo": ["all", "grass", "cows", "eat"]},
+      "from": "/foo/1",
+      "path": "/foo/3",
+      "expected": {"foo": ["all", "cows", "eat", "grass"]}
+    }
+  ],
+  "copy_tests": [
+    {
+      "doc": {"foo": {"bar": "baz"}},
+      "from": "/foo/bar",
+      "path": "/foo/qux",
+      "expected": {"foo": {"bar": "baz", "qux": "baz"}}
+    }
+  ],
+  "test_tests": [
+    {
+      "doc": {"foo": "bar"},
+      "pointer": "/foo",
+      "value": "bar",
+      "expected": true
+    },
+    {
+      "doc": {"foo": "bar"},
+      "pointer": "/foo",
+      "value": "baz",
+      "expected": false
+    },
+    {
+      "doc": {"foo": ["bar", "baz"]},
+      "pointer": "/foo",
+      "value": ["bar", "baz"],
+      "expected": true
+    }
+  ]
+}

test/data/nested.json

···
+{
+  "a": {
+    "b": {
+      "c": {
+        "d": "deep value"
+      }
+    }
+  },
+  "arr": [[1, 2], [3, 4]],
+  "mixed": { "list": [{"x": 1}, {"y": 2}] }
+}

test/data/nulls.json

···
+{
+  "null": null,
+  "nested": { "null": null }
+}

test/data/numeric_keys.json

···
+{
+  "0": "zero",
+  "1": "one",
+  "2": "two"
+}

test/data/parse_invalid.txt

···
+# Invalid JSON Pointer parsing tests
+# Format: pointer -> error description
+
+# Must start with / if non-empty
+foo -> must start with /
+a/b -> must start with /
+0 -> must start with /
+- -> must start with /
+
+# Invalid escape sequences
+/~ -> incomplete escape
+/~2 -> invalid escape ~2
+/~a -> invalid escape ~a
+/foo~bar -> invalid escape ~b
+/~~ -> invalid escape ~~
+
+# Leading zeros in array indices (RFC 6901 Section 4)
+/00 -> leading zero
+/01 -> leading zero
+/007 -> leading zero
+
+# Negative indices not allowed
+/-1 -> not a valid index
+/-42 -> not a valid index

test/data/parse_valid.txt

···
+# Valid JSON Pointer parsing tests
+# Format: pointer -> indices (Mem:name, Nth:n, End)
+
+# Root pointer (empty string)
+ -> []
+
+# RFC 6901 Section 5 examples
+/foo -> [Mem:foo]
+/foo/0 -> [Mem:foo, Nth:0]
+/ -> [Mem:]
+/a~1b -> [Mem:a/b]
+/c%d -> [Mem:c%d]
+/e^f -> [Mem:e^f]
+/g|h -> [Mem:g|h]
+/i\j -> [Mem:i\j]
+/k"l -> [Mem:k"l]
+/  -> [Mem: ]
+/m~0n -> [Mem:m~n]
+
+# Array indices
+/0 -> [Nth:0]
+/1 -> [Nth:1]
+/10 -> [Nth:10]
+/123 -> [Nth:123]
+/999999 -> [Nth:999999]
+
+# End-of-array marker
+/- -> [End]
+/foo/- -> [Mem:foo, End]
+/arr/0/- -> [Mem:arr, Nth:0, End]
+
+# Multiple levels
+/a/b/c -> [Mem:a, Mem:b, Mem:c]
+/0/1/2 -> [Nth:0, Nth:1, Nth:2]
+/foo/0/bar/1 -> [Mem:foo, Nth:0, Mem:bar, Nth:1]
+
+# Escape sequences
+/~0 -> [Mem:~]
+/~1 -> [Mem:/]
+/~0~1 -> [Mem:~/]
+/~1~0 -> [Mem:/~]
+/~01 -> [Mem:~1]
+/a~0b~1c -> [Mem:a~b/c]
+
+# Empty member names
+// -> [Mem:, Mem:]
+/// -> [Mem:, Mem:, Mem:]
+/foo//bar -> [Mem:foo, Mem:, Mem:bar]
+
+# Special characters (not needing escaping)
+/hello world -> [Mem:hello world]
+/with spaces -> [Mem:with spaces]
+/unicode-\u00e9 -> [Mem:unicode-\u00e9]

test/data/rfc6901_example.json

···
+{
+  "foo": ["bar", "baz"],
+  "": 0,
+  "a/b": 1,
+  "c%d": 2,
+  "e^f": 3,
+  "g|h": 4,
+  "i\\j": 5,
+  "k\"l": 6,
+  " ": 7,
+  "m~n": 8
+}

test/data/unicode.json

···
+{
+  "café": "coffee",
+  "日本語": "japanese",
+  "🎉": "party"
+}

test/data/uri_fragment.txt

···
+# URI Fragment encoding/decoding tests
+# Format: uri_fragment <-> pointer_string
+
+# RFC 6901 Section 6 examples (without leading #)
+ <->
+/foo <-> /foo
+/foo/0 <-> /foo/0
+/ <-> /
+/a~1b <-> /a~1b
+/c%25d <-> /c%d
+/e%5Ef <-> /e^f
+/g%7Ch <-> /g|h
+/i%5Cj <-> /i\j
+/k%22l <-> /k"l
+/%20 <-> /
+/m~0n <-> /m~0n
+
+# Additional percent-encoding cases
+/hello%20world <-> /hello world
+/%2F <-> //
+/%7E <-> /~

test/dune

···
+(executable
+ (name test_pointer)
+ (libraries jsont jsont_pointer yojson))
+
+(cram
+ (deps test_pointer.exe
+       data/rfc6901_example.json
+       data/mutations.json
+       data/nested.json
+       data/nulls.json
+       data/booleans.json
+       data/unicode.json
+       data/numeric_keys.json))

test/escape.t

···
+Token Escaping Tests
+
+Escape tilde:
+  $ ./test_pointer.exe escape "~"
+  ~0
+  $ ./test_pointer.exe escape "~0"
+  ~00
+  $ ./test_pointer.exe escape "~1"
+  ~01
+
+Escape slash:
+  $ ./test_pointer.exe escape "/"
+  ~1
+  $ ./test_pointer.exe escape "a/b"
+  a~1b
+  $ ./test_pointer.exe escape "/foo/bar"
+  ~1foo~1bar
+
+Combined:
+  $ ./test_pointer.exe escape "~/"
+  ~0~1
+  $ ./test_pointer.exe escape "/~"
+  ~1~0
+  $ ./test_pointer.exe escape "a~b/c"
+  a~0b~1c
+
+No escaping needed:
+  $ ./test_pointer.exe escape "foo"
+  foo
+  $ ./test_pointer.exe escape "hello world"
+  hello world
+
+Unescape:
+  $ ./test_pointer.exe unescape "~0"
+  OK: ~
+  $ ./test_pointer.exe unescape "~1"
+  OK: /
+  $ ./test_pointer.exe unescape "~0~1"
+  OK: ~/
+  $ ./test_pointer.exe unescape "~1~0"
+  OK: /~
+  $ ./test_pointer.exe unescape "a~0b~1c"
+  OK: a~b/c
+  $ ./test_pointer.exe unescape "foo"
+  OK: foo
+
+Unescape errors:
+  $ ./test_pointer.exe unescape "~"
+  ERROR: Invalid JSON Pointer: incomplete escape sequence at end
+  $ ./test_pointer.exe unescape "~2"
+  ERROR: Invalid JSON Pointer: invalid escape sequence ~2
+  $ ./test_pointer.exe unescape "foo~"
+  ERROR: Invalid JSON Pointer: incomplete escape sequence at end

test/eval.t

···
+JSON Pointer Evaluation Tests (RFC 6901 Section 5)
+
+Using the RFC 6901 example document:
+  $ cat data/rfc6901_example.json
+  {
+    "foo": ["bar", "baz"],
+    "": 0,
+    "a/b": 1,
+    "c%d": 2,
+    "e^f": 3,
+    "g|h": 4,
+    "i\\j": 5,
+    "k\"l": 6,
+    " ": 7,
+    "m~n": 8
+  }
+
+Root pointer returns whole document:
+  $ ./test_pointer.exe eval data/rfc6901_example.json ""
+  OK: {"foo":["bar","baz"],"":0,"a/b":1,"c%d":2,"e^f":3,"g|h":4,"i\\j":5,"k\"l":6," ":7,"m~n":8}
+
+RFC 6901 examples:
+  $ ./test_pointer.exe eval data/rfc6901_example.json "/foo"
+  OK: ["bar","baz"]
+  $ ./test_pointer.exe eval data/rfc6901_example.json "/foo/0"
+  OK: "bar"
+  $ ./test_pointer.exe eval data/rfc6901_example.json "/foo/1"
+  OK: "baz"
+  $ ./test_pointer.exe eval data/rfc6901_example.json "/"
+  OK: 0
+  $ ./test_pointer.exe eval data/rfc6901_example.json "/a~1b"
+  OK: 1
+  $ ./test_pointer.exe eval data/rfc6901_example.json "/c%d"
+  OK: 2
+  $ ./test_pointer.exe eval data/rfc6901_example.json "/e^f"
+  OK: 3
+  $ ./test_pointer.exe eval data/rfc6901_example.json "/g|h"
+  OK: 4
+  $ ./test_pointer.exe eval data/rfc6901_example.json '/i\j'
+  OK: 5
+  $ ./test_pointer.exe eval data/rfc6901_example.json '/k"l'
+  OK: 6
+  $ ./test_pointer.exe eval data/rfc6901_example.json "/ "
+  OK: 7
+  $ ./test_pointer.exe eval data/rfc6901_example.json "/m~0n"
+  OK: 8
+
+Error: nonexistent member:
+  $ ./test_pointer.exe eval data/rfc6901_example.json "/nonexistent"
+  ERROR: JSON Pointer: member 'nonexistent' not found
+
+Error: index out of bounds:
+  $ ./test_pointer.exe eval data/rfc6901_example.json "/foo/2"
+  ERROR: JSON Pointer: index 2 out of bounds (array has 2 elements)
+  $ ./test_pointer.exe eval data/rfc6901_example.json "/foo/99"
+  ERROR: JSON Pointer: index 99 out of bounds (array has 2 elements)
+
+Error: invalid array index (not a valid integer):
+  $ ./test_pointer.exe eval data/rfc6901_example.json "/foo/bar"
+  ERROR: JSON Pointer: invalid array index 'bar'
+
+Error: end marker not allowed in get:
+  $ ./test_pointer.exe eval data/rfc6901_example.json "/foo/-"
+  ERROR: JSON Pointer: '-' (end marker) refers to nonexistent array element
+
+Error: navigating through primitive (string):
+  $ ./test_pointer.exe eval data/rfc6901_example.json "/foo/0/0"
+  ERROR: JSON Pointer: cannot index into string with '0'
+  $ ./test_pointer.exe eval data/rfc6901_example.json "/foo/0/bar"
+  ERROR: JSON Pointer: cannot index into string with 'bar'
+
+Nested evaluation with deep nesting:
+  $ cat data/nested.json
+  {
+    "a": {
+      "b": {
+        "c": {
+          "d": "deep value"
+        }
+      }
+    },
+    "arr": [[1, 2], [3, 4]],
+    "mixed": { "list": [{"x": 1}, {"y": 2}] }
+  }
+  $ ./test_pointer.exe eval data/nested.json "/a/b/c/d"
+  OK: "deep value"
+  $ ./test_pointer.exe eval data/nested.json "/arr/0/1"
+  OK: 2
+  $ ./test_pointer.exe eval data/nested.json "/arr/1/0"
+  OK: 3
+  $ ./test_pointer.exe eval data/nested.json "/mixed/list/0/x"
+  OK: 1
+  $ ./test_pointer.exe eval data/nested.json "/mixed/list/1/y"
+  OK: 2
+
+Null value handling:
+  $ cat data/nulls.json
+  {
+    "null": null,
+    "nested": { "null": null }
+  }
+  $ ./test_pointer.exe eval data/nulls.json "/null"
+  OK: null
+  $ ./test_pointer.exe eval data/nulls.json "/nested/null"
+  OK: null
+
+Boolean values:
+  $ cat data/booleans.json
+  {
+    "true": true,
+    "false": false
+  }
+  $ ./test_pointer.exe eval data/booleans.json "/true"
+  OK: true
+  $ ./test_pointer.exe eval data/booleans.json "/false"
+  OK: false
+
+Empty key access:
+  $ ./test_pointer.exe eval data/rfc6901_example.json "/"
+  OK: 0
+
+Unicode member access:
+  $ cat data/unicode.json
+  {
+    "café": "coffee",
+    "日本語": "japanese",
+    "🎉": "party"
+  }
+  $ ./test_pointer.exe eval data/unicode.json "/café"
+  OK: "coffee"
+  $ ./test_pointer.exe eval data/unicode.json "/日本語"
+  OK: "japanese"
+  $ ./test_pointer.exe eval data/unicode.json "/🎉"
+  OK: "party"

test/mutations.t

···
+JSON Pointer Mutation Tests (RFC 6902 JSON Patch operations)
+
+Add to object:
+  $ ./test_pointer.exe add '{"foo":"bar"}' '/baz' '"qux"'
+  {"foo":"bar","baz":"qux"}
+
+Add to array (insert before):
+  $ ./test_pointer.exe add '{"foo":["bar","baz"]}' '/foo/1' '"qux"'
+  {"foo":["bar","qux","baz"]}
+
+Add to array at beginning:
+  $ ./test_pointer.exe add '{"foo":["bar","baz"]}' '/foo/0' '"qux"'
+  {"foo":["qux","bar","baz"]}
+
+Add to array at end using -:
+  $ ./test_pointer.exe add '{"foo":["bar"]}' '/foo/-' '"qux"'
+  {"foo":["bar","qux"]}
+
+Add replaces existing member:
+  $ ./test_pointer.exe add '{"foo":"bar"}' '/foo' '"baz"'
+  {"foo":"baz"}
+
+Remove from object:
+  $ ./test_pointer.exe remove '{"foo":"bar","baz":"qux"}' '/baz'
+  {"foo":"bar"}
+
+Remove from array:
+  $ ./test_pointer.exe remove '{"foo":["bar","qux","baz"]}' '/foo/1'
+  {"foo":["bar","baz"]}
+
+Remove first element:
+  $ ./test_pointer.exe remove '{"foo":["bar","baz"]}' '/foo/0'
+  {"foo":["baz"]}
+
+Replace in object:
+  $ ./test_pointer.exe replace '{"foo":"bar"}' '/foo' '"baz"'
+  {"foo":"baz"}
+
+Replace in array:
+  $ ./test_pointer.exe replace '{"foo":["bar","baz"]}' '/foo/0' '"qux"'
+  {"foo":["qux","baz"]}
+
+Move within object:
+  $ ./test_pointer.exe move '{"foo":{"bar":"baz"},"qux":{}}' '/foo/bar' '/qux/thud'
+  {"foo":{},"qux":{"thud":"baz"}}
+
+Move within array:
+  $ ./test_pointer.exe move '{"foo":["a","b","c","d"]}' '/foo/1' '/foo/3'
+  {"foo":["a","c","d","b"]}
+
+Copy within object:
+  $ ./test_pointer.exe copy '{"foo":{"bar":"baz"}}' '/foo/bar' '/foo/qux'
+  {"foo":{"bar":"baz","qux":"baz"}}
+
+Copy to new location:
+  $ ./test_pointer.exe copy '{"foo":"bar"}' '/foo' '/baz'
+  {"foo":"bar","baz":"bar"}
+
+Test equality (true):
+  $ ./test_pointer.exe test '{"foo":"bar"}' '/foo' '"bar"'
+  true
+
+Test equality (false):
+  $ ./test_pointer.exe test '{"foo":"bar"}' '/foo' '"baz"'
+  false
+
+Test array equality:
+  $ ./test_pointer.exe test '{"foo":["bar","baz"]}' '/foo' '["bar","baz"]'
+  true
+
+Test nonexistent path returns false:
+  $ ./test_pointer.exe test '{"foo":"bar"}' '/baz' '"qux"'
+  false
+
+Error: remove root:
+  $ ./test_pointer.exe remove '{"foo":"bar"}' ''
+  ERROR: JSON Pointer: cannot remove root document
+
+Error: remove nonexistent:
+  $ ./test_pointer.exe remove '{"foo":"bar"}' '/baz'
+  ERROR: JSON Pointer: member 'baz' not found for remove
+
+Error: replace nonexistent:
+  $ ./test_pointer.exe replace '{"foo":"bar"}' '/baz' '"qux"'
+  ERROR: JSON Pointer: member 'baz' not found
+
+Error: add to out of bounds index:
+  $ ./test_pointer.exe add '{"foo":["bar"]}' '/foo/5' '"qux"'
+  ERROR: JSON Pointer: index 5 out of bounds for add (array has 1 elements)
+
+Add nested path (parent must exist):
+  $ ./test_pointer.exe add '{"foo":{}}' '/foo/bar' '"baz"'
+  {"foo":{"bar":"baz"}}
+
+Add to root-level array:
+  $ ./test_pointer.exe add '["a","b"]' '/1' '"x"'
+  ["a","x","b"]
+  $ ./test_pointer.exe add '["a","b"]' '/-' '"c"'
+  ["a","b","c"]
+  $ ./test_pointer.exe add '["a","b"]' '/0' '"x"'
+  ["x","a","b"]
+
+Replace root document:
+  $ ./test_pointer.exe replace '{"foo":"bar"}' '' '"new root"'
+  "new root"
+  $ ./test_pointer.exe replace '["a","b"]' '' '{"replaced":true}'
+  {"replaced":true}
+
+Move from array to object:
+  $ ./test_pointer.exe move '{"arr":["x","y"],"obj":{}}' '/arr/0' '/obj/item'
+  {"arr":["y"],"obj":{"item":"x"}}
+
+Copy array element:
+  $ ./test_pointer.exe copy '{"arr":["x","y"]}' '/arr/0' '/arr/-'
+  {"arr":["x","y","x"]}
+
+Test with numeric string member names (RFC 6901: context determines interpretation):
+  $ ./test_pointer.exe add '{"0":"zero","1":"one"}' '/2' '"two"'
+  {"0":"zero","1":"one","2":"two"}
+  $ ./test_pointer.exe eval data/numeric_keys.json "/0"
+  OK: "zero"
+
+Special characters in member names:
+  $ ./test_pointer.exe add '{}' '/a~1b' '"slash"'
+  {"a/b":"slash"}
+  $ ./test_pointer.exe add '{}' '/m~0n' '"tilde"'
+  {"m~n":"tilde"}
+  $ ./test_pointer.exe replace '{"a/b":"old"}' '/a~1b' '"new"'
+  {"a/b":"new"}
+
+Deep nested mutations:
+  $ ./test_pointer.exe add '{"a":{"b":{"c":{}}}}' '/a/b/c/d' '"deep"'
+  {"a":{"b":{"c":{"d":"deep"}}}}
+  $ ./test_pointer.exe remove '{"a":{"b":{"c":{"d":"deep"}}}}' '/a/b/c/d'
+  {"a":{"b":{"c":{}}}}
+
+Error: remove from nonexistent array index:
+  $ ./test_pointer.exe remove '{"foo":["bar"]}' '/foo/5'
+  ERROR: JSON Pointer: index 5 out of bounds for remove
+
+Error: move to descendant of source (path doesn't exist after removal):
+  $ ./test_pointer.exe move '{"a":{"b":"c"}}' '/a' '/a/b'
+  ERROR: JSON Pointer: member 'a' not found
+
+Copy to same location (no-op essentially):
+  $ ./test_pointer.exe copy '{"foo":"bar"}' '/foo' '/foo'
+  {"foo":"bar"}
+
+Test value equality with different types:
+  $ ./test_pointer.exe test '{"n":1}' '/n' '1'
+  true
+  $ ./test_pointer.exe test '{"n":1.0}' '/n' '1'
+  true
+  $ ./test_pointer.exe test '{"n":"1"}' '/n' '1'
+  false
+  $ ./test_pointer.exe test '{"b":true}' '/b' 'true'
+  true
+  $ ./test_pointer.exe test '{"b":false}' '/b' 'false'
+  true
+  $ ./test_pointer.exe test '{"n":null}' '/n' 'null'
+  true
+
+Test deep equality:
+  $ ./test_pointer.exe test '{"obj":{"a":1,"b":2}}' '/obj' '{"a":1,"b":2}'
+  true
+  $ ./test_pointer.exe test '{"arr":[1,2,3]}' '/arr' '[1,2,3]'
+  true

test/parse.t

···
+JSON Pointer Parsing Tests (RFC 6901)
+
+Root pointer (empty string):
+  $ ./test_pointer.exe parse ""
+  OK: []
+
+RFC 6901 Section 5 examples:
+  $ ./test_pointer.exe parse "/foo"
+  OK: [Mem:foo]
+  $ ./test_pointer.exe parse "/foo/0"
+  OK: [Mem:foo, Nth:0]
+  $ ./test_pointer.exe parse "/"
+  OK: [Mem:]
+  $ ./test_pointer.exe parse "/a~1b"
+  OK: [Mem:a/b]
+  $ ./test_pointer.exe parse "/c%d"
+  OK: [Mem:c%d]
+  $ ./test_pointer.exe parse "/e^f"
+  OK: [Mem:e^f]
+  $ ./test_pointer.exe parse "/g|h"
+  OK: [Mem:g|h]
+  $ ./test_pointer.exe parse '/i\j'
+  OK: [Mem:i\j]
+  $ ./test_pointer.exe parse '/k"l'
+  OK: [Mem:k"l]
+  $ ./test_pointer.exe parse "/ "
+  OK: [Mem: ]
+  $ ./test_pointer.exe parse "/m~0n"
+  OK: [Mem:m~n]
+
+Array indices:
+  $ ./test_pointer.exe parse "/0"
+  OK: [Nth:0]
+  $ ./test_pointer.exe parse "/1"
+  OK: [Nth:1]
+  $ ./test_pointer.exe parse "/10"
+  OK: [Nth:10]
+  $ ./test_pointer.exe parse "/123"
+  OK: [Nth:123]
+
+End-of-array marker:
+  $ ./test_pointer.exe parse "/-"
+  OK: [End]
+  $ ./test_pointer.exe parse "/foo/-"
+  OK: [Mem:foo, End]
+
+Multiple levels:
+  $ ./test_pointer.exe parse "/a/b/c"
+  OK: [Mem:a, Mem:b, Mem:c]
+  $ ./test_pointer.exe parse "/0/1/2"
+  OK: [Nth:0, Nth:1, Nth:2]
+  $ ./test_pointer.exe parse "/foo/0/bar/1"
+  OK: [Mem:foo, Nth:0, Mem:bar, Nth:1]
+
+Escape sequences:
+  $ ./test_pointer.exe parse "/~0"
+  OK: [Mem:~]
+  $ ./test_pointer.exe parse "/~1"
+  OK: [Mem:/]
+  $ ./test_pointer.exe parse "/~0~1"
+  OK: [Mem:~/]
+  $ ./test_pointer.exe parse "/~1~0"
+  OK: [Mem:/~]
+  $ ./test_pointer.exe parse "/~01"
+  OK: [Mem:~1]
+
+Empty member names:
+  $ ./test_pointer.exe parse "//"
+  OK: [Mem:, Mem:]
+  $ ./test_pointer.exe parse "///"
+  OK: [Mem:, Mem:, Mem:]
+
+Invalid: must start with /
+  $ ./test_pointer.exe parse "foo"
+  ERROR: Invalid JSON Pointer: must be empty or start with '/': foo
+  $ ./test_pointer.exe parse "a/b"
+  ERROR: Invalid JSON Pointer: must be empty or start with '/': a/b
+
+Invalid: incomplete escape
+  $ ./test_pointer.exe parse "/~"
+  ERROR: Invalid JSON Pointer: incomplete escape sequence at end
+  $ ./test_pointer.exe parse "/foo~"
+  ERROR: Invalid JSON Pointer: incomplete escape sequence at end
+
+Invalid: bad escape sequence
+  $ ./test_pointer.exe parse "/~2"
+  ERROR: Invalid JSON Pointer: invalid escape sequence ~2
+  $ ./test_pointer.exe parse "/~a"
+  ERROR: Invalid JSON Pointer: invalid escape sequence ~a
+
+Leading zeros - valid as tokens, become member names (invalid as array indices at eval time):
+  $ ./test_pointer.exe parse "/00"
+  OK: [Mem:00]
+  $ ./test_pointer.exe parse "/01"
+  OK: [Mem:01]
+  $ ./test_pointer.exe parse "/007"
+  OK: [Mem:007]
+
+RFC 6901 Section 4: ~01 decodes to ~1, not / (order matters):
+  $ ./test_pointer.exe parse "/~01"
+  OK: [Mem:~1]
+  $ ./test_pointer.exe parse "/~10"
+  OK: [Mem:/0]
+
+Unicode characters (RFC 6901 specifies JSON Pointer is Unicode):
+  $ ./test_pointer.exe parse "/café"
+  OK: [Mem:café]
+  $ ./test_pointer.exe parse "/日本語"
+  OK: [Mem:日本語]
+  $ ./test_pointer.exe parse "/emoji🎉"
+  OK: [Mem:emoji🎉]
+
+Numeric member names (should be parsed as indices when valid):
+  $ ./test_pointer.exe parse "/0"
+  OK: [Nth:0]
+  $ ./test_pointer.exe parse "/-1"
+  OK: [Mem:-1]
+  $ ./test_pointer.exe parse "/+1"
+  OK: [Mem:+1]
+
+Very deep paths:
+  $ ./test_pointer.exe parse "/a/b/c/d/e/f/g/h/i/j"
+  OK: [Mem:a, Mem:b, Mem:c, Mem:d, Mem:e, Mem:f, Mem:g, Mem:h, Mem:i, Mem:j]
+
+Complex escape sequences:
+  $ ./test_pointer.exe parse "/~0~0"
+  OK: [Mem:~~]
+  $ ./test_pointer.exe parse "/~1~1"
+  OK: [Mem://]
+  $ ./test_pointer.exe parse "/a~0b~1c~0d~1e"
+  OK: [Mem:a~b/c~d/e]
+
+Invalid: tilde at end of path:
+  $ ./test_pointer.exe parse "/foo/bar~"
+  ERROR: Invalid JSON Pointer: incomplete escape sequence at end

test/test_pointer.ml

···
+(* Test runner for jsont_pointer *)
+
+let read_file path =
+  let ic = open_in path in
+  let n = in_channel_length ic in
+  let s = really_input_string ic n in
+  close_in ic;
+  s
+
+(* Convert Yojson.Safe.t to Jsont.json *)
+let rec yojson_to_jsont (y : Yojson.Safe.t) : Jsont.json =
+  match y with
+  | `Null -> Jsont.Json.null ()
+  | `Bool b -> Jsont.Json.bool b
+  | `Int i -> Jsont.Json.number (float_of_int i)
+  | `Float f -> Jsont.Json.number f
+  | `String s -> Jsont.Json.string s
+  | `List l -> Jsont.Json.list (List.map yojson_to_jsont l)
+  | `Assoc pairs ->
+    let members = List.map (fun (k, v) ->
+      Jsont.Json.mem (Jsont.Json.name k) (yojson_to_jsont v)
+    ) pairs in
+    Jsont.Json.object' members
+  | `Intlit s -> Jsont.Json.number (float_of_string s)
+
+(* Convert Jsont.json to Yojson.Safe.t for output *)
+let rec jsont_to_yojson (j : Jsont.json) : Yojson.Safe.t =
+  match j with
+  | Jsont.Null _ -> `Null
+  | Jsont.Bool (b, _) -> `Bool b
+  | Jsont.Number (f, _) ->
+    if Float.is_integer f && Float.abs f < 2e15 then
+      `Int (int_of_float f)
+    else
+      `Float f
+  | Jsont.String (s, _) -> `String s
+  | Jsont.Array (l, _) -> `List (List.map jsont_to_yojson l)
+  | Jsont.Object (members, _) ->
+    `Assoc (List.map (fun ((name, _), v) ->
+      (name, jsont_to_yojson v)
+    ) members)
+
+let parse_json s =
+  yojson_to_jsont (Yojson.Safe.from_string s)
+
+let json_to_string json =
+  Yojson.Safe.to_string (jsont_to_yojson json)
+
+(* Test: parse pointer and print indices *)
+let test_parse pointer_str =
+  try
+    let p = Jsont_pointer.of_string pointer_str in
+    let indices = Jsont_pointer.indices p in
+    let index_strs = List.map (fun idx ->
+      match idx with
+      | Jsont_pointer.Index.Mem s -> Printf.sprintf "Mem:%s" s
+      | Jsont_pointer.Index.Nth n -> Printf.sprintf "Nth:%d" n
+      | Jsont_pointer.Index.End -> "End"
+    ) indices in
+    Printf.printf "OK: [%s]\n" (String.concat ", " index_strs)
+  with Jsont.Error e ->
+    Printf.printf "ERROR: %s\n" (Jsont.Error.to_string e)
+
+(* Test: roundtrip pointer string *)
+let test_roundtrip pointer_str =
+  try
+    let p = Jsont_pointer.of_string pointer_str in
+    let s = Jsont_pointer.to_string p in
+    if s = pointer_str then
+      Printf.printf "OK: %s\n" s
+    else
+      Printf.printf "MISMATCH: input=%s output=%s\n" pointer_str s
+  with Jsont.Error e ->
+    Printf.printf "ERROR: %s\n" (Jsont.Error.to_string e)
+
+(* Test: evaluate pointer against JSON *)
+let test_eval json_path pointer_str =
+  try
+    let json = parse_json (read_file json_path) in
+    let p = Jsont_pointer.of_string pointer_str in
+    let result = Jsont_pointer.get p json in
+    Printf.printf "OK: %s\n" (json_to_string result)
+  with
+  | Jsont.Error e ->
+    Printf.printf "ERROR: %s\n" (Jsont.Error.to_string e)
+  | Failure e ->
+    Printf.printf "FAIL: %s\n" e
+
+(* Test: escape token *)
+let test_escape token =
+  let escaped = Jsont_pointer.Token.escape token in
+  Printf.printf "%s\n" escaped
+
+(* Test: unescape token *)
+let test_unescape token =
+  try
+    let unescaped = Jsont_pointer.Token.unescape token in
+    Printf.printf "OK: %s\n" unescaped
+  with Jsont.Error e ->
+    Printf.printf "ERROR: %s\n" (Jsont.Error.to_string e)
+
+(* Test: URI fragment roundtrip *)
+let test_uri_fragment pointer_str =
+  try
+    let p = Jsont_pointer.of_string pointer_str in
+    let frag = Jsont_pointer.to_uri_fragment p in
+    let p2 = Jsont_pointer.of_uri_fragment frag in
+    let s2 = Jsont_pointer.to_string p2 in
+    if s2 = pointer_str then
+      Printf.printf "OK: %s -> %s\n" pointer_str frag
+    else
+      Printf.printf "MISMATCH: %s -> %s -> %s\n" pointer_str frag s2
+  with Jsont.Error e ->
+    Printf.printf "ERROR: %s\n" (Jsont.Error.to_string e)
+
+(* Test: add operation *)
+let test_add json_str pointer_str value_str =
+  try
+    let json = parse_json json_str in
+    let p = Jsont_pointer.of_string pointer_str in
+    let value = parse_json value_str in
+    let result = Jsont_pointer.add p json ~value in
+    Printf.printf "%s\n" (json_to_string result)
+  with Jsont.Error e ->
+    Printf.printf "ERROR: %s\n" (Jsont.Error.to_string e)
+
+(* Test: remove operation *)
+let test_remove json_str pointer_str =
+  try
+    let json = parse_json json_str in
+    let p = Jsont_pointer.of_string pointer_str in
+    let result = Jsont_pointer.remove p json in
+    Printf.printf "%s\n" (json_to_string result)
+  with Jsont.Error e ->
+    Printf.printf "ERROR: %s\n" (Jsont.Error.to_string e)
+
+(* Test: replace operation *)
+let test_replace json_str pointer_str value_str =
+  try
+    let json = parse_json json_str in
+    let p = Jsont_pointer.of_string pointer_str in
+    let value = parse_json value_str in
+    let result = Jsont_pointer.replace p json ~value in
+    Printf.printf "%s\n" (json_to_string result)
+  with Jsont.Error e ->
+    Printf.printf "ERROR: %s\n" (Jsont.Error.to_string e)
+
+(* Test: move operation *)
+let test_move json_str from_str path_str =
+  try
+    let json = parse_json json_str in
+    let from = Jsont_pointer.of_string from_str in
+    let path = Jsont_pointer.of_string path_str in
+    let result = Jsont_pointer.move ~from ~path json in
+    Printf.printf "%s\n" (json_to_string result)
+  with Jsont.Error e ->
+    Printf.printf "ERROR: %s\n" (Jsont.Error.to_string e)
+
+(* Test: copy operation *)
+let test_copy json_str from_str path_str =
+  try
+    let json = parse_json json_str in
+    let from = Jsont_pointer.of_string from_str in
+    let path = Jsont_pointer.of_string path_str in
+    let result = Jsont_pointer.copy ~from ~path json in
+    Printf.printf "%s\n" (json_to_string result)
+  with Jsont.Error e ->
+    Printf.printf "ERROR: %s\n" (Jsont.Error.to_string e)
+
+(* Test: test operation *)
+let test_test json_str pointer_str expected_str =
+  try
+    let json = parse_json json_str in
+    let p = Jsont_pointer.of_string pointer_str in
+    let expected = parse_json expected_str in
+    let result = Jsont_pointer.test p json ~expected in
+    Printf.printf "%b\n" result
+  with Jsont.Error e ->
+    Printf.printf "ERROR: %s\n" (Jsont.Error.to_string e)
+
+(* Test: has operation (checks if pointer exists) *)
+let test_has json_str pointer_str =
+  try
+    let json = parse_json json_str in
+    let p = Jsont_pointer.of_string pointer_str in
+    let result = Jsont_pointer.find p json in
+    Printf.printf "%b\n" (Option.is_some result)
+  with Jsont.Error e ->
+    Printf.printf "ERROR: %s\n" (Jsont.Error.to_string e)
+
+let () =
+  match Array.to_list Sys.argv with
+  | _ :: "parse" :: pointer :: _ ->
+    test_parse pointer
+  | _ :: "roundtrip" :: pointer :: _ ->
+    test_roundtrip pointer
+  | _ :: "eval" :: json_path :: pointer :: _ ->
+    test_eval json_path pointer
+  | _ :: "escape" :: token :: _ ->
+    test_escape token
+  | _ :: "unescape" :: token :: _ ->
+    test_unescape token
+  | _ :: "uri-fragment" :: pointer :: _ ->
+    test_uri_fragment pointer
+  | _ :: "add" :: json :: pointer :: value :: _ ->
+    test_add json pointer value
+  | _ :: "remove" :: json :: pointer :: _ ->
+    test_remove json pointer
+  | _ :: "replace" :: json :: pointer :: value :: _ ->
+    test_replace json pointer value
+  | _ :: "move" :: json :: from :: path :: _ ->
+    test_move json from path
+  | _ :: "copy" :: json :: from :: path :: _ ->
+    test_copy json from path
+  | _ :: "test" :: json :: pointer :: expected :: _ ->
+    test_test json pointer expected
+  | _ :: "has" :: json :: pointer :: _ ->
+    test_has json pointer
+  | _ ->
+    Printf.printf "Usage:\n";
+    Printf.printf "  test_pointer parse <pointer>\n";
+    Printf.printf "  test_pointer roundtrip <pointer>\n";
+    Printf.printf "  test_pointer eval <json-file> <pointer>\n";
+    Printf.printf "  test_pointer escape <token>\n";
+    Printf.printf "  test_pointer unescape <token>\n";
+    Printf.printf "  test_pointer uri-fragment <pointer>\n";
+    Printf.printf "  test_pointer add <json> <pointer> <value>\n";
+    Printf.printf "  test_pointer remove <json> <pointer>\n";
+    Printf.printf "  test_pointer replace <json> <pointer> <value>\n";
+    Printf.printf "  test_pointer move <json> <from> <path>\n";
+    Printf.printf "  test_pointer copy <json> <from> <path>\n";
+    Printf.printf "  test_pointer test <json> <pointer> <expected>\n";
+    Printf.printf "  test_pointer has <json> <pointer>\n";
+    exit 1

test/uri_fragment.t

···
+URI Fragment Encoding Tests (RFC 6901 Section 6)
+
+Roundtrip through URI fragment encoding:
+  $ ./test_pointer.exe uri-fragment ""
+  OK:  -> 
+  $ ./test_pointer.exe uri-fragment "/foo"
+  OK: /foo -> /foo
+  $ ./test_pointer.exe uri-fragment "/foo/0"
+  OK: /foo/0 -> /foo/0
+  $ ./test_pointer.exe uri-fragment "/"
+  OK: / -> /
+  $ ./test_pointer.exe uri-fragment "/a~1b"
+  OK: /a~1b -> /a~1b
+  $ ./test_pointer.exe uri-fragment "/m~0n"
+  OK: /m~0n -> /m~0n
+
+Characters requiring percent-encoding:
+  $ ./test_pointer.exe uri-fragment "/c%d"
+  OK: /c%d -> /c%25d
+  $ ./test_pointer.exe uri-fragment "/e^f"
+  OK: /e^f -> /e%5Ef
+  $ ./test_pointer.exe uri-fragment "/g|h"
+  OK: /g|h -> /g%7Ch
+  $ ./test_pointer.exe uri-fragment '/i\j'
+  OK: /i\j -> /i%5Cj
+  $ ./test_pointer.exe uri-fragment '/k"l'
+  OK: /k"l -> /k%22l
+  $ ./test_pointer.exe uri-fragment "/ "
+  OK: /  -> /%20
+
+Roundtrip tests:
+  $ ./test_pointer.exe roundtrip ""
+  OK: 
+  $ ./test_pointer.exe roundtrip "/foo"
+  OK: /foo
+  $ ./test_pointer.exe roundtrip "/foo/0"
+  OK: /foo/0
+  $ ./test_pointer.exe roundtrip "/"
+  OK: /
+  $ ./test_pointer.exe roundtrip "/a~1b"
+  OK: /a~1b
+  $ ./test_pointer.exe roundtrip "/m~0n"
+  OK: /m~0n
+  $ ./test_pointer.exe roundtrip "/-"
+  OK: /-
+  $ ./test_pointer.exe roundtrip "/a/b/c"
+  OK: /a/b/c
+
+RFC 6901 Section 6 examples (URI fragment encoding):
+Note: These test the full RFC 6901 Section 6 examples
+  $ ./test_pointer.exe uri-fragment "/c%d"
+  OK: /c%d -> /c%25d
+  $ ./test_pointer.exe uri-fragment "/e^f"
+  OK: /e^f -> /e%5Ef
+  $ ./test_pointer.exe uri-fragment "/g|h"
+  OK: /g|h -> /g%7Ch
+  $ ./test_pointer.exe uri-fragment '/i\j'
+  OK: /i\j -> /i%5Cj
+  $ ./test_pointer.exe uri-fragment '/k"l'
+  OK: /k"l -> /k%22l
+  $ ./test_pointer.exe uri-fragment "/ "
+  OK: /  -> /%20
+
+Unicode in URI fragments:
+  $ ./test_pointer.exe uri-fragment "/café"
+  OK: /café -> /caf%C3%A9
+  $ ./test_pointer.exe uri-fragment "/日本語"
+  OK: /日本語 -> /%E6%97%A5%E6%9C%AC%E8%AA%9E
+
+Combined escapes (tilde escape + URI encode):
+Note: %25 in result is the URI encoding of %, and 100% is treated as member name
+  $ ./test_pointer.exe uri-fragment "/100%"
+  OK: /100% -> /100%25
+
+Multiple special chars:
+  $ ./test_pointer.exe uri-fragment "/a b^c|d"
+  OK: /a b^c|d -> /a%20b%5Ec%7Cd