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