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(** Hub endpoints for real-time notifications.
7
8 Hubs describe endpoints that can be used to subscribe to real-time
9 notifications of changes to the feed. This is an optional and rarely-used
10 feature of JSON Feed, primarily for feeds that update frequently.
11
12 @see <https://www.jsonfeed.org/version/1.1/> JSON Feed Specification *)
13
14
15(** The type representing a hub endpoint. *)
16type t
17
18
19(** {1 Unknown Fields} *)
20
21module Unknown : sig
22 type t = (string * Jsont.json) list
23 (** Unknown/unrecognized JSON object members.
24 Useful for preserving fields 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
33
34(** {1 Jsont Type} *)
35
36val jsont : t Jsont.t
37(** Declarative JSON type for hubs.
38
39 Maps JSON objects with "type" and "url" fields (both required). *)
40
41
42(** {1 Construction} *)
43
44val create : type_:string -> url:string -> unit -> t
45(** [create ~type_ ~url ()] creates a hub object.
46
47 @param type_ The type of hub protocol (e.g., ["rssCloud"], ["WebSub"])
48 @param url The URL endpoint for the hub
49
50 {b Example:}
51 {[
52 let hub = Hub.create
53 ~type_:"WebSub"
54 ~url:"https://pubsubhubbub.appspot.com/" ()
55 ]} *)
56
57val make :
58 type_:string -> url:string ->
59 ?unknown:Unknown.t -> unit -> t
60(** [make] is like {!create} but allows setting unknown fields. *)
61
62
63(** {1 Accessors} *)
64
65val type_ : t -> string
66(** [type_ t] returns the hub's protocol type. *)
67
68val url : t -> string
69(** [url t] returns the hub's endpoint URL. *)
70
71val unknown : t -> Unknown.t
72(** [unknown t] returns unrecognized fields from the JSON. *)
73
74
75(** {1 Comparison} *)
76
77val equal : t -> t -> bool
78(** [equal a b] tests equality between two hubs. *)
79
80
81(** {1 Pretty Printing} *)
82
83val pp : Format.formatter -> t -> unit
84(** [pp ppf t] pretty prints a hub to the formatter.
85
86 The output is human-readable and suitable for debugging.
87
88 {b Example output:}
89 {v WebSub: https://pubsubhubbub.appspot.com/ v} *)