Module Json_query

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 = [
  1. | `Field of string
    (*

    A field in an object.

    *)
  2. | `Index of int
    (*

    An index in an array.

    *)
  3. | `Star
    (*

    Any / every field or index.

    *)
  4. | `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 -> Json_data_encoding_stdlib.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 -> Json_data_encoding_stdlib.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

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.

This function works with JSON data represented in the Json_repr.ezjsonm format. See functor Make for using another representation.

val query_all : path -> Json_repr.ezjsonm -> Json_repr.ezjsonm list

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

This function works with JSON data represented in the Json_repr.ezjsonm format. See functor Make for using another representation.

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.

This function works with JSON data represented in the Json_repr.ezjsonm format. See functor Make for using another representation.

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.

This function works with JSON data represented in the Json_repr.ezjsonm format. See functor Make for using another representation.

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.

This function works with JSON data represented in the Json_repr.ezjsonm format. See functor Make for using another representation.

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:(Json_data_encoding_stdlib.Format.formatter -> exn -> unit) -> Json_data_encoding_stdlib.Format.formatter -> exn -> unit

Produces a human readable version of an error.

Advanced interface for using a custom JSON representation

module Make (Repr : Json_repr.Repr) : sig ... end