OCaml library for JSONfeed parsing and creation
anil.recoil.org
1(*---------------------------------------------------------------------------
2 Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.
3 SPDX-License-Identifier: ISC
4 ---------------------------------------------------------------------------*)
5
6(** Feed items in a JSON Feed.
7
8 An item represents a single entry in a feed, such as a blog post, podcast
9 episode, or microblog entry. Each item must have a unique identifier and
10 content.
11
12 @see <https://www.jsonfeed.org/version/1.1/> JSON Feed Specification *)
13
14type t
15(** The type representing a feed item. *)
16
17type content = [ `Html of string | `Text of string | `Both of string * string ]
18(** Content representation for an item.
19
20 The JSON Feed specification requires that each item has at least one form of
21 content. This type enforces that requirement at compile time.
22
23 - [`Html s]: Item has HTML content only
24 - [`Text s]: Item has plain text content only
25 - [`Both (html, text)]: Item has both HTML and plain text versions *)
26
27(** {1 Unknown Fields} *)
28
29module Unknown : sig
30 type t = (string * Jsont.json) list
31 (** Unknown/unrecognized JSON object members. Useful for preserving fields
32 from custom extensions or future spec versions. *)
33
34 val empty : t
35 (** [empty] is the empty list of unknown fields. *)
36
37 val is_empty : t -> bool
38 (** [is_empty u] returns [true] if there are no unknown fields. *)
39end
40
41(** {1 Jsont Type} *)
42
43val jsont : t Jsont.t
44(** Declarative JSON type for feed items.
45
46 Maps JSON objects with "id" (required), content fields, and various optional
47 metadata. The content must have at least one of "content_html" or
48 "content_text". *)
49
50(** {1 Construction} *)
51
52val create :
53 id:string ->
54 content:content ->
55 ?url:string ->
56 ?external_url:string ->
57 ?title:string ->
58 ?summary:string ->
59 ?image:string ->
60 ?banner_image:string ->
61 ?date_published:Ptime.t ->
62 ?date_modified:Ptime.t ->
63 ?authors:Author.t list ->
64 ?tags:string list ->
65 ?language:string ->
66 ?attachments:Attachment.t list ->
67 ?references:Reference.t list ->
68 ?unknown:Unknown.t ->
69 unit ->
70 t
71
72(** {1 Accessors} *)
73
74val id : t -> string
75val content : t -> content
76val content_html : t -> string option
77val content_text : t -> string option
78val url : t -> string option
79val external_url : t -> string option
80val title : t -> string option
81val summary : t -> string option
82val image : t -> string option
83val banner_image : t -> string option
84val date_published : t -> Ptime.t option
85val date_modified : t -> Ptime.t option
86val authors : t -> Author.t list option
87val tags : t -> string list option
88val language : t -> string option
89val attachments : t -> Attachment.t list option
90val references : t -> Reference.t list option
91val unknown : t -> Unknown.t
92
93(** {1 Comparison} *)
94
95val equal : t -> t -> bool
96val compare : t -> t -> int
97
98(** {1 Pretty Printing} *)
99
100val pp : Format.formatter -> t -> unit
101val pp_summary : Format.formatter -> t -> unit