mdx

doc/dune

···
 (mdx
  (deps
   %{bin:jsonpp}
-  rfc6901_example.json))
+  rfc6901_example.json
+  config.json)
+ (libraries jsont jsont.bytesrw jsont_pointer))

doc/tutorial.md

···
 
 Each reference token becomes an `Index.t` value in the library:
 
+<!-- $MDX skip -->
 ```ocaml
 type t =
   | Mem of string   (* Object member access *)
···
 
 In the library, this is the `Jsont_pointer.get` function:
 
+<!-- $MDX skip -->
 ```ocaml
 val get : t -> Jsont.json -> Jsont.json
 ```
···
 The empty pointer returns the whole document. In OCaml, this is
 `Jsont_pointer.root`:
 
+<!-- $MDX skip -->
 ```ocaml
 val root : t
 (** The empty pointer that references the whole document. *)
···
 **Important**: When using the OCaml library programmatically, you don't need
 to worry about escaping. The `Index.Mem` variant holds the literal key name:
 
+<!-- $MDX skip -->
 ```ocaml
 (* To access the key "a/b", just use the literal string *)
 let pointer = Jsont_pointer.make [Mem "a/b"]
···
 
 The library provides both exception-raising and result-returning variants:
 
+<!-- $MDX skip -->
 ```ocaml
 val get : t -> Jsont.json -> Jsont.json
 val get_result : t -> Jsont.json -> (Jsont.json, Jsont.Error.t) result
···
 
 In OCaml:
 
+<!-- $MDX skip -->
 ```ocaml
 val add : t -> Jsont.json -> value:Jsont.json -> Jsont.json
 ```
···
 to think about escaping. The `Index.Mem` variant stores unescaped strings,
 and escaping happens automatically during serialization:
 
+<!-- $MDX skip -->
 ```ocaml
 (* Create a pointer to key "a/b" - no escaping needed *)
 let p = Jsont_pointer.make [Mem "a/b"]
···
 
 The `Token` module exposes the escaping functions if you need them:
 
+<!-- $MDX skip -->
 ```ocaml
 module Token : sig
   val escape : string -> string    (* "a/b" -> "a~1b" *)
···
 
 The library provides functions for URI fragment encoding:
 
+<!-- $MDX skip -->
 ```ocaml
 val to_uri_fragment : t -> string
 val of_uri_fragment : string -> t
···
 
 ## Jsont Integration
 
-The library integrates with the `Jsont` codec system for typed access:
+The library integrates with the `Jsont` codec system, allowing you to
+combine JSON Pointer navigation with typed decoding. This is powerful
+because you can point to a location in a JSON document and decode it
+directly to an OCaml type.
+
+Let's set up our OCaml environment and explore these features:
+
+```ocaml
+# open Jsont_pointer;;
+# let parse_json s =
+    match Jsont_bytesrw.decode_string Jsont.json s with
+    | Ok json -> json
+    | Error e -> failwith e;;
+val parse_json : string -> Jsont.json = <fun>
+# let json_to_string json =
+    match Jsont_bytesrw.encode_string ~format:Jsont.Minify Jsont.json json with
+    | Ok s -> s
+    | Error e -> failwith e;;
+val json_to_string : Jsont.json -> string = <fun>
+```
+
+### Working with JSON Values
+
+Let's create a sample configuration document:
+
+```ocaml
+# let config_json = parse_json {|{
+    "database": {
+      "host": "localhost",
+      "port": 5432,
+      "credentials": {"username": "admin", "password": "secret"}
+    },
+    "features": ["auth", "logging", "metrics"]
+  }|};;
+val config_json : Jsont.json =
+  Jsont.Object
+   ([(("database", <abstr>),
+      Jsont.Object
+       ([(("host", <abstr>), Jsont.String ("localhost", <abstr>));
+         (("port", <abstr>), Jsont.Number (5432., <abstr>));
+         (("credentials", <abstr>),
+          Jsont.Object
+           ([(("username", <abstr>), Jsont.String ("admin", <abstr>));
+             (("password", <abstr>), Jsont.String ("secret", <abstr>))],
+            <abstr>))],
+        <abstr>));
+     (("features", <abstr>),
+      Jsont.Array
+       ([Jsont.String ("auth", <abstr>); Jsont.String ("logging", <abstr>);
+         Jsont.String ("metrics", <abstr>)],
+        <abstr>))],
+    <abstr>)
+```
+
+### Creating and Using Pointers
+
+Create a pointer and use it to extract values:
+
+```ocaml
+# let host_ptr = of_string "/database/host";;
+val host_ptr : t = <abstr>
+# let host_value = get host_ptr config_json;;
+val host_value : Jsont.json = Jsont.String ("localhost", <abstr>)
+# match host_value with
+  | Jsont.String (s, _) -> s
+  | _ -> failwith "expected string";;
+- : string = "localhost"
+```
+
+### Building Pointers Programmatically
+
+Instead of parsing strings, you can build pointers from indices:
+
+```ocaml
+# let port_ptr = make [Mem "database"; Mem "port"];;
+val port_ptr : t = <abstr>
+# to_string port_ptr;;
+- : string = "/database/port"
+# match get port_ptr config_json with
+  | Jsont.Number (n, _) -> int_of_float n
+  | _ -> failwith "expected number";;
+- : int = 5432
+```
+
+For array access, use `Nth`:
+
+```ocaml
+# let first_feature_ptr = make [Mem "features"; Nth 0];;
+val first_feature_ptr : t = <abstr>
+# match get first_feature_ptr config_json with
+  | Jsont.String (s, _) -> s
+  | _ -> failwith "expected string";;
+- : string = "auth"
+```
+
+### Pointer Navigation
+
+You can build pointers incrementally using `append`:
+
+```ocaml
+# let db_ptr = of_string "/database";;
+val db_ptr : t = <abstr>
+# let creds_ptr = append db_ptr (Mem "credentials");;
+val creds_ptr : t = <abstr>
+# let user_ptr = append creds_ptr (Mem "username");;
+val user_ptr : t = <abstr>
+# to_string user_ptr;;
+- : string = "/database/credentials/username"
+# match get user_ptr config_json with
+  | Jsont.String (s, _) -> s
+  | _ -> failwith "expected string";;
+- : string = "admin"
+```
+
+### Safe Access with `find`
+
+Use `find` when you're not sure if a path exists:
+
+```ocaml
+# find (of_string "/database/timeout") config_json;;
+- : Jsont.json option = None
+# find (of_string "/database/host") config_json |> Option.is_some;;
+- : bool = true
+```
+
+### Typed Access with `path`
+
+The `path` combinator combines pointer navigation with typed decoding:
+
+```ocaml
+# let db_host =
+    Jsont.Json.decode
+      (path (of_string "/database/host") Jsont.string)
+      config_json
+    |> Result.get_ok;;
+val db_host : string = "localhost"
+# let db_port =
+    Jsont.Json.decode
+      (path (of_string "/database/port") Jsont.int)
+      config_json
+    |> Result.get_ok;;
+val db_port : int = 5432
+```
+
+Extract a list of strings:
+
+```ocaml
+# let features =
+    Jsont.Json.decode
+      (path (of_string "/features") Jsont.(list string))
+      config_json
+    |> Result.get_ok;;
+val features : string list = ["auth"; "logging"; "metrics"]
+```
+
+### Default Values with `~absent`
+
+Use `~absent` to provide a default when a path doesn't exist:
+
+```ocaml
+# let timeout =
+    Jsont.Json.decode
+      (path ~absent:30 (of_string "/database/timeout") Jsont.int)
+      config_json
+    |> Result.get_ok;;
+val timeout : int = 30
+```
+
+### Mutation Operations
+
+The library provides mutation functions for modifying JSON:
+
+```ocaml
+# let sample = parse_json {|{"name": "Alice", "scores": [85, 92, 78]}|};;
+val sample : Jsont.json =
+  Jsont.Object
+   ([(("name", <abstr>), Jsont.String ("Alice", <abstr>));
+     (("scores", <abstr>),
+      Jsont.Array
+       ([Jsont.Number (85., <abstr>); Jsont.Number (92., <abstr>);
+         Jsont.Number (78., <abstr>)],
+        <abstr>))],
+    <abstr>)
+```
+
+**Add** a new field:
+
+```ocaml
+# let with_email = add (of_string "/email") sample
+    ~value:(Jsont.Json.string "[e-mail]");;
+val with_email : Jsont.json =
+  Jsont.Object
+   ([(("name", <abstr>), Jsont.String ("Alice", <abstr>));
+     (("scores", <abstr>),
+      Jsont.Array
+       ([Jsont.Number (85., <abstr>); Jsont.Number (92., <abstr>);
+         Jsont.Number (78., <abstr>)],
+        <abstr>));
+     (("email", <abstr>), Jsont.String ("[e-mail]", <abstr>))],
+    <abstr>)
+# json_to_string with_email;;
+- : string =
+"{\"name\":\"Alice\",\"scores\":[85,92,78],\"email\":\"[e-mail]\"}"
+```
+
+**Add** to an array using `-` (append):
+
+```ocaml
+# let with_new_score = add (of_string "/scores/-") sample
+    ~value:(Jsont.Json.number 95.);;
+val with_new_score : Jsont.json =
+  Jsont.Object
+   ([(("name", <abstr>), Jsont.String ("Alice", <abstr>));
+     (("scores", <abstr>),
+      Jsont.Array
+       ([Jsont.Number (85., <abstr>); Jsont.Number (92., <abstr>);
+         Jsont.Number (78., <abstr>); Jsont.Number (95., <abstr>)],
+        <abstr>))],
+    <abstr>)
+# json_to_string with_new_score;;
+- : string = "{\"name\":\"Alice\",\"scores\":[85,92,78,95]}"
+```
+
+**Replace** an existing value:
+
+```ocaml
+# let renamed = replace (of_string "/name") sample
+    ~value:(Jsont.Json.string "Bob");;
+val renamed : Jsont.json =
+  Jsont.Object
+   ([(("name", <abstr>), Jsont.String ("Bob", <abstr>));
+     (("scores", <abstr>),
+      Jsont.Array
+       ([Jsont.Number (85., <abstr>); Jsont.Number (92., <abstr>);
+         Jsont.Number (78., <abstr>)],
+        <abstr>))],
+    <abstr>)
+# json_to_string renamed;;
+- : string = "{\"name\":\"Bob\",\"scores\":[85,92,78]}"
+```
+
+**Remove** a value:
+
+```ocaml
+# let without_first = remove (of_string "/scores/0") sample;;
+val without_first : Jsont.json =
+  Jsont.Object
+   ([(("name", <abstr>), Jsont.String ("Alice", <abstr>));
+     (("scores", <abstr>),
+      Jsont.Array
+       ([Jsont.Number (92., <abstr>); Jsont.Number (78., <abstr>)], <abstr>))],
+    <abstr>)
+# json_to_string without_first;;
+- : string = "{\"name\":\"Alice\",\"scores\":[92,78]}"
+```
+
+### Nested Path Extraction
+
+You can extract values from deeply nested structures:
 
 ```ocaml
-(* Codec for JSON Pointers as JSON strings *)
-val jsont : t Jsont.t
+# let org_json = parse_json {|{
+    "organization": {
+      "owner": {"name": "Alice", "email": "[e-mail]", "age": 35},
+      "members": [{"name": "Bob", "email": "[e-mail]", "age": 28}]
+    }
+  }|};;
+val org_json : Jsont.json =
+  Jsont.Object
+   ([(("organization", <abstr>),
+      Jsont.Object
+       ([(("owner", <abstr>),
+          Jsont.Object
+           ([(("name", <abstr>), Jsont.String ("Alice", <abstr>));
+             (("email", <abstr>),
+              Jsont.String ("[e-mail]", <abstr>));
+             (("age", <abstr>), Jsont.Number (35., <abstr>))],
+            <abstr>));
+         (("members", <abstr>),
+          Jsont.Array
+           ([Jsont.Object
+              ([(("name", <abstr>), Jsont.String ("Bob", <abstr>));
+                (("email", <abstr>),
+                 Jsont.String ("[e-mail]", <abstr>));
+                (("age", <abstr>), Jsont.Number (28., <abstr>))],
+               <abstr>)],
+            <abstr>))],
+        <abstr>))],
+    <abstr>)
+# Jsont.Json.decode
+    (path (of_string "/organization/owner/name") Jsont.string)
+    org_json
+  |> Result.get_ok;;
+- : string = "Alice"
+# Jsont.Json.decode
+    (path (of_string "/organization/members/0/age") Jsont.int)
+    org_json
+  |> Result.get_ok;;
+- : int = 28
+```
 
-(* Query combinators *)
-val path : ?absent:'a -> t -> 'a Jsont.t -> 'a Jsont.t
-val set_path : ?allow_absent:bool -> 'a Jsont.t -> t -> 'a -> Jsont.json Jsont.t
-val update_path : ?absent:'a -> t -> 'a Jsont.t -> Jsont.json Jsont.t
-val delete_path : ?allow_absent:bool -> t -> Jsont.json Jsont.t
+### Comparison: Raw vs Typed Access
+
+**Raw access** requires pattern matching:
+
+```ocaml
+# let raw_port =
+    match get (of_string "/database/port") config_json with
+    | Jsont.Number (f, _) -> int_of_float f
+    | _ -> failwith "expected number";;
+val raw_port : int = 5432
 ```
 
-These allow you to use JSON Pointers with typed codecs rather than raw
-`Jsont.json` values.
+**Typed access** is cleaner and type-safe:
+
+```ocaml
+# let typed_port =
+    Jsont.Json.decode
+      (path (of_string "/database/port") Jsont.int)
+      config_json
+    |> Result.get_ok;;
+val typed_port : int = 5432
+```
+
+The typed approach catches mismatches at decode time with clear errors.
 
 ## Summary