NAME
    URI::Fetch - Smart URI fetching/caching

SYNOPSIS
        use URI::Fetch;

        ## Simple fetch.
        my $res = URI::Fetch->fetch('http://example.com/atom.xml')
            or die URI::Fetch->errstr;

        ## Fetch using specified ETag and Last-Modified headers.
        $res = URI::Fetch->fetch('http://example.com/atom.xml',
                ETag => '123-ABC',
                LastModified => time - 3600,
        )
            or die URI::Fetch->errstr;

        ## Fetch using an on-disk cache that URI::Fetch manages for you.
        my $cache = Cache::File->new( cache_root => '/tmp/cache' );
        $res = URI::Fetch->fetch('http://example.com/atom.xml',
                Cache => $cache
        )
            or die URI::Fetch->errstr;

DESCRIPTION
    *URI::Fetch* is a smart client for fetching HTTP pages, notably
    syndication feeds (RSS, Atom, and others), in an intelligent, bandwidth-
    and time-saving way. That means:

    *   GZIP support

        If you have *Compress::Zlib* installed, *URI::Fetch* will
        automatically try to download a compressed version of the content,
        saving bandwidth (and time).

    *   *Last-Modified* and *ETag* support

        If you use a local cache (see the *Cache* parameter to *fetch*),
        *URI::Fetch* will keep track of the *Last-Modified* and *ETag*
        headers from the server, allowing you to only download pages that
        have been modified since the last time you checked.

    *   Proper understanding of HTTP error codes

        Certain HTTP error codes are special, particularly when fetching
        syndication feeds, and well-written clients should pay special
        attention to them. *URI::Fetch* can only do so much for you in this
        regard, but it gives you the tools to be a well-written client.

        The response from *fetch* gives you the raw HTTP response code,
        along with special handling of 4 codes:

        *   200 (OK)

            Signals that the content of a page/feed was retrieved
            successfully.

        *   301 (Moved Permanently)

            Signals that a page/feed has moved permanently, and that your
            database of feeds should be updated to reflect the new URI.

        *   304 (Not Modified)

            Signals that a page/feed has not changed since it was last
            fetched.

        *   410 (Gone)

            Signals that a page/feed is gone and will never be coming back,
            so you should stop trying to fetch it.

USAGE
  URI::Fetch->fetch($uri, %param)
    Fetches a page identified by the URI *$uri*.

    On success, returns a *URI::Fetch::Response* object; on failure, returns
    "undef".

    *%param* can contain:

    *   LastModified

    *   ETag

        *LastModified* and *ETag* can be supplied to force the server to
        only return the full page if it's changed since the last request. If
        you're writing your own feed client, this is recommended practice,
        because it limits both your bandwidth use and the server's.

        If you'd rather not have to store the *LastModified* time and *ETag*
        yourself, see the *Cache* parameter below (and the SYNOPSIS above).

    *   Cache

        If you'd like *URI::Fetch* to cache responses between requests,
        provide the *Cache* parameter with an object supporting the Cache
        API (e.g. *Cache::File*, *Cache::Memory*). Specifically, an object
        that supports "$cache->get($key)" and "$cache->set($key, $value,
        $expires)".

        If supplied, *URI::Fetch* will store the page content, ETag, and
        last-modified time of the response in the cache, and will pull the
        content from the cache on subsequent requests if the page returns a
        Not-Modified response.

    *   UserAgent

        Optional. You may provide your own LWP::UserAgent instance. Look
        into LWPx::ParanoidUserAgent if you're fetching URLs given to you by
        possibly malicious parties.

    *   NoNetwork

        Optional. Controls the interaction between the cache and HTTP
        requests with If-Modified-Since/If-None-Match headers. Possible
        behaviors are:

        false (default)
            If a page is in the cache, the origin HTTP server is always
            checked for a fresher copy with an If-Modified-Since and/or
            If-None-Match header.

        1   If set to 1, the origin HTTP is never contacted, regardless of
            the page being in cache or not. If the page is missing from
            cache, the fetch method will return undef. If the page is in
            cache, that page will be returned, no matter how old it is. Note
            that setting this option means the URI::Fetch::Response object
            will never have the http_response member set.

        "N", where N > 1
            The origin HTTP server is not contacted if the page is in cache
            and the cached page was inserted in the last N seconds. If the
            cached copy is older than N seconds, a normal HTTP request (full
            or cache check) is done.

    *   ContentAlterHook

        Optional. A subref that gets called with a scalar reference to your
        content so you can modify the content before it's returned and
        before it's put in cache.

        For instance, you may want to only cache the <head> section of an
        HTML document, or you may want to take a feed URL and cache only a
        pre-parsed version of it. If you modify the scalarref given to your
        hook and change it into a hashref, scalarref, or some blessed
        object, that same value will be returned to you later on
        not-modified responses.

    *   CacheEntryGrep

        Optional. A subref that gets called with the *URI::Fetch::Response*
        object about to be cached (with the contents already possibly
        transformed by your "ContentAlterHook"). If your subref returns
        true, the page goes into the cache. If false, it doesn't.

    *   Freeze

    *   Thaw

        Optional. Subrefs that get called to serialize and deserialize,
        respectively, the data that will be cached. The cached data should
        be assumed to be an arbitrary Perl data structure, containing
        (potentially) references to arrays, hashes, etc.

        Freeze should serialize the structure into a scalar; Thaw should
        deserialize the scalar into a data structure.

        By default, *Storable* will be used for freezing and thawing the
        cached data structure.

    *   ForceResponse

        Optional. A boolean that indicates a *URI::Fetch::Response* should
        be returned regardless of the HTTP status. By default "undef" is
        returned when a response is not a "success" (200 codes) or one of
        the recognized HTTP status codes listed above. The HTTP status
        message can then be retreived using the "errstr" method on the
        class.

LICENSE
    *URI::Fetch* is free software; you may redistribute it and/or modify it
    under the same terms as Perl itself.

AUTHOR & COPYRIGHT
    Except where otherwise noted, *URI::Fetch* is Copyright 2004 Benjamin
    Trott, ben+cpan@stupidfool.org. All rights reserved.

