Michael Stovenour > Weather-NOAA-Alert > Weather::NOAA::Alert

Download:
Weather-NOAA-Alert-0.90.tar.gz

Dependencies

Annotate this POD

CPAN RT

Open  2
View/Report Bugs
Module Version: 0.90   Source  

NAME ^

Weather::NOAA::Alert - Polling and parsing of NOAA CAP 1.1 Alerts

VERSION ^

Version 0.90

SYNOPSIS ^

    my $alert = Weather::NOAA::Alert->new(['TXZ104', 'TXC082', 'TXZ097']);
    my $events = $alert->get_events();
    my ($errorCount, $eventCount, $addCount, $deleteCount) = $alert->poll_events();

DESCRIPTION ^

Weather::NOAA::Alert will retrieve and parse the NOAA National Weather Service ATOM and CAP 1.1 feeds for the specified forecast zones. It is designed to cache previously polled CAP items. The overall process is to get the requested ATOM feed, get any CAP entries that are not in the cache, and store the alerts.

You can find the zone list and more information about NOAA watches, warnings, and advisories at the following sites:

EXAMPLE ^

    use Weather::NOAA::Alert;
    use Data::Dumper;
 
    my $SLEEP_SECS = 60;   #Poll every 1 minute
 
    #my $alert = Weather::NOAA::Alert->new(['US']);
    my $alert = Weather::NOAA::Alert->new(['TXC085', 'TXZ097']);
    $alert->printLog(1);
    $alert->errorLog(1);

    my $events = $alert->get_events();
 
    while (1) {
         my ($errorCount, $eventCount, $addCount, $deleteCount) 
                 = $alert->poll_events();
       
         print Dumper( $events) . "\n";
       
         print "Tracking $eventCount " . ($eventCount ==1 ? "event" : "events");
         print "   $addCount added, $deleteCount deleted";
         print ", $errorCount " . ($errorCount ==1 ? "error" : "errors");
         print "\n";
         
         print "Sleeping $SLEEP_SECS seconds\n-----------------\n\n";
         sleep($SLEEP_SECS);
     }

METHODS ^

new - Create a new Weather::NOAA::Alert object

    $alert = Weather::NOAA:Alert->new(@zones);
    $alert = Weather::NOAA:Alert->new();

An array reference may be provided with the list of NOAA forecast zones that should be polled. If the list is not supplied then you must call $object->zones(@zones) to set the zone list prior to calling $object->poll_events().

zones - Set the monitored zone list

    $object->zones([zone1, zone2, ...]);
    @zones = $object->zones();

Setting the zone list will overwrite the existing list with the supplied list. If called with no arguments, returns a reference to the current zone array. To return data for all zones use "US".

get_events - get a reference to the alert object events hash

    %events = $object->get_events();

This is the primary output of the Weather::NOAA::Alert module. The data structure is the result of parsing the NOAA CAP 1.1 objects retrieved for the specified zones. The events hash is indexed first by zone, then by the CAP ID.

Remembers past events in a data structure hash consisting of: {zone}->{CAP id}->{'delete'} ->{'actionTime'} ->{'event'} ->{'certainty'} ->{'senderName'} ->{'urgency'} ->{'instruction'} ->{'description'} ->{'category'} ->{'severity'} ->{'effective'} ->{'headline'} ->{'expires'}

Note that the hash keys are dynamically created from the <info> section of the event. If NOAA adds, renames, or removes an XML parameter it will also change in the structure. In addition, nothing is currently parsed from the event header. There are XML parameters in the header that might be interesting to collect but I didn't have a use for any of that data. Future module revisions might include more of the NOAA data.

SETTINGS ^

formatTime - Add colons to strings that look like time stamps

    $object->formatTime( [1 | 0] );
    $curr_setting = $object->formatTime();

When called without parameters will return the current setting.

formatAsterisk - Strip asterisks from description and information tags

    $object->formatAsterisk( [1 | 0] );
    $curr_setting = $object->formatAsterisk();

When called without parameters will return the current setting.

printLog - Print basic status information while retrieving cap entities

    $object->printLog( [1 | 0] );
    $curr_setting = $object->printLog();

When called without parameters will return the current setting.

printActions - Print the cap ID for every entry added or deleted

    $object->printActions( [1 | 0] );
    $curr_setting = $object->printActions();

When called without parameters will return the current setting.

errorLog - Print error descriptions

    $object->errorLog( [1 | 0] );
    $curr_setting = $object->errorLog();

When called without parameters will return the current setting.

diagDump - Save all atom content to file

    $object->diagDump( [1 | 0] );
    $curr_setting = $object->diagDump();

Dumps all atom files received to the file diagnostics.txt in the current directory. When called without parameters will return the current setting.

atomURLZone - Sets the Atom URL for zones

    $object->atomURLZone( $url );
    $curr_setting = $object->atomURLZone();

When called without parameters will return the current setting. The default setting is:

http://alerts.weather.gov/cap/wwaatmget.php?x=

atomURLUS - Sets the Atom URL when specifying zone "US"

    $object->atomURLUS( $url );
    $curr_setting = $object->atomURLUS();

When called without parameters will return the current setting. The default setting is:

http://alerts.weather.gov/cap/us.atom

VERSION - Returns the current module version

    my $version = Weather::NOAA::Alert->VERSION;

poll_events - Poll NWS Public Alerts

    my ($errorCount, $eventCount, $addCount, $deleteCount)
            = $object->poll_events();

Polls the National Weather Service Public Alerts and updates the events hash for each event. Returns an array of counts:

NOAA CAP CHALLENGES ^

The following items represent fragile parts of the code caused by ambiguous data in the National Weather Service CAP feeds. These items should be addressed by NWS by publishing a document that clearly states the behavior for each of these conditions or by generally adding more XML enclosures especially replacing the long list of counties that can occur.

TODO ^

SEE ALSO ^

AUTHOR ^

Michael Stovenour, <michael at stovenour.net>

BUGS ^

Please report any bugs or feature requests to bug-weather-noaa-alert at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Weather-NOAA-Alert. 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 Weather::NOAA::Alert

You can also look for information at:

LICENSE AND COPYRIGHT ^

Copyright 2011 Michael Stovenour.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.

syntax highlighting: