more docs

bin/dune

···
+(executable
+ (name jsonpp)
+ (public_name jsonpp)
+ (package jsont-pointer)
+ (libraries jsont jsont.bytesrw jsont_pointer))

bin/jsonpp.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
+
+let parse_json s =
+  match Jsont_bytesrw.decode_string Jsont.json s with
+  | Ok json -> json
+  | Error e -> failwith e
+
+let json_to_string json =
+  match Jsont_bytesrw.encode_string Jsont.json json with
+  | Ok s -> s
+  | Error e -> failwith e
+
+(* 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

doc/dune

···
+(mdx
+ (deps
+  %{bin:jsonpp}
+  rfc6901_example.json))

doc/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
+}

doc/tutorial.md

···
+# JSON Pointer Tutorial
+
+This tutorial introduces JSON Pointer as defined in
+[RFC 6901](https://www.rfc-editor.org/rfc/rfc6901), and demonstrates
+the `jsont-pointer` OCaml library through interactive examples.
+
+## What is JSON Pointer?
+
+From RFC 6901, Section 1:
+
+> JSON Pointer defines a string syntax for identifying a specific value
+> within a JavaScript Object Notation (JSON) document.
+
+In other words, JSON Pointer is an addressing scheme for locating values
+inside a JSON structure. Think of it like a filesystem path, but for JSON
+documents instead of files.
+
+For example, given this JSON document:
+
+```json
+{
+  "users": [
+    {"name": "Alice", "age": 30},
+    {"name": "Bob", "age": 25}
+  ]
+}
+```
+
+The JSON Pointer `/users/0/name` refers to the string `"Alice"`.
+
+## Syntax: Reference Tokens
+
+RFC 6901, Section 3 defines the syntax:
+
+> A JSON Pointer is a Unicode string containing a sequence of zero or more
+> reference tokens, each prefixed by a '/' (%x2F) character.
+
+The grammar is elegantly simple:
+
+```
+json-pointer    = *( "/" reference-token )
+reference-token = *( unescaped / escaped )
+```
+
+This means:
+- The empty string `""` is a valid pointer (it refers to the whole document)
+- Every non-empty pointer starts with `/`
+- Everything between `/` characters is a "reference token"
+
+Let's see this in action. We can parse pointers and see their structure:
+
+```sh
+$ jsonpp parse ""
+OK: []
+```
+
+The empty pointer has no reference tokens - it points to the root.
+
+```sh
+$ jsonpp parse "/foo"
+OK: [Mem:foo]
+```
+
+The pointer `/foo` has one token: `foo`. Since it's not a number, it's
+interpreted as an object member name (`Mem`).
+
+```sh
+$ jsonpp parse "/foo/0"
+OK: [Mem:foo, Nth:0]
+```
+
+Here we have two tokens: `foo` (a member name) and `0` (interpreted as
+an array index `Nth`).
+
+```sh
+$ jsonpp parse "/foo/bar/baz"
+OK: [Mem:foo, Mem:bar, Mem:baz]
+```
+
+Multiple tokens navigate deeper into nested structures.
+
+### Invalid Syntax
+
+What happens if a pointer doesn't start with `/`?
+
+```sh
+$ jsonpp parse "foo"
+ERROR: Invalid JSON Pointer: must be empty or start with '/': foo
+```
+
+The RFC is strict: non-empty pointers MUST start with `/`.
+
+## Escaping Special Characters
+
+RFC 6901, Section 3 explains the escaping rules:
+
+> 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.
+
+Why these specific characters?
+- `/` separates tokens, so it must be escaped inside a token
+- `~` is the escape character itself, so it must also be escaped
+
+The escape sequences are:
+- `~0` represents `~` (tilde)
+- `~1` represents `/` (forward slash)
+
+Let's see escaping in action:
+
+```sh
+$ jsonpp escape "hello"
+hello
+```
+
+No special characters, no escaping needed.
+
+```sh
+$ jsonpp escape "a/b"
+a~1b
+```
+
+The `/` becomes `~1`.
+
+```sh
+$ jsonpp escape "a~b"
+a~0b
+```
+
+The `~` becomes `~0`.
+
+```sh
+$ jsonpp escape "~/"
+~0~1
+```
+
+Both characters are escaped.
+
+### Unescaping
+
+And the reverse process:
+
+```sh
+$ jsonpp unescape "a~1b"
+OK: a/b
+```
+
+```sh
+$ jsonpp unescape "a~0b"
+OK: a~b
+```
+
+### The Order Matters!
+
+RFC 6901, Section 4 is careful to specify the unescaping order:
+
+> 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).
+
+Let's verify this tricky case:
+
+```sh
+$ jsonpp unescape "~01"
+OK: ~1
+```
+
+If we unescaped `~0` first, `~01` would become `~1`, which would then become
+`/`. But that's wrong! The sequence `~01` should become the literal string
+`~1` (a tilde followed by the digit one).
+
+Invalid escape sequences are rejected:
+
+```sh
+$ jsonpp unescape "~2"
+ERROR: Invalid JSON Pointer: invalid escape sequence ~2
+```
+
+```sh
+$ jsonpp unescape "hello~"
+ERROR: Invalid JSON Pointer: incomplete escape sequence at end
+```
+
+## Evaluation: Navigating JSON
+
+Now we come to the heart of JSON Pointer: evaluation. RFC 6901, Section 4
+describes how a pointer is resolved against a JSON document:
+
+> 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.
+
+Let's use the example JSON document from RFC 6901, Section 5:
+
+```sh
+$ cat 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
+}
+```
+
+This document is carefully constructed to exercise various edge cases!
+
+### The Root Pointer
+
+```sh
+$ jsonpp eval 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}
+```
+
+The empty pointer returns the whole document.
+
+### Object Member Access
+
+```sh
+$ jsonpp eval rfc6901_example.json "/foo"
+OK: ["bar","baz"]
+```
+
+`/foo` accesses the member named `foo`, which is an array.
+
+### Array Index Access
+
+```sh
+$ jsonpp eval rfc6901_example.json "/foo/0"
+OK: "bar"
+```
+
+`/foo/0` first goes to `foo`, then accesses index 0 of the array.
+
+```sh
+$ jsonpp eval rfc6901_example.json "/foo/1"
+OK: "baz"
+```
+
+Index 1 gives us the second element.
+
+### Empty String as Key
+
+JSON allows empty strings as object keys:
+
+```sh
+$ jsonpp eval rfc6901_example.json "/"
+OK: 0
+```
+
+The pointer `/` has one token: the empty string. This accesses the member
+with an empty name.
+
+### Keys with Special Characters
+
+Now for the escape sequences:
+
+```sh
+$ jsonpp eval rfc6901_example.json "/a~1b"
+OK: 1
+```
+
+The token `a~1b` unescapes to `a/b`, which is the key name.
+
+```sh
+$ jsonpp eval rfc6901_example.json "/m~0n"
+OK: 8
+```
+
+The token `m~0n` unescapes to `m~n`.
+
+### Other Special Characters (No Escaping Needed)
+
+Most characters don't need escaping in JSON Pointer strings:
+
+```sh
+$ jsonpp eval rfc6901_example.json "/c%d"
+OK: 2
+```
+
+```sh
+$ jsonpp eval rfc6901_example.json "/e^f"
+OK: 3
+```
+
+```sh
+$ jsonpp eval rfc6901_example.json "/g|h"
+OK: 4
+```
+
+```sh
+$ jsonpp eval rfc6901_example.json "/ "
+OK: 7
+```
+
+Even a space is a valid key character!
+
+### Error Conditions
+
+What happens when we try to access something that doesn't exist?
+
+```sh
+$ jsonpp eval rfc6901_example.json "/nonexistent"
+ERROR: JSON Pointer: member 'nonexistent' not found
+File "-":
+```
+
+Or an out-of-bounds array index:
+
+```sh
+$ jsonpp eval rfc6901_example.json "/foo/99"
+ERROR: JSON Pointer: index 99 out of bounds (array has 2 elements)
+File "-":
+```
+
+Or try to index into a non-container:
+
+```sh
+$ jsonpp eval rfc6901_example.json "/foo/0/invalid"
+ERROR: JSON Pointer: cannot index into string with 'invalid'
+File "-":
+```
+
+### Array Index Rules
+
+RFC 6901 has specific rules for array indices. Section 4 states:
+
+> characters comprised of digits [...] 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
+
+And importantly:
+
+> note that leading zeros are not allowed
+
+```sh
+$ jsonpp parse "/foo/0"
+OK: [Mem:foo, Nth:0]
+```
+
+Zero itself is fine.
+
+```sh
+$ jsonpp parse "/foo/01"
+OK: [Mem:foo, Mem:01]
+```
+
+But `01` has a leading zero, so it's NOT treated as an array index - it
+becomes a member name instead. This protects against accidental octal
+interpretation.
+
+## The End-of-Array Marker: `-`
+
+RFC 6901, Section 4 introduces a special token:
+
+> exactly the single character "-", making the new referenced value the
+> (nonexistent) member after the last array element.
+
+This is primarily useful for JSON Patch operations (RFC 6902). Let's see
+how it parses:
+
+```sh
+$ jsonpp parse "/foo/-"
+OK: [Mem:foo, End]
+```
+
+The `-` is recognized as a special `End` index.
+
+However, you cannot evaluate a pointer containing `-` because it refers
+to a position that doesn't exist:
+
+```sh
+$ jsonpp eval rfc6901_example.json "/foo/-"
+ERROR: JSON Pointer: '-' (end marker) refers to nonexistent array element
+File "-":
+```
+
+The RFC explains this:
+
+> 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.
+
+But we'll see later that `-` is very useful for mutation operations!
+
+## URI Fragment Encoding
+
+JSON Pointers can be embedded in URIs. RFC 6901, Section 6 explains:
+
+> A JSON Pointer can be represented in a URI fragment identifier by
+> encoding it into octets using UTF-8, while percent-encoding those
+> characters not allowed by the fragment rule in RFC 3986.
+
+This adds percent-encoding on top of the `~0`/`~1` escaping:
+
+```sh
+$ jsonpp uri-fragment "/foo"
+OK: /foo -> /foo
+```
+
+Simple pointers often don't need percent-encoding.
+
+```sh
+$ jsonpp uri-fragment "/a~1b"
+OK: /a~1b -> /a~1b
+```
+
+The `~1` escape stays as-is (it's valid in URI fragments).
+
+```sh
+$ jsonpp uri-fragment "/c%d"
+OK: /c%d -> /c%25d
+```
+
+The `%` character must be percent-encoded as `%25` in URIs!
+
+```sh
+$ jsonpp uri-fragment "/ "
+OK: /  -> /%20
+```
+
+Spaces become `%20`.
+
+Here's the RFC example showing the URI fragment forms:
+
+| JSON Pointer | URI Fragment | Value |
+|-------------|-------------|-------|
+| `""`        | `#`         | whole document |
+| `"/foo"`    | `#/foo`     | `["bar", "baz"]` |
+| `"/foo/0"`  | `#/foo/0`   | `"bar"` |
+| `"/"`       | `#/`        | `0` |
+| `"/a~1b"`   | `#/a~1b`    | `1` |
+| `"/c%d"`    | `#/c%25d`   | `2` |
+| `"/ "`      | `#/%20`     | `7` |
+| `"/m~0n"`   | `#/m~0n`    | `8` |
+
+## Mutation Operations
+
+While RFC 6901 defines JSON Pointer for read-only access, RFC 6902
+(JSON Patch) uses JSON Pointer for modifications. The `jsont-pointer`
+library provides these operations.
+
+### Add
+
+The `add` operation inserts a value at a location:
+
+```sh
+$ jsonpp add '{"foo":"bar"}' '/baz' '"qux"'
+{"foo":"bar","baz":"qux"}
+```
+
+For arrays, `add` inserts BEFORE the specified index:
+
+```sh
+$ jsonpp add '{"foo":["a","b"]}' '/foo/1' '"X"'
+{"foo":["a","X","b"]}
+```
+
+This is where the `-` marker shines - it appends to the end:
+
+```sh
+$ jsonpp add '{"foo":["a","b"]}' '/foo/-' '"c"'
+{"foo":["a","b","c"]}
+```
+
+### Remove
+
+The `remove` operation deletes a value:
+
+```sh
+$ jsonpp remove '{"foo":"bar","baz":"qux"}' '/baz'
+{"foo":"bar"}
+```
+
+For arrays, it removes and shifts:
+
+```sh
+$ jsonpp remove '{"foo":["a","b","c"]}' '/foo/1'
+{"foo":["a","c"]}
+```
+
+### Replace
+
+The `replace` operation updates an existing value:
+
+```sh
+$ jsonpp replace '{"foo":"bar"}' '/foo' '"baz"'
+{"foo":"baz"}
+```
+
+Unlike `add`, `replace` requires the target to already exist:
+
+```sh
+$ jsonpp replace '{"foo":"bar"}' '/nonexistent' '"value"'
+ERROR: JSON Pointer: member 'nonexistent' not found
+File "-":
+```
+
+### Move
+
+The `move` operation relocates a value:
+
+```sh
+$ jsonpp move '{"foo":{"bar":"baz"},"qux":{}}' '/foo/bar' '/qux/thud'
+{"foo":{},"qux":{"thud":"baz"}}
+```
+
+### Copy
+
+The `copy` operation duplicates a value:
+
+```sh
+$ jsonpp copy '{"foo":{"bar":"baz"}}' '/foo/bar' '/foo/qux'
+{"foo":{"bar":"baz","qux":"baz"}}
+```
+
+### Test
+
+The `test` operation verifies a value (useful in JSON Patch):
+
+```sh
+$ jsonpp test '{"foo":"bar"}' '/foo' '"bar"'
+true
+```
+
+```sh
+$ jsonpp test '{"foo":"bar"}' '/foo' '"baz"'
+false
+```
+
+## Deeply Nested Structures
+
+JSON Pointer handles arbitrarily deep nesting:
+
+```sh
+$ jsonpp eval rfc6901_example.json "/foo/0"
+OK: "bar"
+```
+
+For deeper structures, just add more path segments. With nested objects:
+
+```sh
+$ jsonpp add '{"a":{"b":{"c":"d"}}}' '/a/b/x' '"y"'
+{"a":{"b":{"c":"d","x":"y"}}}
+```
+
+With nested arrays:
+
+```sh
+$ jsonpp add '{"arr":[[1,2],[3,4]]}' '/arr/0/1' '99'
+{"arr":[[1,99,2],[3,4]]}
+```
+
+## Summary
+
+JSON Pointer (RFC 6901) provides a simple but powerful way to address
+values within JSON documents:
+
+1. **Syntax**: Pointers are strings of `/`-separated reference tokens
+2. **Escaping**: Use `~0` for `~` and `~1` for `/` in tokens
+3. **Evaluation**: Tokens navigate through objects (by key) and arrays (by index)
+4. **URI Encoding**: Pointers can be percent-encoded for use in URIs
+5. **Mutations**: Combined with JSON Patch (RFC 6902), pointers enable structured updates
+
+The `jsont-pointer` library implements all of this with type-safe OCaml
+interfaces, integration with the `jsont` codec system, and proper error
+handling for malformed pointers and missing values.

dune-project

···
 (lang dune 3.20)
+(using mdx 0.4)
 
 (name jsont-pointer)
 

test/dune

···
 (executable
  (name test_pointer)
- (libraries jsont jsont_pointer yojson))
+ (libraries jsont jsont.bytesrw jsont_pointer))
 
 (cram
  (deps test_pointer.exe

test/eval.t

···
 Error: nonexistent member:
   $ ./test_pointer.exe eval data/rfc6901_example.json "/nonexistent"
   ERROR: JSON Pointer: member 'nonexistent' not found
+  File "-":
 
 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)
+  File "-":
   $ ./test_pointer.exe eval data/rfc6901_example.json "/foo/99"
   ERROR: JSON Pointer: index 99 out of bounds (array has 2 elements)
+  File "-":
 
 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'
+  File "-":
 
 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
+  File "-":
 
 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'
+  File "-":
   $ ./test_pointer.exe eval data/rfc6901_example.json "/foo/0/bar"
   ERROR: JSON Pointer: cannot index into string with 'bar'
+  File "-":
 
 Nested evaluation with deep nesting:
   $ cat data/nested.json

test/mutations.t

···
 Error: remove nonexistent:
   $ ./test_pointer.exe remove '{"foo":"bar"}' '/baz'
   ERROR: JSON Pointer: member 'baz' not found for remove
+  File "-":
 
 Error: replace nonexistent:
   $ ./test_pointer.exe replace '{"foo":"bar"}' '/baz' '"qux"'
   ERROR: JSON Pointer: member 'baz' not found
+  File "-":
 
 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)
+  File "-":
 
 Add nested path (parent must exist):
   $ ./test_pointer.exe add '{"foo":{}}' '/foo/bar' '"baz"'
···
 Error: remove from nonexistent array index:
   $ ./test_pointer.exe remove '{"foo":["bar"]}' '/foo/5'
   ERROR: JSON Pointer: index 5 out of bounds for remove
+  File "-":
 
 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
+  File "-":
 
 Copy to same location (no-op essentially):
   $ ./test_pointer.exe copy '{"foo":"bar"}' '/foo' '/foo'

test/test_pointer.ml

···
   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)
+  match Jsont_bytesrw.decode_string Jsont.json s with
+  | Ok json -> json
+  | Error e -> failwith e
 
 let json_to_string json =
-  Yojson.Safe.to_string (jsont_to_yojson json)
+  match Jsont_bytesrw.encode_string Jsont.json json with
+  | Ok s -> s
+  | Error e -> failwith e
 
 (* Test: parse pointer and print indices *)
 let test_parse pointer_str =