RFC6901 JSON Pointer implementation in OCaml using jsont
Fix errors in documentation, and add a toplevel index
authored by
Tangled
424b6bb3
f5d950a4
+18
-18
src/json_pointer.mli
+18
-18
src/json_pointer.mli
···
77
(** [unescape s] unescapes a JSON Pointer reference token.
78
Specifically, [~1] becomes [/] and [~0] becomes [~].
79
80
-
@raise Jsont.Error.Error if [s] contains invalid escape sequences
81
(a [~] not followed by [0] or [1]). *)
82
end
83
···
202
203
val to_nav_exn : any -> nav t
204
(** [to_nav_exn p] returns the navigation pointer if [p] is one.
205
-
@raise Jsont.Error.Error if [p] is an append pointer. *)
206
207
(** {2:parsing Parsing} *)
208
···
217
with [/]. Each segment between [/] characters is unescaped as a
218
reference token.
219
220
-
@raise Jsont.Error.Error if [s] has invalid syntax:
221
- Non-empty string not starting with [/]
222
- Invalid escape sequence ([~] not followed by [0] or [1])
223
- [-] appears in non-final position *)
···
230
differently, or when you need a typed pointer for operations that
231
require a specific kind.
232
233
-
@raise Jsont.Error.Error if [s] has invalid syntax. *)
234
235
val of_string_nav : string -> nav t
236
(** [of_string_nav s] parses a JSON Pointer that must not contain [-].
···
238
Use this when you need a {!nav} pointer for retrieval operations
239
like {!get} or {!find}.
240
241
-
@raise Jsont.Error.Error if [s] has invalid syntax or contains [-]. *)
242
243
val of_string_result : string -> (any, string) result
244
(** [of_string_result s] is like {!of_string} but returns a result
···
251
according to {{:https://www.rfc-editor.org/rfc/rfc3986}RFC 3986}.
252
The leading [#] should {b not} be included in [s].
253
254
-
@raise Jsont.Error.Error on invalid syntax or invalid percent-encoding. *)
255
256
val of_uri_fragment_nav : string -> nav t
257
(** [of_uri_fragment_nav s] is like {!of_uri_fragment} but requires
258
the pointer to not contain [-].
259
260
-
@raise Jsont.Error.Error if invalid or contains [-]. *)
261
262
val of_uri_fragment_result : string -> (any, string) result
263
(** [of_uri_fragment_result s] is like {!of_uri_fragment} but returns
···
317
val get : nav t -> Jsont.json -> Jsont.json
318
(** [get p json] retrieves the value at pointer [p] in [json].
319
320
-
@raise Jsont.Error.Error if:
321
- The pointer references a nonexistent object member
322
- The pointer references an out-of-bounds array index
323
- An index type doesn't match the JSON value (e.g., [Nth]
···
353
This accepts {!type:any} pointers directly from {!of_string}:
354
{[set (of_string "/tasks/-") json ~value:(Jsont.Json.string "new task")]}
355
356
-
@raise Jsont.Error.Error if the pointer doesn't resolve to an existing
357
location (except for {!append} pointers on arrays). *)
358
359
val add : any -> Jsont.json -> value:Jsont.json -> Jsont.json
···
368
valid (0 to length inclusive).}
369
{- For {!append} pointers: Appends [value] to the array.}}
370
371
-
@raise Jsont.Error.Error if:
372
- The parent of the target location doesn't exist
373
- An array index is out of bounds (except for {!append} pointers)
374
- The parent is not an object or array *)
···
379
For objects, removes the member. For arrays, removes the element
380
and shifts subsequent elements.
381
382
-
@raise Jsont.Error.Error if:
383
- [p] is the root (cannot remove the root)
384
- The pointer doesn't resolve to an existing value *)
385
···
388
389
Unlike {!add}, this requires the target to exist.
390
391
-
@raise Jsont.Error.Error if the pointer doesn't resolve to an existing value. *)
392
393
val move : from:nav t -> path:any -> Jsont.json -> Jsont.json
394
(** [move ~from ~path json] moves the value from [from] to [path].
···
396
This is equivalent to {!remove} at [from] followed by {!add}
397
at [path] with the removed value.
398
399
-
@raise Jsont.Error.Error if:
400
- [from] doesn't resolve to a value
401
- [path] is a proper prefix of [from] (would create a cycle) *)
402
···
406
This is equivalent to {!get} at [from] followed by {!add}
407
at [path] with the retrieved value.
408
409
-
@raise Jsont.Error.Error if [from] doesn't resolve to a value. *)
410
411
val test : nav t -> Jsont.json -> expected:Jsont.json -> bool
412
(** [test p json ~expected] tests if the value at [p] equals [expected].
···
511
The syntax is the same as RFC 6901 JSON Pointer, except [*] is allowed
512
as a reference token for array mapping.
513
514
-
@raise Jsont.Error.Error if [s] has invalid syntax. *)
515
516
val of_string_result : string -> (t, string) result
517
(** [of_string_result s] is like {!of_string} but returns a result. *)
···
528
For [*] tokens on arrays, maps through all elements and collects results.
529
Results that are arrays are flattened into the output.
530
531
-
@raise Jsont.Error.Error if:
532
- A standard token doesn't resolve (member not found, index out of bounds)
533
- [*] is used on a non-array value
534
- [-] appears in the pointer (not supported in JMAP extended pointers) *)
···
561
(Jsont.list Jsont.string)
562
]}
563
564
-
@raise Jsont.Error.Error if the pointer fails to resolve (and no [absent])
565
or if decoding with [codec] fails. *)
566
567
val path_list : t -> 'a Jsont.t -> 'a list Jsont.t
···
576
Jmap.path (Jmap.of_string "/list/*/id") (Jsont.list Jsont.string)
577
]}
578
579
-
@raise Jsont.Error.Error if pointer resolution fails, the result is not an array,
580
or any element fails to decode. *)
581
end
···
77
(** [unescape s] unescapes a JSON Pointer reference token.
78
Specifically, [~1] becomes [/] and [~0] becomes [~].
79
80
+
@raise Jsont.exception-Error if [s] contains invalid escape sequences
81
(a [~] not followed by [0] or [1]). *)
82
end
83
···
202
203
val to_nav_exn : any -> nav t
204
(** [to_nav_exn p] returns the navigation pointer if [p] is one.
205
+
@raise Jsont.exception-Error if [p] is an append pointer. *)
206
207
(** {2:parsing Parsing} *)
208
···
217
with [/]. Each segment between [/] characters is unescaped as a
218
reference token.
219
220
+
@raise Jsont.exception-Error if [s] has invalid syntax:
221
- Non-empty string not starting with [/]
222
- Invalid escape sequence ([~] not followed by [0] or [1])
223
- [-] appears in non-final position *)
···
230
differently, or when you need a typed pointer for operations that
231
require a specific kind.
232
233
+
@raise Jsont.exception-Error if [s] has invalid syntax. *)
234
235
val of_string_nav : string -> nav t
236
(** [of_string_nav s] parses a JSON Pointer that must not contain [-].
···
238
Use this when you need a {!nav} pointer for retrieval operations
239
like {!get} or {!find}.
240
241
+
@raise Jsont.exception-Error if [s] has invalid syntax or contains [-]. *)
242
243
val of_string_result : string -> (any, string) result
244
(** [of_string_result s] is like {!of_string} but returns a result
···
251
according to {{:https://www.rfc-editor.org/rfc/rfc3986}RFC 3986}.
252
The leading [#] should {b not} be included in [s].
253
254
+
@raise Jsont.exception-Error on invalid syntax or invalid percent-encoding. *)
255
256
val of_uri_fragment_nav : string -> nav t
257
(** [of_uri_fragment_nav s] is like {!of_uri_fragment} but requires
258
the pointer to not contain [-].
259
260
+
@raise Jsont.exception-Error if invalid or contains [-]. *)
261
262
val of_uri_fragment_result : string -> (any, string) result
263
(** [of_uri_fragment_result s] is like {!of_uri_fragment} but returns
···
317
val get : nav t -> Jsont.json -> Jsont.json
318
(** [get p json] retrieves the value at pointer [p] in [json].
319
320
+
@raise Jsont.exception-Error if:
321
- The pointer references a nonexistent object member
322
- The pointer references an out-of-bounds array index
323
- An index type doesn't match the JSON value (e.g., [Nth]
···
353
This accepts {!type:any} pointers directly from {!of_string}:
354
{[set (of_string "/tasks/-") json ~value:(Jsont.Json.string "new task")]}
355
356
+
@raise Jsont.exception-Error if the pointer doesn't resolve to an existing
357
location (except for {!append} pointers on arrays). *)
358
359
val add : any -> Jsont.json -> value:Jsont.json -> Jsont.json
···
368
valid (0 to length inclusive).}
369
{- For {!append} pointers: Appends [value] to the array.}}
370
371
+
@raise Jsont.exception-Error if:
372
- The parent of the target location doesn't exist
373
- An array index is out of bounds (except for {!append} pointers)
374
- The parent is not an object or array *)
···
379
For objects, removes the member. For arrays, removes the element
380
and shifts subsequent elements.
381
382
+
@raise Jsont.exception-Error if:
383
- [p] is the root (cannot remove the root)
384
- The pointer doesn't resolve to an existing value *)
385
···
388
389
Unlike {!add}, this requires the target to exist.
390
391
+
@raise Jsont.exception-Error if the pointer doesn't resolve to an existing value. *)
392
393
val move : from:nav t -> path:any -> Jsont.json -> Jsont.json
394
(** [move ~from ~path json] moves the value from [from] to [path].
···
396
This is equivalent to {!remove} at [from] followed by {!add}
397
at [path] with the removed value.
398
399
+
@raise Jsont.exception-Error if:
400
- [from] doesn't resolve to a value
401
- [path] is a proper prefix of [from] (would create a cycle) *)
402
···
406
This is equivalent to {!get} at [from] followed by {!add}
407
at [path] with the retrieved value.
408
409
+
@raise Jsont.exception-Error if [from] doesn't resolve to a value. *)
410
411
val test : nav t -> Jsont.json -> expected:Jsont.json -> bool
412
(** [test p json ~expected] tests if the value at [p] equals [expected].
···
511
The syntax is the same as RFC 6901 JSON Pointer, except [*] is allowed
512
as a reference token for array mapping.
513
514
+
@raise Jsont.exception-Error if [s] has invalid syntax. *)
515
516
val of_string_result : string -> (t, string) result
517
(** [of_string_result s] is like {!of_string} but returns a result. *)
···
528
For [*] tokens on arrays, maps through all elements and collects results.
529
Results that are arrays are flattened into the output.
530
531
+
@raise Jsont.exception-Error if:
532
- A standard token doesn't resolve (member not found, index out of bounds)
533
- [*] is used on a non-array value
534
- [-] appears in the pointer (not supported in JMAP extended pointers) *)
···
561
(Jsont.list Jsont.string)
562
]}
563
564
+
@raise Jsont.exception-Error if the pointer fails to resolve (and no [absent])
565
or if decoding with [codec] fails. *)
566
567
val path_list : t -> 'a Jsont.t -> 'a list Jsont.t
···
576
Jmap.path (Jmap.of_string "/list/*/id") (Jsont.list Jsont.string)
577
]}
578
579
+
@raise Jsont.exception-Error if pointer resolution fails, the result is not an array,
580
or any element fails to decode. *)
581
end