package rss

  1. Overview
  2. Docs

The RSS library to read and write RSS 2.0 files.

Reference: RSS 2.0 specification.

Types

type category = {
  1. cat_name : string;
    (*

    A forward-slash-separated string that identifies a hierarchic location in the indicated taxonomy.

    *)
  2. cat_domain : Uri.t option;
    (*

    Identifies a categorization taxonomy.

    *)
}
type image = {
  1. image_url : Uri.t;
    (*

    The URL of a GIF, JPEG or PNG image that represents the channel.

    *)
  2. image_title : string;
    (*

    Description of the image, it's used in the ALT attribute of the HTML <img> tag when the channel is rendered in HTML.

    *)
  3. image_height : int option;
    (*

    Height of the image, in pixels.

    *)
  4. image_width : int option;
    (*

    Width of the image, in pixels.

    *)
  5. image_desc : string option;
    (*

    Text to be included in the "title" attribute of the link formed around the image in the HTML rendering.

    *)
}
type text_input = {
  1. ti_title : string;
    (*

    The label of the Submit button in the text input area.

    *)
  2. ti_desc : string;
    (*

    Explains the text input area.

    *)
  3. ti_name : string;
    (*

    The name of the text object in the text input area.

    *)
}
type enclosure = {
  1. encl_url : Uri.t;
    (*

    URL of the enclosure

    *)
  2. encl_length : int;
    (*

    size in bytes

    *)
  3. encl_type : string;
    (*

    MIME type

    *)
}
type guid =
  1. | Guid_name of string
    (*

    A string that uniquely identifies the item.

    *)
type source = {
  1. src_name : string;
  2. src_url : Uri.t;
}
type cloud = {
  1. cloud_domain : string;
  2. cloud_port : int;
  3. cloud_path : string;
  4. cloud_register_procedure : string;
  5. cloud_protocol : string;
}
type 'a item_t = {
  1. item_title : string option;
    (*

    Optional title

    *)
  2. item_desc : string option;
    (*

    Optional description

    *)
  3. item_pubdate : Ptime.t option;
    (*

    Date of publication

    *)
  4. item_author : string option;
    (*

    The email address of the author of the item.

    *)
  5. item_categories : category list;
    (*

    Categories for the item. See the field category.

    *)
  6. item_comments : Uri.t option;
    (*

    Url of comments about this item

    *)
  7. item_enclosure : enclosure option;
  8. item_guid : guid option;
    (*

    A globally unique identifier for the item.

    *)
  9. item_source : source option;
  10. item_data : 'a option;
    (*

    Additional data, since RSS can be extended with namespace-prefixed nodes.

    *)
}

An item may represent a "story". Its description is a synopsis of the story (or sometimes the full story), and the link points to the full story.

type namespace = string * string

A namespace is a pair (name, url).

type ('a, 'b) channel_t = {
  1. ch_title : string;
    (*

    Mandatory. The name of the channel, for example the title of your web site.

    *)
  2. ch_desc : string;
    (*

    Mandatory. A sentence describing the channel.

    *)
  3. ch_language : string option;
    (*

    Language of the news, e.g. "en". See the W3C language codes.

    *)
  4. ch_managing_editor : string option;
    (*

    Managing editor of the news.

    *)
  5. ch_webmaster : string option;
    (*

    The address of the webmasterof the site.

    *)
  6. ch_pubdate : Ptime.t option;
    (*

    Publication date of the channel.

    *)
  7. ch_last_build_date : Ptime.t option;
    (*

    When the channel content changed for the last time.

    *)
  8. ch_categories : category list;
    (*

    Categories for the channel. See the field category.

    *)
  9. ch_generator : string option;
    (*

    The tool used to generate this channel.

    *)
  10. ch_cloud : cloud option;
    (*

    Allows processes to register with a cloud to be notified of updates to the channel.

    *)
  11. ch_docs : Uri.t option;
    (*

    An url to a RSS format reference.

    *)
  12. ch_ttl : int option;
    (*

    Time to live, in minutes. It indicates how long a channel can be cached before refreshing from the source.

    *)
  13. ch_image : image option;
  14. ch_rating : string option;
    (*

    The PICS rating for the channel.

    *)
  15. ch_text_input : text_input option;
  16. ch_skip_hours : int list option;
    (*

    A hint for aggregators telling them which hours they can skip.

    *)
  17. ch_skip_days : int list option;
    (*

    A hint for aggregators telling them which days they can skip.

    *)
  18. ch_items : 'b item_t list;
  19. ch_data : 'a option;
    (*

    Additional data, since RSS can be extended with namespace-prefixed nodes.

    *)
  20. ch_namespaces : namespace list;
}
type item = unit item_t
type channel = (unit, unit) channel_t

Building items and channels

val item : ?title:string -> ?link:Uri.t -> ?desc:string -> ?pubdate:Ptime.t -> ?author:string -> ?cats:category list -> ?comments:Uri.t -> ?encl:enclosure -> ?guid:guid -> ?source:source -> ?data:'a -> unit -> 'a item_t

item() creates a new item with all fields set to None. Use the optional parameters to set fields.

val channel : title:string -> link:Uri.t -> desc:string -> ?language:string -> ?copyright:string -> ?managing_editor:string -> ?webmaster:string -> ?pubdate:Ptime.t -> ?last_build_date:Ptime.t -> ?cats:category list -> ?generator:string -> ?cloud:cloud -> ?docs:Uri.t -> ?ttl:int -> ?image:image -> ?rating:string -> ?text_input:text_input -> ?skip_hours:int list -> ?skip_days:int list -> ?data:'a -> ?namespaces:namespace list -> 'b item_t list -> ('a, 'b) channel_t

channel items creates a new channel containing items. Other fields are set to None unless the corresponding optional parameter is used.

val compare_item : ?comp_data:('a -> 'a -> int) -> 'a item_t -> 'a item_t -> int
val copy_item : 'a item_t -> 'a item_t
val copy_channel : ('a, 'b) channel_t -> ('a, 'b) channel_t

Manipulating channels

val keep_n_items : int -> ('a, 'b) channel_t -> ('a, 'b) channel_t

keep_n_items n ch returns a copy of the channel, keeping only n items maximum.

val sort_items_by_date : 'a item_t list -> 'a item_t list

Sort items by date, older last.

val merge_channels : ('a, 'b) channel_t -> ('a, 'b) channel_t -> ('a, 'b) channel_t

merge_channels c1 c2 merges the given channels in a new channel, sorting items using sort_items_by_date. Channel information are copied from the first channel c1.

Reading channels

type xmltree =
  1. | E of Xmlm.tag * xmltree list
  2. | D of string

This represents XML trees. Such XML trees are given to functions provided to read additional data from RSS channels and items.

val xml_of_source : Xmlm.source -> xmltree

Read an XML tree from a source.

exception Error of string

Use this exception to indicate an error is functions given to make_opts used to read additional data from prefixed XML nodes.

type ('a, 'b) opts

Options used when reading source.

val make_opts : ?read_channel_data:(xmltree list -> 'a option) -> ?read_item_data:(xmltree list -> 'b option) -> unit -> ('a, 'b) opts
  • parameter read_channel_data

    provides a way to read additional information from the subnodes of the channels. All these subnodes are prefixed by an expanded namespace.

  • parameter read_item_data

    is the equivalent of read_channel_data parameter but is called of each item with its prefixed subnodes.

val default_opts : (unit, unit) opts
val channel_t_of_file : ('a, 'b) opts -> string -> ('a, 'b) channel_t * string list

channel_[t_]of_X returns the parsed channel and a list of encountered errors. Note that only namespaces declared in the root not of the XML tree are added to ch_namespaces field.

  • raises Failure

    if the channel could not be parsed.

val channel_t_of_string : ('a, 'b) opts -> string -> ('a, 'b) channel_t * string list
val channel_t_of_channel : ('a, 'b) opts -> in_channel -> ('a, 'b) channel_t * string list
val channel_t_of_xmls : ('a, 'b) opts -> xmltree list -> ('a, 'b) channel_t * string list

Read a channel from XML trees. These trees correspond to nodes under the "channel" XML node of a reguler RSS document.

val channel_of_file : string -> channel * string list
val channel_of_string : string -> channel * string list
val channel_of_channel : in_channel -> channel * string list

Writing channels

type 'a data_printer = 'a -> xmltree list
val print_channel : ?channel_data_printer:'a data_printer -> ?item_data_printer:'b data_printer -> ?indent:int -> ?encoding:string -> Format.formatter -> ('a, 'b) channel_t -> unit
val print_file : ?channel_data_printer:'a data_printer -> ?item_data_printer:'b data_printer -> ?indent:int -> ?encoding:string -> string -> ('a, 'b) channel_t -> unit
OCaml

Innovation. Community. Security.