simdjson bindings with streaming support
gdiazlo.tngl.sh
1(** Codecs for decoding/encoding JSON.
2
3 A codec ['a t] contains:
4
5 - a decoder from {!Simdjsont.Raw.element} to ['a]
6 - an encoder from ['a] to JSON written into a buffer
7
8 See the {!Obj} submodule for building codecs for JSON objects. *)
9
10type error = { path : string list; message : string }
11(** Error value used by {!Decode_error}.
12
13 - [path] is a list of strings accumulated during decoding.
14 - [message] is a human-readable error message. *)
15
16exception Decode_error of error
17(** Exception raised by decoders. *)
18
19val error_to_string : error -> string
20(** Convert an {!error} to a string. *)
21
22type 'a t
23(** A codec for values of type ['a]. *)
24
25val decode_string : 'a t -> string -> ('a, string) result
26(** Decode a JSON string using the given codec. *)
27
28val decode_string_exn : 'a t -> string -> 'a
29(** Like {!decode_string}, but raises on error. *)
30
31val decode_element : 'a t -> Simdjsont_raw.element -> ('a, string) result
32
33val encode_to_buffer : 'a t -> 'a -> Buffer.t
34(** Encode a value to a fresh buffer using the given codec. *)
35
36val encode_string : 'a t -> 'a -> string
37(** Encode a value to a JSON string using the given codec. *)
38
39val to_json : 'a t -> 'a -> Simdjsont_json.t
40(** Convert a value to JSON AST using the given codec. *)
41
42val null : unit t
43(** Codec for the JSON [null] value. *)
44
45val bool : bool t
46(** Codec for JSON booleans. *)
47
48val int : int t
49(** Codec for JSON integers mapped to OCaml [int]. *)
50
51val int64 : int64 t
52(** Codec for JSON integers mapped to OCaml [int64]. *)
53
54val float : float t
55(** Codec for JSON numbers mapped to OCaml [float]. *)
56
57val string : string t
58(** Codec for JSON strings. *)
59
60val list : 'a t -> 'a list t
61(** Codec for JSON arrays mapped to OCaml lists. *)
62
63val array : 'a t -> 'a array t
64(** Codec for JSON arrays mapped to OCaml arrays. *)
65
66val optional : 'a t -> 'a option t
67(** Codec for optional values. *)
68
69val map : ('a -> 'b) -> ('b -> 'a) -> 'a t -> 'b t
70(** Transform a codec using conversion functions. *)
71
72module Obj : sig
73 (** Builder for JSON objects.
74
75 The builder API is driven by a constructor function provided to {!field},
76 then extended with fields using {!mem} and {!opt_mem}, and finalized with
77 {!finish}. *)
78
79 type ('o, 'dec) builder
80 (** Builder state for an object codec.
81
82 ['o] is the resulting OCaml type. *)
83
84 val field : 'a -> ('o, 'a) builder
85 (** Start building an object codec from a constructor function. *)
86
87 val mem :
88 string ->
89 'a t ->
90 enc:('o -> 'a) ->
91 ('o, 'a -> 'b) builder ->
92 ('o, 'b) builder
93 (** Add a required object member. *)
94
95 val opt_mem :
96 string ->
97 'a t ->
98 enc:('o -> 'a option) ->
99 ('o, 'a option -> 'b) builder ->
100 ('o, 'b) builder
101 (** Add an optional object member. *)
102
103 val finish : ('o, 'o) builder -> 'o t
104 (** Finish building an object codec. *)
105end
106
107val value : Simdjsont_json.t t
108(** Codec for {!Simdjsont.Json.t}. *)