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(** 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
14type t
15(** The type representing an author. *)
16
17(** {1 Unknown Fields} *)
18
19module Unknown : sig
20 type t = (string * Jsont.json) list
21 (** Unknown/unrecognized JSON object members. Useful for preserving fields
22 from custom extensions or future spec versions. *)
23
24 val empty : t
25 (** [empty] is the empty list of unknown fields. *)
26
27 val is_empty : t -> bool
28 (** [is_empty u] returns [true] if there are no unknown fields. *)
29end
30
31(** {1 Jsont Type} *)
32
33val jsont : t Jsont.t
34(** Declarative JSON type for authors.
35
36 Maps JSON objects with optional "name", "url", and "avatar" fields. At least
37 one field must be present during decoding. *)
38
39(** {1 Construction} *)
40
41val create :
42 ?name:string ->
43 ?url:string ->
44 ?avatar:string ->
45 ?unknown:Unknown.t ->
46 unit ->
47 t
48(** [create ?name ?url ?avatar ?unknown ()] creates an author.
49
50 At least one of the optional parameters must be provided, otherwise the
51 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
56 URL of the author's avatar image (should be square, 512x512 or larger)
57 @param unknown Unknown/custom fields for extensions (default: empty)
58
59 {b Examples:}
60 {[
61 let author = Author.create ~name:"Jane Doe" ()
62 let author = Author.create ~name:"Jane Doe" ~url:"https://janedoe.com" ()
63
64 let author =
65 Author.create ~name:"Jane Doe" ~url:"https://janedoe.com"
66 ~avatar:"https://janedoe.com/avatar.png" ()
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(** {1 Predicates} *)
84
85val is_valid : t -> bool
86(** [is_valid t] checks if the author has at least one field set.
87
88 This should always return [true] for authors created via {!create}, but may
89 be useful when parsing from external sources. *)
90
91(** {1 Comparison} *)
92
93val equal : t -> t -> bool
94(** [equal a b] tests equality between two authors. *)
95
96(** {1 Pretty Printing} *)
97
98val pp : Format.formatter -> t -> unit
99(** [pp ppf t] pretty prints an author to the formatter.
100
101 The output is human-readable and suitable for debugging.
102
103 {b Example output:}
104 {v Jane Doe <https://janedoe.com> v} *)