FeedReader.Format behaviour (FeedReader v0.1.0)

Behaviour implemented by built-in and explicitly supplied feed formats.

Detection examines only the bounded, replayable prefix provided by the caller. XML formats provide their dedicated Saxy handler and create parser state with an event sink; normalization returns the standalone feed and item value types.

Callback options are keyword lists. The shared parser limits are:

:max_xml_events — non-negative integer; default 1_000_000.
:max_xml_depth — non-negative integer; default 256.
:max_attributes_per_element — non-negative integer; default 128.
:max_attribute_bytes — non-negative integer; default 65_536.
:max_feed_metadata_bytes — non-negative integer; default 1_048_576.
:max_item_bytes — non-negative integer; default 4_194_304.

Zero is a valid limit. Missing or invalid limit values use the defaults. A format may define additional options; their meaning and accepted values are documented by that format. Parser limits are consumed while building parser state; the keyword list is also passed to the normalization callbacks. RSS recognizes :feed_url as an optional URL string.

Summary

Types

options()

Keyword options accepted by format callbacks.

Callbacks

handler()

Returns the module implementing Saxy.Handler; no options are accepted.

id()

Returns the stable atom identifying this format; no options are accepted.

matches_prefix?(prefix)

Tests a bounded prefix for this format.

new_parser_state(event_sink, opts)

Creates the initial state for handler/0 and its event sink.

normalize_feed(state, opts)

Converts completed format-specific parser state into normalized feed metadata.

normalize_item(raw_item, feed, opts)

Converts one raw format-specific item using normalized feed metadata.

Types

options()

@type options() :: keyword()

Keyword options accepted by format callbacks.

Callbacks

handler()

@callback handler() :: module()

Returns the module implementing Saxy.Handler; no options are accepted.

id()

@callback id() :: atom()

Returns the stable atom identifying this format; no options are accepted.

matches_prefix?(prefix)

@callback matches_prefix?(prefix :: binary()) :: boolean()

Tests a bounded prefix for this format.

The prefix is at most :max_detection_bytes bytes. That option belongs to the caller of format detection, not this callback; it must be a positive integer and defaults to 65_536. This callback accepts no options and must not read beyond the supplied prefix.

new_parser_state(event_sink, opts)

@callback new_parser_state(event_sink :: (term() -> term()), opts :: options()) :: term()

Creates the initial state for handler/0 and its event sink.

The arity-one event_sink receives {:feed, feed} and {:item, item} events as values are normalized. opts accepts the shared parser limits documented in this module's options section, plus options defined by the format. RSS accepts :feed_url as an optional String.t() and forwards it to normalize_feed/2.

normalize_feed(state, opts)

@callback normalize_feed(state :: term(), opts :: options()) :: FeedReader.Feed.t()

Converts completed format-specific parser state into normalized feed metadata.

opts accepts the shared parser limits documented in this module's options section and format-specific options. RSS recognizes :feed_url as an optional String.t(); when omitted, the resulting feed URL is nil.

normalize_item(raw_item, feed, opts)

@callback normalize_item(
  raw_item :: map(),
  feed :: FeedReader.Feed.t(),
  opts :: options()
) ::
  {:ok, FeedReader.Item.t()} | :skip | {:error, term()}

Converts one raw format-specific item using normalized feed metadata.

Return {:ok, item} to deliver an item, :skip to omit it, or {:error, reason} to terminate parsing. opts is a keyword list containing the shared parser limits and any format-specific options. The RSS implementation currently uses no item-normalization options.