OCaml library for JSONfeed parsing and creation
anil.recoil.org
1(** Attachments for JSON Feed items.
2
3 An attachment represents an external resource related to a feed item,
4 such as audio files for podcasts, video files, or other downloadable content.
5 Attachments with identical titles indicate alternate formats of the same resource.
6
7 @see <https://www.jsonfeed.org/version/1.1/> JSON Feed Specification *)
8
9
10(** The type representing an attachment. *)
11type t
12
13
14(** {1 Construction} *)
15
16(** [create ~url ~mime_type ?title ?size_in_bytes ?duration_in_seconds ()]
17 creates an attachment object.
18
19 @param url The location of the attachment (required)
20 @param mime_type The MIME type of the attachment, e.g. ["audio/mpeg"] (required)
21 @param title The name of the attachment; identical titles indicate alternate formats
22 of the same resource
23 @param size_in_bytes The size of the attachment file in bytes
24 @param duration_in_seconds The duration of the attachment in seconds (for audio/video)
25
26 {b Examples:}
27 {[
28 (* Simple attachment *)
29 let att = Attachment.create
30 ~url:"https://example.com/episode.mp3"
31 ~mime_type:"audio/mpeg" ()
32
33 (* Podcast episode with metadata *)
34 let att = Attachment.create
35 ~url:"https://example.com/episode.mp3"
36 ~mime_type:"audio/mpeg"
37 ~title:"Episode 42"
38 ~size_in_bytes:15_728_640L
39 ~duration_in_seconds:1800 ()
40
41 (* Alternate format (same title indicates same content) *)
42 let att2 = Attachment.create
43 ~url:"https://example.com/episode.aac"
44 ~mime_type:"audio/aac"
45 ~title:"Episode 42"
46 ~size_in_bytes:12_582_912L
47 ~duration_in_seconds:1800 ()
48 ]} *)
49val create :
50 url:string ->
51 mime_type:string ->
52 ?title:string ->
53 ?size_in_bytes:int64 ->
54 ?duration_in_seconds:int ->
55 unit ->
56 t
57
58
59(** {1 Accessors} *)
60
61(** [url t] returns the attachment's URL. *)
62val url : t -> string
63
64(** [mime_type t] returns the attachment's MIME type. *)
65val mime_type : t -> string
66
67(** [title t] returns the attachment's title, if set. *)
68val title : t -> string option
69
70(** [size_in_bytes t] returns the attachment's size in bytes, if set. *)
71val size_in_bytes : t -> int64 option
72
73(** [duration_in_seconds t] returns the attachment's duration, if set. *)
74val duration_in_seconds : t -> int option
75
76
77(** {1 Comparison} *)
78
79(** [equal a b] tests equality between two attachments. *)
80val equal : t -> t -> bool
81
82
83(** {1 Pretty Printing} *)
84
85(** [pp ppf t] pretty prints an attachment to the formatter.
86
87 The output is human-readable and suitable for debugging.
88
89 {b Example output:}
90 {v episode.mp3 (audio/mpeg, 15.0 MB, 30m0s) v} *)
91val pp : Format.formatter -> t -> unit