The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Weather-Bug-0.25
River stage zero No dependents
++
/ Weather::Bug::Location

NAME

Weather::Bug::Location - Simple class interface to the location of a WeatherBug Station or observation.

VERSION

This document describes Weather::Bug::Location version 0.25

SYNOPSIS

    use Weather::Bug;

    my $wbug = Weather::Bug->new( 'YOURAPIKEYHERE' );
    my ($station) = $wbug->list_stations( 77096 );
    my $l = $station->location();

    printf( "%s, %s %s\n\t(%0.5f,%0.5f), (dist=%0.3f)\n",
            $l->city(), $l->state(), $l->zipcode(),
            $l->latitude(), $l->longitude(),
            $l->distance()
    );

DESCRIPTION

Each type of response has its own concept of what Location information should look like. This class abstracts away the differences (as much as possible) providing a mostly common interface. Unfortunately, some of the responses provide more information than others, so it is not always possible to get all of the same information from each Location object.

The Location object should always provide three pieces of information: city, state, and zipcode. Depending on where it was obtained, it may also contain latitude and longitude of the site, distance from the center of the requested zip code, and/or a zone string representing a general location in the US.

Each field has its own accessor method. If the field is optional, it will also have a has_ method that tells whether or not the field is present.

INTERFACE

The Location is basically a data object that only provides read access to its fields. The methods of this class can be separated into two groups, accessor methods and factory methods.

Accessor Methods

The methods providing access to the Location's fields are:

city

The Location's city as a string. Always available.

state

The Location's state as a string. Always available.

zipcode

The Location's zip code as a string. Always available.

has_latitude

Boolean value telling whether or not latitude is available.

latitude

The Location's latitude as a float. Always available.

has_longitude

Boolean value telling whether or not longitude is available.

longitude

The Location's longitude as a float. Always available.

has_distance

Boolean value telling whether or not distance is available.

distance

The Location's distance from the center of the zip code as a float. Always available.

has_zone

Boolean value telling whether or not zone is available.

zone

A string telling the general region of the US that the Location describes.

is_equivalent

Returns a true value if the supplied Location is equvalent.

    $loc->is_equivalent( $other );

Equivalence, in this case, is defined as all of the required fields are the same. The optional fields are also tested in the case where both of the Location objects do have that field. So, if either Location is missing a field (say, distance) this field will not be compared.

Factory Methods

Since the object is usually created from an XML repsonse, the class provides factory methods that take a portion of the XML and return a Location.

from_station_xml

Construct a Location from the aws:station node returned by the getStations API method. The only argument is the node to parse.

The created Location will have the following fields: city, state, zipcode, latitude, longitude, and distance (from the center of the zipcode supplied to getStations).

Returns a Location object on success.

from_forecast

Construct a Location object from the aws:location node returned by the getFullForecast API method. The only argument is the node to parse.

The created Location will have the following fields: city, state, zipcode, and zone.

Returns a Location object on success.

from_compact_station_xml
from_obs_xml

Construct a Location object from a getLiveWeather request.

Returns a Location object on success or dies if the city and state cannot be parsed.

DIAGNOSTICS

City/State not formatted as expected.

The Live Weather mixes the City and State together in one node value. This value was not formatted in a way that allowed the module to parse the result.

CONFIGURATION AND ENVIRONMENT

Weather::Bug requires no configuration files or environment variables.

DEPENDENCIES

Moose, XML::LibXML.

INCOMPATIBILITIES

None reported.

BUGS AND LIMITATIONS

No bugs have been reported.

Please report any bugs or feature requests to bug-weather-weatherbug@rt.cpan.org, or through the web interface at http://rt.cpan.org.

AUTHOR

G. Wade Johnson <wade@anomaly.org>

LICENCE AND COPYRIGHT

Copyright (c) 2008, G. Wade Johnson <wade@anomaly.org>. All rights reserved.

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

DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.