/ 
WWW-PTV-0.02
River stage zero No dependents
/ WWW::PTV

NAME

WWW::PTV - Perl interface to Public Transport Victoria (PTV) Website.

VERSION

Version 0.01

SYNOPSIS

use WWW::PTV;

my $ptv = WWW::PTV->new( cache => 1 );

METHODS

new ( cache => BOOLEAN )

Constructor method - creates a new WWW::PTV object. This method accepts an optional hashref specifying a single valid parameter; cache, which if set to a true value will enable internal object caching.

The default behaviour is not to implement any caching, however it is strongly recommended that you enable caching in most implementations. Caching will dramatically improve the performance of repeated method invocations and reduce network utilisation, but will increase memory requirements.

You may also selectively enable or disable the cache after invoking the constructor via the cache and nocache methods.

See the CACHING section for more information.

cache

Enables internal object caching. See the CACHING section for more details.

nocache

Enables internal object caching. See the CACHING section for more details.

get_metropolitan_bus_routes

Returns a hash containing all metropolitan bus routes indexed by the bus route ID.

Please note that the bus route ID is not the same as the bus route ID that may be used to identify the service by the service operator - the ID used in this module refers to the unique ID assigned to the route within the context of the PTV website.

my %routes = $ptv->get_metropolitan_bus_routes;
map { printf( "%-6s: %-50s\n", $_, $routes{ $_ } } sort keys %routes;

# Prints a list of all metropolitan bus route IDs and names. e.g.
# 1000  : 814 - Springvale South - Dandenong via Waverley Gardens Shopping Centre, Springvale
# 1001  : 815 - Dandenong - Noble Park                      
# 1003  : 821 - Southland - Clayton via Heatherton 
# ... etc.

get_regional_bus_routes

Returns a hash containing all regional bus routes indexed by the bus route ID.

Please note that the bus route ID is the PTV designated ID for the route and not the service operator ID.

my %routes = $ptv->get_regional_bus_routes;

while (( $id, $desc ) = each %routes ) {
	print "$id : $desc\n" if ( $desc =~ /Echuca/ )
}

# Prints a list of regional bus routes containing 'Echuca' in the route name - e.g.
# 1346 : Echuca - Moama (Route 3 - Circular)
# 1345 : Echuca - Echuca East (Route 2 - Circular)
# 6649 : Kerang - Echuca via Cohuna (Effective from 18/11/2012)
# ... etc.

get_metropolitan_tram_routes

Returns a hash containing all metropolitan tram routes indexed by the route ID.

Please note as per the method above, the route ID is the PTV designated route and not the service operator ID.

get_metropolitan_train_routes

Returns a hash containing all metropolitan train routes indexed by the route ID.

Please note as per the method above, the route ID is the PTV designated route and not the service operator ID.

get_vline_bus_routes

Returns a hash containing all V/Line bus routes indexed by the route ID.

Please note as per the method above, the route ID is the PTV designated route and not the service operator ID.

get_vline_train_routes

Returns a hash containing all V/Line train routes indexed by the route ID.

Please note as per the method above, the route ID is the PTV designated route and not the service operator ID.

get_route_by_id

my $route = $ptv->get_route_by_id( 1 );

print $route->direction_out."\n".$route_description."\n";
# Prints the outbound route direction ("To Alamein") and a 
# description of the outbound route

Returns a WWW::PTV::Route object for the given route ID representing a transit route.

Note that the route ID is not the service operator route ID, but is the PTV route ID as obtained from one of the other methods in this class.

See the WWW::PTV::Route page for more detail.

get_stop_by_id ( $ID )

Returns the stop identified by the numerical parameter $ID as a WWW::PTV::Stop object. The numerical identifier of a stop is unique.

get_local_areas

Returns a hash containing the defined "local areas" and a URI to the local area web page. The hash is indexed by the local area name.

get_area_by_id ( $ID )

Returns the area identified by the numerical parameter $ID as a WWW::PTV::Area object.

CACHING

It is strongly recommended that you enable caching in the constructor invocation using the optional cache argument. Caching is not enabled by default to align with the principle of least surprise, however it is most likely that you will want to enable it to improve the performance of your program and to reduce the number ofrequests to the PTV website.

If you do not enable caching, then you may wish to consider storing any retrieved objects locally (e.g. in a database), or attempting to limit the frequency, or number, of methods invocations.

Note that you can also disable the cache for selective method invocations by invoking the no_cache method prior to method invocation, and then re-enable the cache (which will also restore the content of the cache prior to the invocation of the nocache method) with the cache method.

# Disable cache
$ptv->nocache;

$ptv->get_stop_by_id( $id );

# Re-enable cache
$ptv->cache;

AUTHOR

Luke Poskitt, <ltp at cpan.org>

BUGS

Please report any bugs or feature requests to bug-www-ptv at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=WWW-PTV. 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 WWW::PTV

You can also look for information at:

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

Copyright 2012 Luke Poskitt.

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.