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