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

SYNOPSIS
        use strict;
        use warnings;
        use POE qw/Component::WWW::Google::Time/;

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

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

        $poe_kernel->run;

        sub _start {
            $poco->get_time({ event => 'results', where => 'Toronto' });
        }

        sub results {
            my $data = $_[ARG0];

            if ( $data->{error} ) {
                print "Error: $data->{error}\n";
            }
            else {
                printf "It is %s, %s (%s) in %s\n",
                    @{ $data->{result} }{ qw/day_of_week  time  time_zone  where/ };
            }
            $poco->shutdown;
        }

    Using event based interface is also possible of course.

DESCRIPTION
    The module is a non-blocking wrapper around WWW::Google::Time which
    provides interface to fetch time data for various locations from Google.

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

        POE::Component::WWW::Google::Time->spawn(
            alias => 'google_time',
            ua      => LWP::UserAgent->new( ua => "Mozilla" ),
            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::Google::Time object.
    It takes a few arguments, *all of which are optional*. The possible
    arguments are as follows:

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

    Optional. Specifies a POE Kernel alias for the component.

   "ua"
        ->spawn( ua => LWP::UserAgent->new( agent => "Mozilla" );

    Optional. Same as the "ua" argument in WWW::Google::Time constructor.
    Note that Google blocks LWP::UserAgent's default "User-Agent" header.

   "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
  "get_time"
        $poco->get_time( {
                event       => 'event_for_output',
                where       => 'Toronto',
                _blah       => 'pooh!',
                session     => 'other',
            }
        );

    Takes a hashref as an argument, does not return a sensible return value.
    See "get_time" 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
  "get_time"
        $poe_kernel->post( google_time => get_time => {
                event       => 'event_for_output',
                where       => 'Toronto',
                _blah       => 'pooh!',
                session     => 'other',
            }
        );

    Instructs the component to fetch time data from Google. 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.

   "where"
        { where => 'Toronto' }

    Mandatory. Specifies the place for which to fetch the time data.

   "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_time => 'shutdown' );

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

OUTPUT
        $VAR1 = {
            'where' => 'Toronto',
            'result' => {
                'time' => '11:06pm',
                'day_of_week' => 'Saturday',
                'time_zone' => 'EDT',
                'where' => 'Toronto, Ontario'
            },
            '_blah' => 'foos',
        };

        $VAR1 = {
            'error' => 'Could not find time data for that location',
            'where' => 'Nonexistant',
            '_blah' => 'foos',
        };

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

  "where"
        { where => 'Toronto' }

    The "where" key will contain the same value as what you passed in
    "where" argument to the "get_time()" event/method.

  "error"
        { 'error' => 'Could not find time data for that location' }

    The "error" key will be present if a network error occured or Google
    doesn't know about the location you passed as "where" argument to the
    "get_time()" method/event.

  "result"
        'result' => {
            'time' => '11:06pm',
            'day_of_week' => 'Saturday',
            'time_zone' => 'EDT',
            'where' => 'Toronto, Ontario'
        },

    The "result" key (upon success, that is when "error" key is not present)
    will contain the same hashref as returned by the WWW::Google::Time's
    "get_time()" method. See documentation for WWW::Google::Time for more
    information.

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

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

SEE ALSO
    POE, WWW::Google::Time

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

BUGS
    Please report any bugs or feature requests to
    "bug-poe-component-www-google-time at rt.cpan.org", or through the web
    interface at
    <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=POE-Component-WWW-Google
    -Time>. 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::Google::Time

    You can also look for information at:

    *   RT: CPAN's request tracker

        <http://rt.cpan.org/NoAuth/Bugs.html?Dist=POE-Component-WWW-Google-T
        ime>

    *   AnnoCPAN: Annotated CPAN documentation

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

    *   CPAN Ratings

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

    *   Search CPAN

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

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.