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(** Author information for JSON Feed items and feeds.
7
8 An author object provides information about the creator of a feed or item.
9 According to the JSON Feed 1.1 specification, at least one field must be
10 present when an author object is included.
11
12 @see <https://www.jsonfeed.org/version/1.1/> JSON Feed Specification *)
13
14
15(** The type representing an author. *)
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 authors.
38
39 Maps JSON objects with optional "name", "url", and "avatar" fields.
40 At least one field must be present during decoding. *)
41
42
43(** {1 Construction} *)
44
45val create :
46 ?name:string -> ?url:string -> ?avatar:string ->
47 ?unknown:Unknown.t -> unit -> t
48(** [create ?name ?url ?avatar ?unknown ()] creates an author.
49
50 At least one of the optional parameters must be provided, otherwise
51 the function will raise [Invalid_argument].
52
53 @param name The author's name
54 @param url URL of the author's website or profile
55 @param avatar URL of the author's avatar image (should be square, 512x512 or larger)
56 @param unknown Unknown/custom fields for extensions (default: empty)
57
58 {b Examples:}
59 {[
60 let author = Author.create ~name:"Jane Doe" ()
61 let author = Author.create ~name:"Jane Doe" ~url:"https://janedoe.com" ()
62 let author = Author.create
63 ~name:"Jane Doe"
64 ~url:"https://janedoe.com"
65 ~avatar:"https://janedoe.com/avatar.png" ()
66 ]} *)
67
68
69(** {1 Accessors} *)
70
71val name : t -> string option
72(** [name t] returns the author's name, if set. *)
73
74val url : t -> string option
75(** [url t] returns the author's URL, if set. *)
76
77val avatar : t -> string option
78(** [avatar t] returns the author's avatar URL, if set. *)
79
80val unknown : t -> Unknown.t
81(** [unknown t] returns unrecognized fields from the JSON. *)
82
83
84(** {1 Predicates} *)
85
86val is_valid : t -> bool
87(** [is_valid t] checks if the author has at least one field set.
88
89 This should always return [true] for authors created via {!create},
90 but may be useful when parsing from external sources. *)
91
92
93(** {1 Comparison} *)
94
95val equal : t -> t -> bool
96(** [equal a b] tests equality between two authors. *)
97
98
99(** {1 Pretty Printing} *)
100
101val pp : Format.formatter -> t -> unit
102(** [pp ppf t] pretty prints an author to the formatter.
103
104 The output is human-readable and suitable for debugging.
105
106 {b Example output:}
107 {v Jane Doe <https://janedoe.com> v} *)