NAME

WWW::Yahoo::DrivingDirections-- Generate driving directions for multiple-stop trips in the United States, courtesy of maps.yahoo.com.

ABSTRACT

Object-oriented interface to the maps.yahoo.com driving directions.

SYNOPSIS

    use WWW::Yahoo::DrivingDirections;
    my $yd = WWW::Yahoo::DrivingDirections->new ();
    $yd->add_stops ( @ARGV ); 
    $yd->get_maps();

or

    use WWW::Yahoo::DrivingDirections;
    my $yd = WWW::Yahoo::DrivingDirections->new (
                  {
                      roundtrip   => 1,
                      return_html => 1,
                      save_html   => 0,
                      save_format => 'output_%d.html',
                  },
                  'atlanta, ga',
                  '123 fake st, boston, ma',
                  '0 church st, cambridge, ma',
                  'LAX',
              );
    $yd->add_stops ( 'paris, tx', '1 main st, springfield, IL' ); 
    $yd->roundtrip ( 1 );
    $html_array_ref = $yd->get_maps();

DESCRIPTION

WWW::Yahoo::DrivingDirections provides a simple means of generating driving directions for trips with more stops than a start and a finish. Driving from LAX airport to 1 Main St, Portland, OR to Denver, CO? Just do this:

    use WWW::Yahoo::DrivingDirections;
    my $yd = WWW::Yahoo::DrivingDirections->new (
                 'LAX', '1 Main St, Portland, OR', 'Denver, CO'
             );
    $yd->get_maps();

and the directions will be saved in trip_leg_1.html and trip_leg_2.html.

Methods

new

Creates a new WWW::Yahoo::DrivingDirections instance. A list of string arguments containing stops will be added to the object's list of destinations. A hash reference argument to this function with some or all of the following keys is allowed:

roundtrip

A boolean. If true, a route from the last given stop to the first will be generated. The default is false.

return_html

A boolean. If true, the get_maps method returns a reference to an array of the the html driving direction pages. If false, the get_maps method returns nothing. The default is false.

save_html

A boolean. If true, the get_maps method writes the html driving direction pages to files with names defined by save_format parameter. The default is true. Setting both return_html and save_html to 0 makes get_maps a null-op, and is not reccomended.

save_format

A printf format string defining the filenames that the driving directions are saved to if save_html is true. The default is 'trip_leg_%d.html'. There must be one %d one %s in the string to take the trip leg number. Example: if there are two trip legs, trip_leg_1.html and trip_leg_2.html will be the output files.

mech

The WWW::Mechanize object that interacts with maps.yahoo.com. A user-defined WWW::Mechanize object can be supplied.

add_stops

Add stops to the object's list of driving destinations. The are pushed onto the list. Returns the current number of stops.

Allowed address formats are the following:

    "123 fake st, anytown, az" (street adddress, city, state)
    "123 fake st, anytown, az 87530" (street adddress, city, state zipcode)
    "Boston, ma" (city, state)
    "Boston, ma 02138" (city, state)
    "90210" (zipcode only)
    "LAX" (three letter airport code)

The addresses are parsed on commas; do not add a comma between state and zipcode.

list_stops

Returns a return-delimited string of the driving stops that have been entered.

shuffle_stops

Randomizes the order of the stops.

clear_stops

Clears the list of stops (presumably in order to do another trip).

total_distance

Returns the summed distance of all the trip legs. Returns 0 if run before get_maps.

number_of_stops

Returns the current number of stops.

stops_number

Identical to number_of_stops.

roundtrip

Sets the roundtrip flag to the argument. If the roundtrip flag is true, a trip leg between the last destination and the first destination will be created. Returns the current value of the roundtrip flag.

get_maps

Generates the driving direction pages. The pages are either written to files or returned as a reference to an array of the html pages, or neither, or both, depending on the settings of the return_html and save_html flags.

Functions

get_dirs

A functional interface to the module. All arguments are passed to WWW::Yahoo::DrivingDirections::new, and get_maps is run on the resultant object.

get_directions

Identical to get_dirs.

EXPORT

The (identical) functions get_dirs and get_directions are exported on request.

AUTHOR

Kester Allen, kester@gmail.com

VERSION

0.04

SEE ALSO

WWW::Mechanize, maps.yahoo.com

AUTHOR

Kester Allen, kester@gmail.com

COPYRIGHT AND LICENSE

Copyright 2004 by Kester Allen

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