anil.recoil.org
OCaml library for JSONfeed parsing and creation
docs and format
+125
-4
lib/jsonfeed.mli
+125
-4
lib/jsonfeed.mli
···
10
10
type t
11
11
(** The type representing a complete JSON Feed. *)
12
12
13
-
(** {1 Jsont Type} *)
14
-
15
13
val jsont : t Jsont.t
16
-
(** Declarative JSON type for JSON feeds.
14
+
(** Declarative type that describes the structure of JSON Feeds.
17
15
18
16
Maps the complete JSON Feed 1.1 specification including all required and
19
17
optional fields. *)
20
18
21
19
module Unknown : sig
22
20
type t = (string * Jsont.json) list
23
-
(** Unknown/unrecognized JSON object members. Useful for preserving fields
21
+
(** Unknown or unrecognized JSON object members. Useful for preserving fields
24
22
from custom extensions or future spec versions. *)
25
23
26
24
val empty : t
···
29
27
val is_empty : t -> bool
30
28
(** [is_empty u] returns [true] if there are no unknown fields. *)
31
29
end
30
+
31
+
(** {1 Construction} *)
32
32
33
33
val create :
34
34
title:string ->
···
47
47
?unknown:Unknown.t ->
48
48
unit ->
49
49
t
50
+
(** [create ~title ~items ()] creates a new JSON Feed.
51
+
52
+
@param title
53
+
The name of the feed. Required field that should be plain text, not HTML.
54
+
@param home_page_url
55
+
The URL of the resource that the feed describes. This resource may or may
56
+
not actually be a "home" page, but it should be an HTML page. If a feed is
57
+
for a podcast, for instance, the home_page_url would be the URL for the
58
+
podcast's website.
59
+
@param feed_url
60
+
The URL of the feed itself. This is the URL that was requested to get this
61
+
JSON Feed response. Helps feed readers to determine when they're being
62
+
redirected. Strongly recommended for feeds.
63
+
@param description
64
+
A plain text description of the feed, for human consumption. May contain
65
+
some formatting (like newlines).
66
+
@param user_comment
67
+
A description of the purpose of the feed, for a person looking at the raw
68
+
JSON. This is for the publisher's use only, not intended to be displayed
69
+
to the user.
70
+
@param next_url
71
+
The URL of a feed that provides the next n items, where n is determined by
72
+
the publisher. Used for pagination. A feed reader may continue to request
73
+
the URLs in next_url until it reaches a feed without a next_url.
74
+
@param icon
75
+
The URL of an image for the feed suitable to be used in a timeline, much
76
+
the way an avatar might be used. Should be square and relatively large -
77
+
such as 512 x 512 pixels - and may be cropped to a circle or rounded
78
+
corners. Should not be transparent.
79
+
@param favicon
80
+
The URL of an image for the feed suitable to be used in a source list.
81
+
Should be square and relatively small - such as 64 x 64 pixels. Should not
82
+
be transparent.
83
+
@param authors
84
+
Specifies one or more feed authors. The author object has several members
85
+
(name, url, avatar) which are all optional, but at least one must be
86
+
present for the object to be valid.
87
+
@param language
88
+
The primary language for the feed in RFC 5646 format. The value can be a
89
+
language tag such as "en" or "en-US", or a language-region combination.
90
+
@param expired
91
+
Whether or not the feed is finished - that is, whether or not it will ever
92
+
update again. A feed for a temporary event, like an instance of a
93
+
conference, may expire. If the value is [true], feed readers may stop
94
+
checking for updates.
95
+
@param hubs
96
+
Endpoints that can be used to subscribe to real-time notifications from
97
+
the publisher of this feed. Each hub object has a type (such as "rssCloud"
98
+
or "WebSub") and url.
99
+
@param items
100
+
The items in the feed. Required field, though it may be an empty array.
101
+
@param unknown
102
+
Unknown JSON object members preserved from parsing. Useful for custom
103
+
extensions. *)
104
+
105
+
(** {1 Accessors} *)
50
106
51
107
val version : t -> string
108
+
(** [version feed] returns the URL of the version of the format the feed uses.
109
+
This will always be "https://jsonfeed.org/version/1.1" for feeds created
110
+
with this library. This is a required field in the JSON Feed spec. *)
111
+
52
112
val title : t -> string
113
+
(** [title feed] returns the name of the feed. This is plain text and should not
114
+
contain HTML. This is a required field. *)
115
+
53
116
val home_page_url : t -> string option
117
+
(** [home_page_url feed] returns the URL of the resource that the feed
118
+
describes. This resource may or may not actually be a "home" page, but it
119
+
should be an HTML page. For instance, if a feed is for a podcast, the
120
+
home_page_url would be the URL for the podcast's website. *)
121
+
54
122
val feed_url : t -> string option
123
+
(** [feed_url feed] returns the URL of the feed itself. This should be the URL
124
+
that was requested to get this JSON Feed response. It helps feed readers
125
+
determine when they're being redirected. This is strongly recommended for
126
+
feeds. *)
127
+
55
128
val description : t -> string option
129
+
(** [description feed] returns a plain text description of the feed, for human
130
+
consumption. This field may contain some formatting such as newlines. *)
131
+
56
132
val user_comment : t -> string option
133
+
(** [user_comment feed] returns a description of the purpose of the feed, for a
134
+
person looking at the raw JSON. This is for the publisher's use only and is
135
+
not intended to be displayed to end users. *)
136
+
57
137
val next_url : t -> string option
138
+
(** [next_url feed] returns the URL of a feed that provides the next n items,
139
+
where n is determined by the publisher. This is used for pagination. A feed
140
+
reader may continue to request the URLs in next_url until it reaches a feed
141
+
without a next_url. *)
142
+
58
143
val icon : t -> string option
144
+
(** [icon feed] returns the URL of an image for the feed suitable to be used in
145
+
a timeline, much the way an avatar might be used. It should be square and
146
+
relatively large (such as 512 x 512 pixels) and may be cropped to a circle
147
+
or rounded corners by feed readers. It should not be transparent. *)
148
+
59
149
val favicon : t -> string option
150
+
(** [favicon feed] returns the URL of an image for the feed suitable to be used
151
+
in a source list. It should be square and relatively small (such as 64 x 64
152
+
pixels) and should not be transparent. *)
153
+
60
154
val authors : t -> Author.t list option
155
+
(** [authors feed] returns the feed authors. Each author object has several
156
+
members (name, url, avatar) which are all optional, but at least one must be
157
+
present for the object to be valid. If a feed has multiple authors, they
158
+
should all be listed here. *)
159
+
61
160
val language : t -> string option
161
+
(** [language feed] returns the primary language for the feed in RFC 5646
162
+
format. The value can be a language tag such as "en" or "en-US", or a
163
+
language-region combination. This field helps feed readers present the feed
164
+
in the appropriate language. *)
165
+
62
166
val expired : t -> bool option
167
+
(** [expired feed] returns whether the feed is finished - that is, whether it
168
+
will ever update again. A feed for a temporary event, like an instance of a
169
+
conference, may expire. If the value is [Some true], feed readers may stop
170
+
checking for updates. *)
171
+
63
172
val hubs : t -> Hub.t list option
173
+
(** [hubs feed] returns endpoints that can be used to subscribe to real-time
174
+
notifications from the publisher of this feed. Each hub object has a type
175
+
(such as "rssCloud" or "WebSub") and a url. Feed readers can use these to
176
+
get immediate updates when new items are published. *)
177
+
64
178
val items : t -> Item.t list
179
+
(** [items feed] returns the array of items in the feed. This is a required
180
+
field, though it may be an empty list. Items represent the individual
181
+
entries in the feed - blog posts, podcast episodes, microblog posts, etc. *)
182
+
65
183
val unknown : t -> Unknown.t
184
+
(** [unknown feed] returns any unknown JSON object members that were preserved
185
+
during parsing. This is useful for custom extensions or fields from future
186
+
versions of the spec. *)
66
187
67
188
(** {1 Encoding and Decoding} *)
68
189