Module Jsont.Path

JSON paths.

Paths are used for keeping track of erroring contexts and for specifying query and update locations.

Indices

type index =
  1. | Mem of string node
    (*

    Indexes the value of the member n of an object.

    *)
  2. | Nth of int node
    (*

    Indexes the value of the nth element of an array. If negative counts the number of elements from the end: -1 is that last element. This may not supported by all operations accepting index values.

    *)

The type for indexing operations on JSON values.

val pp_index : index fmt

pp_index formats indexes.

val pp_index_trace : index fmt

pp_index formats indexes and their location.

Paths

type t

The type for paths, a sequence of indexing operations.

val root : t

root is the root path.

val is_root : t -> bool

is_root p is true iff p is the root path.

val nth : ?meta:Meta.t -> int -> t -> t

nth n p indexes the array indexed by p at index n.

val mem : ?meta:Meta.t -> string -> t -> t

mem n p indexes the object indexed by p at member n.

val rev_indices : t -> index list

rev_indices p are the indices of p in reverse order, the last indexing operation appears first.

val of_string : string -> (t, string) Stdlib.result

of_string s parses a path according to the path syntax.

val pp : t fmt

pp formats paths.

val pp_trace : t fmt

pp_trace formats paths as a stack trace, if not empty.

Carets

module Caret : sig ... end

Carets.

val over : t -> Caret.t

over p is the data at the path p.

val before : t -> Caret.t

before p is the void before the path p.

val after : t -> Caret.t

after p is the void after the path p.

Path & caret syntax

Path and carets provide a way for end users to address JSON and edit locations.

A path is a sequence of member and list indexing operations. Applying the path to a JSON value leads to either a JSON value or nothing if one of the indices does not exist, or an error if ones tries to index a non-indexable value.

A caret is a path and a spatial specification for the JSON construct found by the path. The caret indicates either the void before that JSON construct, the JSON value itself (over) or the void after it.

Here are a few examples of paths and carets, syntactically the charater 'v' is used to denote the caret's insertion point before or after a path. There's no distinction between a path and an over caret.

{
  "ocaml": {
    "libs": ["jsont", "brr", "cmdliner"]
  }
}
ocaml.libs        # value of member "libs" of member "ocaml"
ocaml.v[libs]     # void before the "libs" member
ocaml.[libs]v     # void after "libs" member

ocaml.libs.[0]    # first element of member "libs" of member "ocaml"
ocaml.libs.v[0]   # void before first element
ocaml.libs.[0]v   # void after first element

ocaml.libs.[-1]   # last element of member "libs" of member "ocaml"
ocaml.libs.v[-1]  # before last element (if any)
ocaml.libs.[-1]v  # after last element (if any)

More formally a path is a . seperated list of indices.

An index is written [i]. i can a zero-based list index with negative indices counting from the end of the list (-1 is the last element). Or i can be an object member name n. If there is no ambiguity, the surrounding brackets can be dropped.

A caret is a path whose last index brackets can be prefixed or suffixed by an insertion point, represented by the character 'v'. This respectively denote the void before or after the JSON construct found by the path.

Notes.