The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Storm-Tracker_0.01
River stage zero No dependents
++
/ Geo::Storm_Tracker::Data

NAME

Geo::Storm_Tracker::Data - The weather event object of the perl Storm-Tracker bundle.

SYNOPSIS

        use Geo::Storm_Tracker::Data;

        #The only argument is the path for the data files of
        #this new data object.
        #If the directory does not exist it will fail.

        ($data_object,$error)=Geo::Storm_Tracker::Data->new('/data/1999/15');

        #The only argument is the path for the data files of this
        #shiny new data object.
        #The shiny_new method expects to create the last directory level of the path.
        #If the full path already exists it will fail.
        ($data_object,$error)=Geo::Storm_Tracker::Data->shiny_new('/data/1999/15');

        
        #The insert_advisory method inserts an advisory object
        #into the data object.
        #Unless the second argument is true, inserting an
        #advisory with the same advisory number as a previously
        #inserted advisory will fail. 
        #Second argument can be thought of as a force flag.
       
         ($success,$error)=$data_object->insert_advisory($adv_obj,[0|1])


        #Determine the last known position for this weather event.
        $position_AR=$data_object->current_position()

        ($long,$long_dir,$lat,$lat_dir)=@{$position_AR};


        #The postion_track method will return an
        #array of position array references.
        #sorted in advisory number order.
        #The position from the advisory with the smallest
        #advisory number will be in element 0 of @track.
       
        @track=$data_object->position_track();

        #Alternatively.

        $track_AR=$data_object->position_track();
        @track=@{$track_AR};


        #Retrieve the most current advisory available
        #for this data object.
        
        $adv_obj=$data_object->current_advisory;


        #Is this weather event still occurring?
        #$set_to will contain true(1) or false(0)
        #if called without any arguments.
        #Can be used as an assignment operator
        #if given an argument.
        #When used as an assignment operator it
        #returns the value to which it was set
        #if successful and undef otherwise.

        ($set_to,$error)=$data_object->is_active([[0|1]);


        #The all_advisory_objects method returns an array of
        #every weather event advisory available in the referenced
        #data object.
        #The order is identical
        #to that returned by the position_track method.

        @all_advisory_objects=$data_object->all_advisories();
        
        #Alternatively

        $all_advisory_objects_AR=$data_object->all_advisories();


        #The advisory_by_number method returns an advisory
        #object for the advisory number given as an argument.
        #If the advisory doesn't exist the method returns undef.

        $adv_obj_15=$data_object->advisory_by_number(15);


        #Returns the path to the data file directory of
        #this object.

        $path=$data_object->get_path();

DESCRIPTION

The Geo::Storm_Tracker::Data module is a component of the Storm-Tracker perl bundle. The Storm-Tracker perl bundle is designed to track weather events using the national weather advisories. The original intent is to track tropical depressions, storms and hurricanes. There should be a Geo::Storm_Tracker::Data object for each weather event being stored and/or tracked. The Geo::Storm_Tracker::Data objects are managed by Geo::Storm_Tracker::Main.

CONSTRUCTOR

new (PATHNAME)

Creates a Geo::Storm_Tracker::Data object. This constructor method returns an array of the form (OBJECT,ERROR). OBJECT being the newly created object if successful, and ERROR being any errors encountered during the attempt.

The data set for this object is assumed to be contained within the directory specified by the mandatory PATHNAME argument. In the event that a directory with the given PATHNAME does not exist, the method will fail. Check to see if the OBJECT returned is defined.

The motivation for having two constructor methods instead of one, is to help the caller maintain data integrity.

shiny_new (PATHNAME)

Creates a Geo::Storm_Tracker::Data object. This constructor method returns an array of the form (OBJECT,ERROR). OBJECT being the newly created object if successful, and ERROR being any errors encountered during the attempt.

The data set for this object will be placed within the directory specified by the mandatory PATHNAME argument. The method will only succeed if the directory with the given PATHNAME does not already exist.

The shiny_new method only knows how to create the last level directory. The constructor does not attempt to recursively create a new directory and therefore will never succeed unless every directory in the path except the last one already exists. Even then the creation of a new directory can fail due to permission problems. It is wise to always check to insure that the OBJECT returned is defined.

The motivation for having two constructor methods instead of one, is to help the caller maintain data integrity.

METHODS

insert_advisory (ADVISORY_OBJECT)

Attempts to insert a Geo::Storm_Tracker::Advisory object into the Geo::Storm_Tracker::Data object being referenced.

The method returns an array of the form (SUCCESS,ERROR). SUCCESS being a boolean value indicating whether or not the operation was successful and ERROR being a scalar string reporting what error was encountered if any.

current_position

When called in scalar context current_position returns a reference to a position array.

When called in array context current_position returns a position array.

The position array specifies the longitude and latitude of the most recent weather advisory available for this Geo::Storm_Tracker::Data object. The position array is of the form (LONGITUDE,N or S,LATITUDE, W or E).

If the Geo::Storm_Tracker::Data object being referenced contains no advisories at all the return value will be undefined.

position_track

When called in scalar context position_track returns a reference to an array of position array references.

When called in array context position_track returns an array of position array references.

There is a position returned for each advisory within the Geo::Storm_Tracker::Data object being referenced. The position arrays returned are sorted by advisory number with the smallest advisory number first.

The position arrays are identical in format to that returned by the current_position method.

current_advisory

Returns a reference to the Geo::Storm_Tracker::Advisory object within the Geo::Storm_Tracker::Data object that has the greatest advisory number.

If the Geo::Storm_Tracker::Data object being referenced contains no advisories at all the return value will be undefined.

all_advisories

When called in scalar context all_advisories returns a reference to an array of advisory objects.

When called in array context all_advisories returns an array of advisory objects.

The array of advisories is sorted by advisory number in the same order as that used by the position_track method. The advisory with the smallest advisory number will be given first.

If the Geo::Storm_Tracker::Data object being referenced contains no advisories at all the return value will be undefined.

advisory_by_number (NUM)

Returns a reference to the advisory object with the same advisory number as given by the mandatory NUM argument.

If the Geo::Storm_Tracker::Data object being referenced does not contain an advisory with the requested advisory number the return value will be undefined.

get_path

Returns the path passed to the new method upon creation of the referenced Geo::Storm_Tracker::Data object.

is_active ([BOOLEAN])

When called with a boolean argument is_active attempts to define the referenced Geo::Storm_Tracker::Data object as active or inactive. is_active returns the array (SET_TO,ERROR). If successful the SET_TO string indicates the value the state to which the data_object was set. If unsuccessful SET_TO will be undefined and ERROR will contain the reason for the failure.

When is_active is called without an argument it will return the current state of the Geo::Storm_Tracker::Data object being referenced.

AUTHOR

Jimmy Carpenter, Jimmy.Carpenter@chron.com

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

Thanks to Dr. Paul Ruscher for his assistance in helping me to understand the weather advisory formats.

SEE ALSO

Geo::Storm_Tracker::Main Geo::Storm_Tracker::Parser Geo::Storm_Tracker::Advisory

perl(1).