NAME
    XML::RSS::Feed - Persistant XML RSS Encapsulation

SYNOPSIS
    A quick and dirty non-POE example that uses a blocking "sleep". The
    magic is in the "late_breaking_news" method that returns only headlines
    it hasn't seen.

        use XML::RSS::Feed;
        use LWP::Simple qw(get);

        my $feed = XML::RSS::Feed->new(
            url    => "http://www.jbisbee.com/rdf/",
            name   => "jbisbee",
            delay  => 10,
            debug  => 1,
            tmpdir => "/tmp", # optional caching
        );

        while (1) {
            $feed->parse(get($feed->url));
            print $_->headline . "\n" for $feed->late_breaking_news;
            sleep($feed->delay); 
        }

    ATTENTION! - If you want a non-blocking way to watch multiple RSS
    sources with one process use POE::Component::RSSAggregator.

CONSTRUCTOR
    "XML::RSS::Feed->new( url => $url, name => $name )"
    Required Params

        * "name"
            Identifier and hash lookup key for the RSS feed.

        * "url"
            The URL of the RSS feed

    Optional Params

        * "delay"
            Number of seconds between updates (defaults to 600)

        * "tmpdir"
            Directory to keep a cached feed (using Storable) to keep
            persistance between instances.

        * "debug"
            Turn debuging on.

        * "headline_as_id"
            Boolean value to use the headline as the id when URL isn't
            unique within a feed.

        * "hlobj"
            A class name sublcassed from XML::RSS::Headline

        * "max_headlines"
            The max number of headlines to keep. (default is unlimited)

METHODS
    "$feed->parse( $xml_string )"
        Pass in a xml string to parse with XML::RSS and then call
        "$feed->process()" to process the results.

    "$feed->process( $items, $title, $link )"
    "$feed->process( $items, $title )"
    "$feed->process( $items )"
        Calls "pre_process", "process_items", "post_process", "title", and
        "link" methods to process the parsed results of an RSS XML feed.

        * $items
            An array of hash refs which will eventually become
            XML::RSS::Headline objects. Look at XML::RSS::Headline->new()
            for acceptable arguments.

        * $title
            The title of the RSS feed.

        * $link
            The RSS channel link (normally a URL back to the homepage) of
            the RSS feed.

    "$feed->pre_process"
        Mark all headlines from previous run as seen.

    "$feed->process_items( $items )"
        Turn an array refs of hash refs into XML::RSS::Headline objects and
        added to the internal list of headlines.

    "$feed->post_process"
        Post process cleanup, cache headlines (if tmpdir), and debug
        messages.

    "$feed->create_headline( %args)"
        Create a new XML::RSS::Headline object and add it to the interal
        list. Check "XML::RSS::Headline->new()" for acceptable values for
        %args.

    "$feed->num_headlines"
        Returns the number of headlines for the feed.

    "$feed->seen_headline( $id )"
        Just a boolean test to see if we've seen a headline or not.

    "$feed->headlines"
        Returns an array or array reference (based on context) of
        XML::RSS::Headline objects

    "$feed->late_breaking_news"
        Returns an array or the number of elements (based on context) of the
        latest XML::RSS::Headline objects.

    "$feed->cache"
        If tmpdir is defined the rss info is cached.

    "$feed->set_last_updated"
    "$feed->set_last_updated( Time::HiRes::time )"
        Set the time of when the feed was last processed. If you pass in a
        value it will be used otherwise calls Time::HiRes::time.

    "$feed->last_updated"
        The time (in epoch seconds) of when the feed was last processed.

    "$feed->last_updated_hires"
        The time (in epoch seconds and milliseconds) of when the feed was
        last processed.

SET/GET ACCESSOR METHODS
    "$feed->title"
    "$feed->title( $title )"
        The title of the RSS feed.

    "$feed->debug"
    "$feed->debug( $bool )"
        Turn on debugging messages

    "$feed->init"
    "$feed->init( $bool )"
        init is used so that we just load the current headlines and don't
        return all headlines. in other words we initialize them. Takes a
        boolean argument.

    "$feed->name"
    "$feed->name( $name )"
        The identifier of an RSS feed.

    "$feed->delay"
    "$feed->delay( $seconds )"
        Number of seconds between updates.

    "$feed->link"
    "$feed->link( $rss_channel_url )"
        The url in the RSS feed with a link back to the site where the RSS
        feed came from.

    "$feed->url"
    "$feed->url( $url )"
        The url in the RSS feed with a link back to the site where the RSS
        feed came from.

    "$feed->headline_as_id"
    "$feed->headline_as_id( $bool )"
        Within some RSS feeds the URL may not always be unique, in these
        cases you can use the headline as the unique id. The id is used to
        check whether or not a feed is new or has already been seen.

    "$feed->hlobj"
    "$feed->hlobj( $class )"
        Ablity to use a subclass of XML::RSS::Headline. (See Perl Jobs
        example in XML::RSS::Headline::PerlJobs). This should just be the
        name of the subclass.

    "$feed->tmpdir"
    "$feed->tmpdir( $tmpdir )"
        Temporay directory to store cached RSS XML between instances for
        persistance.

    "$feed->max_headlines"
    "$feed->max_headlines( $integer )"
        The maximum number of headlines you'd like to keep track of. (0
        means infinate)

DEPRECATED METHODS
    "$feed->failed_to_fetch"
        This should was deprecated because, the object shouldn't really know
        anything about fetching, it just processes the results. This method
        currently will always return false

    "$feed->failed_to_parse"
        This method was deprecated because, $feed->parse now returns a bool
        value. This method will always return false

AUTHOR
    Copyright 2004 Jeff Bisbee <jbisbee@cpan.org>

    http://search.cpan.org/~jbisbee/

COPYRIGHT
    This program is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.

    The full text of the license can be found in the LICENSE file included
    with this module.

SEE ALSO
    XML::RSS::Headline, XML::RSS::Headline::PerlJobs,
    POE::Component::RSSAggregator