NAME
    POE::Component::WWW::Cache::Google - non-blocking wrapper around
    WWW::Cache::Google

SYNOPSIS
        use strict;
        use warnings;

        use POE qw(Component::WWW::Cache::Google);

        my $poco = POE::Component::WWW::Cache::Google->spawn;

        POE::Session->create(
            package_states => [ main => [qw(_start cache)] ],
        );

        $poe_kernel->run;

        sub _start {
            $poco->cache( {
                    uri   => 'http://zoffix.com/',
                    event => 'cache',
                    fetch => 1,
                }
            );
        }

        sub cache {
            my $in_ref = $_[ARG0];

            print "Cache URI for $in_ref->{uri} is: $in_ref->{cache}\n";
            print "Content:\n$in_ref->{content}\n";

            $poco->shutdown;
        }

    Using event based interface is also possible of course.

DESCRIPTION
    The module is a non-blocking wrapper (for what it's worth) around
    WWW::Cache::Google which provides interface to get Google's "cache" URIs
    as well as optionally fetch contents of such URIs.

CONSTRUCTOR
  "spawn"
        my $poco = POE::Component::WWW::Cache::Google->spawn;

        POE::Component::WWW::Cache::Google->spawn(
            alias => 'google_cache',
            options => {
                debug => 1,
                trace => 1,
                # POE::Session arguments for the component
            },
            debug => 1, # output some debug info
        );

    The "spawn" method returns a POE::Component::WWW::Cache::Google object.
    It takes a few arguments, *all of which are optional*. The possible
    arguments are as follows:

   "alias"
        ->spawn( alias => 'google_cache' );

    Optional. Specifies a POE Kernel alias for the component.

   "options"
        ->spawn(
            options => {
                trace => 1,
                default => 1,
            },
        );

    Optional. A hashref of POE Session options to pass to the component's
    session.

   "debug"
        ->spawn(
            debug => 1
        );

    When set to a true value turns on output of debug messages. Defaults to:
    0.

METHODS
  "cache"
        $poco->cache( {
                event       => 'event_for_output',
                uri         => 'http://zoffix.com',
                max_size    => 1000,
                fetch       => 1, # or fetch => \'file_name',
                overwrite => 1,
                _blah       => 'pooh!',
                session     => 'other',
            }
        );

    Takes a hashref as an argument, does not return a sensible return value.
    See "WWW::Cache::Google" event's description for more information.

  "session_id"
        my $poco_id = $poco->session_id;

    Takes no arguments. Returns component's session ID.

  "shutdown"
        $poco->shutdown;

    Takes no arguments. Shuts down the component.

ACCEPTED EVENTS
  "cache"
        $poe_kernel->post( google_cache => cache => {
                event       => 'event_for_output',
                uri         => 'http://zoffix.com',
                max_size    => 1000,
                fetch       => 1, # or fetch => \'file_name',
                overwrite   => 1,
                _blah       => 'pooh!',
                session     => 'other',
            }
        );

    Instructs the component to construct a URI to Google's 'cached' URI for
    the URI given via "uri" argument. Optionally can fetch page's content or
    automatically store it in a file. Takes a hashref as an argument, the
    possible keys/value of that hashref are as follows:

   "event"
        { event => 'results_event', }

    Mandatory. Specifies the name of the event to emit when results are
    ready. See OUTPUT section for more information.

   "uri"
        { uri => 'http://haslayout.net/' }

    Mandatory. Specifies the URi which to look up in Google's cache.

   "fetch"
        { fetch => 1 },

        { fetch => \'file_name' }

    Optional. Takes either true, false or scalarref values. When set to a
    false value, the component will not fetch the page. When set to a true
    value, the component will try to fetch the uri (in Google's cache that
    is) using LWP::Simple. When set to a scalarref, it will be dereferenced
    to obtain a filename into which to save the contents. The component will
    error out if the file already exists (the check is performed via "-e")
    unless "overwrite" argument (see below) is set to a true value. Defaults
    to: 0 (no fetching)

   "overwrite"
        { overwrite => 1 }

    Optional. Regarded only when the "fetch" argument (see above) is set to
    a scalarref which is a filename. Can take either true or false values.
    When set to a true value will overwrite the filename set via "fetch"
    argument if the file already exists. Defaults to: 0 (no overwriting -
    error out instead)

   "max_size"
        { max_size => 1000, }

    Optional. Regarded only when the "fetch" argument is not a false value.
    The value you specify (which indicates the maximum length of the content
    to retrieve) will by passed to LWP::UserAgent's "max_size" method. Use
    this argument if you just want to have error checking with regards to
    actual existance of that cache page. Note: component *does* actually
    need some content to determine if the cached page exists, thus do not
    set max_size below 100. By default is not set, thus no limit on the
    content length is imposed.

   "session"
        { session => 'other' }

        { session => $other_session_reference }

        { session => $other_session_ID }

    Optional. Takes either an alias, reference or an ID of an alternative
    session to send output to.

   user defined
        {
            _user    => 'random',
            _another => 'more',
        }

    Optional. Any keys starting with "_" (underscore) will not affect the
    component and will be passed back in the result intact.

  "shutdown"
        $poe_kernel->post( google_cache => 'shutdown' );

    Takes no arguments. Tells the component to shut itself down.

OUTPUT
        $VAR1 = {
            'overwrite' => 1,
            'content' => '<meta http-e.... and so on',
            'fetch' => 1,
            'uri' => 'http://zoffix.com',
            'cache' => bless( do{\(my $o = 'http://www.google.com/search?q=cache:zoffix.com')}, 'URI::http' )
        };

    The event handler set up to handle the event which you've specified in
    the "event" argument to "cache()" method/event will recieve input in the
    $_[ARG0] in a form of a hashref. The possible keys/value of that hashref
    are as follows:

  "cache"
        'cache' => bless( do{\(my $o = 'http://www.google.com/search?q=cache:zoffix.com')}, 'URI::http' )

    The "cache" key will contain a URI object representing the URI pointing
    to the Google's cache page. Note: without actually fetching anything
    there is no way to know if that URI contains anything but Google's "no
    found".

  "content"
        'content' => '<meta http-e.... and so on',

    The "content" key will contain the content of the Google cache page.
    This key will be set only when the "fetch" argument to the "cache"
    event/method is set to a true value, or when the "fetch" argument is set
    to a scalarref and the cached page was not found on google. When later
    occurs, the "error" key will also be present.

  "error"
        'error' => 'Doesn\'t look like cache exists',

    There won't ever be errors if the "fetch" argument to "cache"
    event/method is set to a false value. Otherwise, the "error" key will
    contain the explanation of any errors that occur, including any issues
    with opening the file when "fetch" argument is set to a scalarref.

  arguments passed to "cache" event/method
        'overwrite' => 1,
        'fetch' => 1,
        'max_size' => 100,
        'uri' => 'http://zoffix.com',

    The "overwrite", "fetch", "max_size" and "uri" arguments passed to
    "cache" event/method will be present in the output intact.

  user defined
        { '_blah' => 'foos' }

    Any arguments beginning with "_" (underscore) passed into the "cache()"
    event/method will be present intact in the result.

SEE ALSO
    POE, WWW::Cache::Google

AUTHOR
    Zoffix Znet, "<zoffix at cpan.org>" (<http://zoffix.com>,
    <http://haslayout.net>)

BUGS
    Please report any bugs or feature requests to
    "bug-poe-component-www-cache-google at rt.cpan.org", or through the web
    interface at
    <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=POE-Component-WWW-Cache-
    Google>. I will be notified, and then you'll automatically be notified
    of progress on your bug as I make changes.

SUPPORT
    You can find documentation for this module with the perldoc command.

        perldoc POE::Component::WWW::Cache::Google

    You can also look for information at:

    *   RT: CPAN's request tracker

        <http://rt.cpan.org/NoAuth/Bugs.html?Dist=POE-Component-WWW-Cache-Go
        ogle>

    *   AnnoCPAN: Annotated CPAN documentation

        <http://annocpan.org/dist/POE-Component-WWW-Cache-Google>

    *   CPAN Ratings

        <http://cpanratings.perl.org/d/POE-Component-WWW-Cache-Google>

    *   Search CPAN

        <http://search.cpan.org/dist/POE-Component-WWW-Cache-Google>

COPYRIGHT & LICENSE
    Copyright 2008 Zoffix Znet, all rights reserved.

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