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 : ?name:string -> ?url:string -> ?avatar:string -> unit -> t
46(** [create ?name ?url ?avatar ()] creates an author.
47
48 At least one of the optional parameters must be provided, otherwise
49 the function will raise [Invalid_argument].
50
51 @param name The author's name
52 @param url URL of the author's website or profile
53 @param avatar URL of the author's avatar image (should be square, 512x512 or larger)
54
55 {b Examples:}
56 {[
57 let author = Author.create ~name:"Jane Doe" ()
58 let author = Author.create ~name:"Jane Doe" ~url:"https://janedoe.com" ()
59 let author = Author.create
60 ~name:"Jane Doe"
61 ~url:"https://janedoe.com"
62 ~avatar:"https://janedoe.com/avatar.png" ()
63 ]} *)
64
65val make :
66 ?name:string -> ?url:string -> ?avatar:string ->
67 ?unknown:Unknown.t -> unit -> t
68(** [make] is like {!create} but allows setting unknown fields.
69 Useful when round-tripping JSON with custom extensions. *)
70
71
72(** {1 Accessors} *)
73
74val name : t -> string option
75(** [name t] returns the author's name, if set. *)
76
77val url : t -> string option
78(** [url t] returns the author's URL, if set. *)
79
80val avatar : t -> string option
81(** [avatar t] returns the author's avatar URL, if set. *)
82
83val unknown : t -> Unknown.t
84(** [unknown t] returns unrecognized fields from the JSON. *)
85
86
87(** {1 Predicates} *)
88
89val is_valid : t -> bool
90(** [is_valid t] checks if the author has at least one field set.
91
92 This should always return [true] for authors created via {!create},
93 but may be useful when parsing from external sources. *)
94
95
96(** {1 Comparison} *)
97
98val equal : t -> t -> bool
99(** [equal a b] tests equality between two authors. *)
100
101
102(** {1 Pretty Printing} *)
103
104val pp : Format.formatter -> t -> unit
105(** [pp ppf t] pretty prints an author to the formatter.
106
107 The output is human-readable and suitable for debugging.
108
109 {b Example output:}
110 {v Jane Doe <https://janedoe.com> v} *)