docs

doc/tutorial.md

···
 
 The JSON Pointer `/users/0/name` refers to the string `"Alice"`.
 
+In OCaml, this is represented by the `Jsont_pointer.t` type - a sequence
+of navigation steps from the document root to a target value.
+
 ## Syntax: Reference Tokens
 
 RFC 6901, Section 3 defines the syntax:
···
 
 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`.
+### The Index Type
 
-```sh
-$ jsonpp escape "~/"
-~0~1
-```
-
-Both characters are escaped.
-
-### Unescaping
-
-And the reverse process:
-
-```sh
-$ jsonpp unescape "a~1b"
-OK: a/b
-```
+Each reference token becomes an `Index.t` value in the library:
 
-```sh
-$ jsonpp unescape "a~0b"
-OK: a~b
+```ocaml
+type t =
+  | Mem of string   (* Object member access *)
+  | Nth of int      (* Array index access *)
+  | End             (* The special "-" marker for append operations *)
 ```
 
-### The Order Matters!
+The `Mem` variant holds the **unescaped** member name - you work with the
+actual key string (like `"a/b"`) and the library handles any escaping needed
+for the JSON Pointer string representation.
 
-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).
+### Invalid Syntax
 
-Let's verify this tricky case:
+What happens if a pointer doesn't start with `/`?
 
 ```sh
-$ jsonpp unescape "~01"
-OK: ~1
+$ jsonpp parse "foo"
+ERROR: Invalid JSON Pointer: must be empty or start with '/': foo
 ```
 
-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
-```
+The RFC is strict: non-empty pointers MUST start with `/`.
 
 ## Evaluation: Navigating JSON
 
···
 > the document. Each reference token in the JSON Pointer is evaluated
 > sequentially.
 
+In the library, this is the `Jsont_pointer.get` function:
+
+```ocaml
+val get : t -> Jsont.json -> Jsont.json
+```
+
 Let's use the example JSON document from RFC 6901, Section 5:
 
 ```sh
···
 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.
+The empty pointer returns the whole document. In OCaml, this is
+`Jsont_pointer.root`:
+
+```ocaml
+val root : t
+(** The empty pointer that references the whole document. *)
+```
 
 ### Object Member Access
 
···
 
 ### Keys with Special Characters
 
-Now for the escape sequences:
+The RFC example includes keys with `/` and `~` characters:
 
 ```sh
 $ jsonpp eval rfc6901_example.json "/a~1b"
 OK: 1
 ```
 
-The token `a~1b` unescapes to `a/b`, which is the key name.
+The token `a~1b` refers to the key `a/b`. We'll explain this escaping
+[below](#escaping-special-characters).
 
 ```sh
 $ jsonpp eval rfc6901_example.json "/m~0n"
 OK: 8
 ```
 
-The token `m~0n` unescapes to `m~n`.
+The token `m~0n` refers to the key `m~n`.
+
+**Important**: When using the OCaml library programmatically, you don't need
+to worry about escaping. The `Index.Mem` variant holds the literal key name:
+
+```ocaml
+(* To access the key "a/b", just use the literal string *)
+let pointer = Jsont_pointer.make [Mem "a/b"]
+
+(* The library escapes it when converting to string *)
+let s = Jsont_pointer.to_string pointer  (* "/a~1b" *)
+```
 
 ### Other Special Characters (No Escaping Needed)
 
···
 $ jsonpp eval rfc6901_example.json "/foo/0/invalid"
 ERROR: JSON Pointer: cannot index into string with 'invalid'
 File "-":
+```
+
+The library provides both exception-raising and result-returning variants:
+
+```ocaml
+val get : t -> Jsont.json -> Jsont.json
+val get_result : t -> Jsont.json -> (Jsont.json, Jsont.Error.t) result
+val find : t -> Jsont.json -> Jsont.json option
 ```
 
 ### Array Index Rules
···
 
 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
···
 {"foo":"bar","baz":"qux"}
 ```
 
+In OCaml:
+
+```ocaml
+val add : t -> Jsont.json -> value:Jsont.json -> Jsont.json
+```
+
 For arrays, `add` inserts BEFORE the specified index:
 
 ```sh
···
 false
 ```
 
+## 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)
+
+### The Library Handles Escaping Automatically
+
+**Important**: When using `jsont-pointer` programmatically, you rarely need
+to think about escaping. The `Index.Mem` variant stores unescaped strings,
+and escaping happens automatically during serialization:
+
+```ocaml
+(* Create a pointer to key "a/b" - no escaping needed *)
+let p = Jsont_pointer.make [Mem "a/b"]
+
+(* Serialize to string - escaping happens automatically *)
+let s = Jsont_pointer.to_string p  (* Returns "/a~1b" *)
+
+(* Parse from string - unescaping happens automatically *)
+let p' = Jsont_pointer.of_string "/a~1b"
+(* p' contains [Mem "a/b"] - the unescaped key *)
+```
+
+The `Token` module exposes the escaping functions if you need them:
+
+```ocaml
+module Token : sig
+  val escape : string -> string    (* "a/b" -> "a~1b" *)
+  val unescape : string -> string  (* "a~1b" -> "a/b" *)
+end
+```
+
+### Escaping in Action
+
+Let's see escaping with the CLI tool:
+
+```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
+```
+
+## 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`.
+
+The library provides functions for URI fragment encoding:
+
+```ocaml
+val to_uri_fragment : t -> string
+val of_uri_fragment : string -> t
+val jsont_uri_fragment : t Jsont.t
+```
+
+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` |
+
 ## Deeply Nested Structures
 
 JSON Pointer handles arbitrarily deep nesting:
···
 {"arr":[[1,99,2],[3,4]]}
 ```
 
+## Jsont Integration
+
+The library integrates with the `Jsont` codec system for typed access:
+
+```ocaml
+(* Codec for JSON Pointers as JSON strings *)
+val jsont : t Jsont.t
+
+(* 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
+```
+
+These allow you to use JSON Pointers with typed codecs rather than raw
+`Jsont.json` values.
+
 ## 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
+2. **Escaping**: Use `~0` for `~` and `~1` for `/` in tokens (handled automatically by the library)
 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