Module Jsont.Caret

JSON carets

Carets

type pos =
  1. | Before
    (*

    The void before the data indexed by a path.

    *)
  2. | Over
    (*

    The data indexed by a path.

    *)
  3. | After
    (*

    The void after the data indexed by a path.

    *)

The type for caret positions.

type t = Path.t * pos

The type for carets. A path and the caret position.

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

of_string s parses a caret according to the caret syntax .

val pp : t fmt

pp formats carets.

Path & caret end-user syntax

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

A path is a sequence of key and list indexing operations. Applying the path to a JSON value leads to a JSON construct 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 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.

Note. FIXME The syntax has no form of quoting at the moment this means key names can't contain, [, ], or start with a number.