Module Jsont.Obj

Mapping JSON objects.

This module allows to describe JSON objects. See a simple example.

Object maps

type ('o, 'dec) map

The type for mapping JSON objects to values of type 'o. The 'dec type is used to construct 'o from members see mem.

val kind : ('o, _) map -> string

kind m is the kind of object represented by 'o.

val map : ?kind:string -> ?doc:string -> 'dec -> ('o, 'dec) map

map dec is an empty JSON object decoded by dec.

  • kind names the entities represented by type 'o. Defaults to "".
  • doc is a documentation string for kind. Defaults to "".
  • dec is a constructor eventually returning a value of type 'o to be saturated with calls to mem, case_mem or unknown_keep. This is needed for decoding. Use nodec if the result is only used for encoding.
val map' : ?kind:string -> ?doc:string -> ?enc_meta:(Context.t -> 'o -> Meta.t) -> (Context.t -> Meta.t -> 'dec) -> ('o, 'dec) map

map' dec is like map except you get the full decoding context in dec and enc_meta is used to recover it on encoding.

val nodec : ?kind:string -> ?doc:string -> ?enc_meta:(Context.t -> 'o -> Meta.t) -> unit -> ('o, 'a) map

nodec () is like map' but can only be used for encoding.

val finish : ('o, 'o) map -> 'o t

finish m is a JSON type for objects mapped by m. Raises Invalid_argument if m describes a member name more than once.

val unfinish : 'o t -> ('o, 'o) map

unfinish t is the object description of t. Raises Invalid_argument if t is not the result of finish.

Members

val mem : ?doc:string -> ?dec_absent:'a -> ?enc:('o -> 'a) -> ?enc_meta:('a -> Meta.t) -> ?enc_omit:('a -> bool) -> string -> 'a t -> ('o, 'a -> 'b) map -> ('o, 'b) map

mem ?doc ?omit ?absent ?proj n t map is a member named n of type t for an object of type 'o being constructed by map.

  • doc is a documentation string for the member. Defaults to "".
  • dec_absent, if specified, is the value used for the decoding direction when the member named n is missing. If unspecified decoding errors when the member is absent. See also opt_mem and this example.
  • enc is used to project the member's value from the object representation 'o for encoding to JSON. It can be omitted if the result is only used for decoding.
  • enc_omit is for the encoding direction. If the member value returns true the member is omited in the JSON. Defaults to Fun.const false. See this example.
val opt_mem : ?doc:string -> ?enc:('o -> 'a option) -> string -> 'a t -> ('o, 'a option -> 'b) map -> ('o, 'b) map

opt_mem ?doc ?enc n t map is mem ?doc ?enc ~dec_absent:None ~enc_omit:Option.is_none n (some t) map. A shortcut to represent optional members with option values.

module Mem : sig ... end

Case objects

This is for dealing with JSON object types or classes. See this example.

module Case : sig ... end

Case objects.

val case_mem : ?doc:string -> ?dec_absent:'tag -> ?tag_compare:('tag -> 'tag -> int) -> ?enc:('o -> 'cases) -> ?enc_omit:('tag -> bool) -> ?enc_case:('cases -> ('cases, 'tag) Case.value) -> string -> 'tag t -> ('cases, 'tag) Case.t list -> ('o, 'cases -> 'a) map -> ('o, 'a) map

case_mem n t parts map is mostly like mem except the member n selects an object representation according to the member value of type t:

  • doc is a documentation string for the member. Defaults to "".
  • dec_absent, if specified, is the case value used for the decoding direction when the case member named n is missing. If unspecified decoding errors when the member is absent.
  • enc is used to project the value in which cases are stored from the object representation 'o for encoding to JSON. It can be omitted if the result is only used for decoding.
  • enc_case determines the actual case value from the value returned by enc.
  • parts enumerates all the cases, it is needed for decoding.

map, n and the object maps of cases must declare disjoint member names otherwise Invalid_argument is raised on finish.

Unknown members

These functions define the behaviour on unknown members. They cannot be used on an object map value on which case_mem was called and can be specified only once otherwise Invalid_argument is raised. By default unknown members are skipped.

module Mems : sig ... end

Uniform members.

val skip_unknown : ('o, 'dec) map -> ('o, 'dec) map

skip_unknown m makes m skip unknown members. This is the default, no need to specify it.

val error_unknown : ('o, 'dec) map -> ('o, 'dec) map

error_unknown m makes m error on unknown members. See this example.

val keep_unknown : ?enc:('o -> 'mems) -> ('mems, _, _) Mems.map -> ('o, 'mems -> 'a) map -> ('o, 'a) map

keep_unknown mems m makes m keep unknown member with mems. See this this example. TODO describe this can be used

JSON types

val as_string_map : ?kind:string -> ?doc:string -> 'a t -> 'a Stdlib.Map.Make(Stdlib.String).t t

as_string_map t maps object to key-value maps of type t. See also Mems.string_map.

val ignore : unit t

ignore ignores JSON objects on decoding and errors on encoding.