ocplib-json-typed 0.1 · OCaml Package

Representations of JSON documents

In memory JSON document representation

type value = [

| `O of (string * value) list
(*
Cf. document.
*)
| `A of value list
(*
Cf. document.
*)
| `Bool of bool
(*
A JS boolean true or false.
*)
| `Float of float
(*
A floating point number (double precision).
*)
| `String of string
(*
An UTF-8 encoded string.
*)
| `Null
(*
The null constant.
*)

]

A JSON value compatible with Ezjsonm.value. This is the main type used by this library, unlike yojson, which is provided only for compatibility.

Paths in JSON documents

type path = path_item list

An abstract type for paths into a JSON document. A sequence of sub-tree selectors to descend into a JSON tree.

and path_item = [

| `Field of string
(*
A field in an object.
*)
| `Index of int
(*
An index in an array.
*)
| `Star
(*
Any / every field or index.
*)
| `Next
(*
The next element after an array.
*)

]

A JSON sub-tree selector. Indendent from any concrete format (JSON pointer, JSON path, etc.) The semantics depends on the use (selection, insertion, etc.)

val print_path_as_json_pointer : 
  ?wildcards:bool ->
  Format.formatter ->
  path ->
  unit

Pretty prints a path in JSON pointer format (RFC6901). May throw Unsupported_path_item. Use ~wildcards:false to deactivate the support of wildcard path items, which may lead to Unsupported_path_item.

val print_path_as_json_path : 
  ?wildcards:bool ->
  Format.formatter ->
  path ->
  unit

Pretty prints a path in JSON path format. Use ~wildcards:false to deactivate the support of wildcard path items, which may lead to Unsupported_path_item.

val json_pointer_of_path : ?wildcards:bool -> path -> string

Pretty prints a path in JSON pointer format into a fresh string. May throw Unsupported_path_item. Use ~wildcards:false to deactivate the support of wildcard path items, which may lead to Unsupported_path_item.

val path_of_json_pointer : ?wildcards:bool -> string -> path

Parses a path from a string in JSON pointer format. May throw Illegal_pointer_notation. The string is expected to be ASCII compatible, including UTF-8. Use ~wildcards:false to deactivate the support of wildcard path items, which may lead to Unsupported_path_item.

Querying JSON documents

val query : path -> [< value ] -> value

Extracts the value located at a given path. If multiple locations satisfy the path (in presence of wildcard path items), the chosen one is unspecified. May throw Not_found.

val query_all : path -> [< value ] -> value list

Extracts the values located at a given path (may be more than one in presence of wildcard path items). The order is unspecified.

val insert : path -> [< value ] -> [< value ] -> value

Insert a value at a given path. If multiple locations satisfy the path (in presence of wildcard path items), the chosen one is unspecified. Will create parent objects or arrays if needed, for instance inserting 3 at /a/b/c in {} will result in {"a":{"b":{"c":3}}}. Inserting in an array at an index bigger than the previous size will expand the array, filling potential missing cells with `Null. Inserting in an array at `Index n where n is negative inserts from the last element of the array. If a value is inserted at a location where there is already one, both are merged as if with merge. May throw Cannot_merge if the path is incompatible with the original object (such as inserting in a field of something which is not an object) or if the value is to be merged with an incompatible existing value.

val replace : path -> [< value ] -> [< value ] -> value

Same as insert, except that if the path leads to a pre-existing value, it is replaced with the new one instead of being merged.

val merge : [< value ] -> [< value ] -> value

Merges two compatible JSON values. Merges `Null with any JSON value. Merges two deeply equal values together. Merges two objects by merging their common fields and adding all the others. Merges two arrays by merging their common cells pairwise and adding the remaining ones if one array is bigger than the other. May throw Cannot_merge.

Errors

exception Cannot_merge of path

When two incompatible objects are unsuccessfully merged. Comes with the path to the first incompatibility encountered.

exception Illegal_pointer_notation of string * int * string

An path litteral could not be parsed. Comes with the original string, the position and an explanation.

exception Unsupported_path_item of path_item * string

An operation was given a path containing an unsupported construct. Comes with an explanation as its second argument.

val print_error : 
  ?print_unknown:(Format.formatter -> exn -> unit) ->
  Format.formatter ->
  exn ->
  unit

Produces a human readable version of an error.

YoJSON Compatibility

type yojson = [

| `Bool of bool
(*
A JS boolean true of false.
*)
| `Assoc of (string * yojson) list
(*
JSON object.
*)
| `Float of float
(*
A floating point number (double precision).
*)
| `Int of int
(*
A number without decimal point or exponent.
*)
| `Intlit of string
(*
A number without decimal point or exponent, preserved as string.
*)
| `List of yojson list
(*
A JS array.
*)
| `Null
(*
The null constant.
*)
| `String of string
(*
An UTF-8 encoded string.
*)
| `Tuple of yojson list
(*
A tuple (non-standard). Syntax: ("abc", 123).
*)
| `Variant of string * yojson option
(*
A variant (non-standard). Syntax: <"Foo"> or <"Bar": 123>.
*)

]

A JSON value compatible with Yojson.Safe.json. Provided only for compatibility. See converters

val from_yojson : [< yojson ] -> [> value ]

Conversion helper.

val to_yojson : [< value ] -> [> yojson ]