OCaml library for JSONfeed parsing and creation
anil.recoil.org
1(*---------------------------------------------------------------------------
2 Copyright (c) 2024 Anil Madhavapeddy. All rights reserved.
3 SPDX-License-Identifier: ISC
4 ---------------------------------------------------------------------------*)
5
6(** JSON Feed format parser and serializer using Jsont and Bytesrw.
7
8 @see <https://www.jsonfeed.org/version/1.1/> JSON Feed Specification *)
9
10
11(** The type representing a complete JSON Feed. *)
12type t
13
14
15(** {1 Unknown Fields} *)
16
17module Unknown : sig
18 type t = (string * Jsont.json) list
19 (** Unknown/unrecognized JSON object members.
20 Useful for preserving fields from custom extensions or future spec versions. *)
21
22 val empty : t
23 (** [empty] is the empty list of unknown fields. *)
24
25 val is_empty : t -> bool
26 (** [is_empty u] returns [true] if there are no unknown fields. *)
27end
28
29
30(** {1 Jsont Type} *)
31
32val jsont : t Jsont.t
33(** Declarative JSON type for JSON feeds.
34
35 Maps the complete JSON Feed 1.1 specification including all required
36 and optional fields. *)
37
38
39(** {1 Construction} *)
40
41val create :
42 title:string ->
43 ?home_page_url:string ->
44 ?feed_url:string ->
45 ?description:string ->
46 ?user_comment:string ->
47 ?next_url:string ->
48 ?icon:string ->
49 ?favicon:string ->
50 ?authors:Author.t list ->
51 ?language:string ->
52 ?expired:bool ->
53 ?hubs:Hub.t list ->
54 items:Item.t list ->
55 unit ->
56 t
57
58val make :
59 title:string ->
60 ?home_page_url:string ->
61 ?feed_url:string ->
62 ?description:string ->
63 ?user_comment:string ->
64 ?next_url:string ->
65 ?icon:string ->
66 ?favicon:string ->
67 ?authors:Author.t list ->
68 ?language:string ->
69 ?expired:bool ->
70 ?hubs:Hub.t list ->
71 items:Item.t list ->
72 ?unknown:Unknown.t ->
73 unit ->
74 t
75
76
77(** {1 Accessors} *)
78
79val version : t -> string
80val title : t -> string
81val home_page_url : t -> string option
82val feed_url : t -> string option
83val description : t -> string option
84val user_comment : t -> string option
85val next_url : t -> string option
86val icon : t -> string option
87val favicon : t -> string option
88val authors : t -> Author.t list option
89val language : t -> string option
90val expired : t -> bool option
91val hubs : t -> Hub.t list option
92val items : t -> Item.t list
93val unknown : t -> Unknown.t
94
95
96(** {1 Encoding and Decoding with Bytesrw} *)
97
98val decode :
99 ?layout:bool -> ?locs:bool -> ?file:string ->
100 Bytesrw.Bytes.Reader.t -> (t, Jsont.Error.t) result
101(** [decode r] decodes a JSON Feed from bytesrw reader [r].
102
103 @param layout Preserve whitespace for round-tripping (default: false)
104 @param locs Track locations for better error messages (default: false)
105 @param file Source file name for error reporting *)
106
107val decode_string :
108 ?layout:bool -> ?locs:bool -> ?file:string ->
109 string -> (t, Jsont.Error.t) result
110(** [decode_string s] decodes a JSON Feed from string [s]. *)
111
112val encode :
113 ?format:Jsont.format -> ?number_format:Jsont.number_format ->
114 t -> eod:bool -> Bytesrw.Bytes.Writer.t -> (unit, Jsont.Error.t) result
115(** [encode feed w] encodes [feed] to bytesrw writer [w].
116
117 @param format Output formatting: [Jsont.Minify] or [Jsont.Indent] (default: Minify)
118 @param number_format Printf format for numbers (default: "%.16g")
119 @param eod Write end-of-data marker *)
120
121val encode_string :
122 ?format:Jsont.format -> ?number_format:Jsont.number_format ->
123 t -> (string, Jsont.Error.t) result
124(** [encode_string feed] encodes [feed] to a string. *)
125
126
127(** {1 Convenience Functions} *)
128
129val of_string : string -> (t, Jsont.Error.t) result
130(** Alias for [decode_string] with default options. *)
131
132val to_string : ?minify:bool -> t -> (string, Jsont.Error.t) result
133(** [to_string feed] encodes [feed] to string.
134 @param minify Use compact format (true) or indented (false, default) *)
135
136
137(** {1 Validation} *)
138
139val validate : t -> (unit, string list) result
140(** [validate feed] validates the feed structure.
141 Checks for unique item IDs, valid content, etc. *)
142
143
144(** {1 Comparison} *)
145
146val equal : t -> t -> bool
147(** [equal a b] tests equality between two feeds. *)
148
149
150(** {1 Pretty Printing} *)
151
152val pp : Format.formatter -> t -> unit
153val pp_summary : Format.formatter -> t -> unit
154
155
156(** {1 Submodules} *)
157
158module Rfc3339 = Rfc3339
159module Cito = Cito
160module Author = Author
161module Attachment = Attachment
162module Hub = Hub
163module Reference = Reference
164module Item = Item