NAME
Map::Tube - Lightweight Routing Framework.
VERSION
Version v5.0.1
DESCRIPTION
The core module defined as a Role (Moo) to process the map data. It provides the interface to find the shortest route in terms of stoppage between two nodes. Also you can get all possible routes between two given nodes.
The routing algorithm is line-change-aware: when two candidate routes have the same number of stops, the one requiring fewer line changes is preferred. Each line change incurs a small fractional penalty (0.5) on top of the normal per-hop cost of 1, so hop count always dominates but unnecessary changes are avoided.
If you are keen to know the internals of Map::Tube then please follow the note documented in Map::Tube::Cookbook.
MAP LEADER BOARD
+----------------------+-----------+------------------------------------------+
| Author | PAUSE ID | Map Count (City) |
+----------------------+-----------+------------------------------------------+
| Michal Josef Spacek | SKIM | 22 (Bucharest, Budapest, Dnipropetrovsk, |
| | | Kazan, Kharkiv, Kiev, KualaLumpur, |
| | | Malaga, Minsk, Moscow, Nanjing, |
| | | NizhnyNovgorod, Novosibirsk, Prague, |
| | | SaintPetersburg, Samara, Singapore, |
| | | Sofia, Tbilisi, Vienna, Warsaw, |
| | | Yekaterinburg) |
| | | |
| Gisbert W Selke | GWS | 16 (Beijing, Brussels, Chicago, Glasgow, |
| | | Hamburg, KoelnBonn, Lyon, Muenchen, |
| | | Napoli, Oslo, Paris, RheinRuhr, |
| | | San Francisco, Stockholm, Stuttgart, |
| | | Toulouse) |
| | | |
| Mohammad Sajid Anwar | MANWAR | 8 (Barcelona, Delhi, Kolkatta, Leipzig, |
| | | London, Madrid, NYC, Tokyo) |
| | | |
| FUNG Cheok Yin | CYFUNG | 1 (Hong Kong) |
| | | |
| Peter Harrison | EARLYBEAN | 1 (Sydney) |
| | | |
| Errietta Kostala | ERRIETTA | 1 (Athens) |
| | | |
| Giuseppe Di Terlizzi | GDT | 1 (Rome) |
| | | |
| Marco Fontani | MFONTANI | 1 (Milan) |
| | | |
| Renee Baecker | RENEEB | 1 (Frankfurt) |
| | | |
| Soren Lund | SLU | 1 (Copenhagen) |
| | | |
| Slaven Rezic | SREZIC | 1 (Berlin) |
| | | |
| Stefan Limbacher | STELIM | 1 (Nuremberg) |
| | | |
| Vitali Peil | VPEIL | 1 (Bielefeld) |
+----------------------+-----------+------------------------------------------+SYNOPSIS
Common Usage
use strict; use warnings;
use Map::Tube::London;
my $map = Map::Tube::London->new;
print $map->get_shortest_route('Baker Street', 'Euston Square'), "\n";You should expect the result like below:
Baker Street (Circle, Hammersmith & City, Bakerloo, Metropolitan, Jubilee), Great Portland Street (Circle, Hammersmith & City, Metropolitan), Euston Square (Circle, Hammersmith & City, Metropolitan)Alternatively,
use strict; use warnings;
use Map::Tube::London;
my $map = Map::Tube::London->new;
print $map->get_shortest_route('Baker Street', 'Euston Square')->preferred, "\n";You should now expect the result like below:
Baker Street (Circle, Hammersmith & City, Metropolitan), Great Portland Street (Circle, Hammersmith & City, Metropolitan), Euston Square (Circle, Hammersmith & City, Metropolitan)METHODS
get_shortest_routes($from, $to)
This requires $from and $to station names parameters. It returns an object of type Map::Tube::Route. On error it throws an exception of type Map::Tube::Exception.
get_all_routes($from, $to) *** EXPERIMENTAL ***
This requires $from and $to station names as parameters. It returns a ref to a list of objects of type Map::Tube::Route. On error it throws an exception of type Map::Tube::Exception.
Be careful when using this against a large map. You may encounter a warning similar to this one when running against London map:
Deep recursion on subroutine "Map::Tube::_get_all_routes"However, for comparatively smaller maps, like below, it is happy to give all routes.
A(1) ---- B(2)
/ \
C(3) -------- F(6) --- G(7) ---- H(8)
\ /
D(4) ---- E(5)name()
Returns the map name.
get_node_by_id($node_id)
Returns an object of type Map::Tube::Node for a given $node_id.
get_node_by_name($node_name)
Returns an object of type Map::Tube::Node for a given $node_name.
get_line_by_id($line_id)
Returns an object of type Map::Tube::Line.
get_line_by_name($line_name)
Returns an object of type Map::Tube::Line.
get_lines()
Returns a ref to a list of objects of type Map::Tube::Line, containing all lines in the map (but excluding "other links").
get_stations($line_name)
Returns a ref to a list of objects of type Map::Tube::Node for the line called $line_name. If $line_name is missing, it will return all stations in the map.
get_next_stations($station_name)
Returns a ref to the list of next stations from the given $station_name as objects of type Map::Tube::Node.
get_linked_stations($station_name)
Returns a ref to the list of the names of the linked stations from the given $station_name as strings.
bgcolor($color)
Set the background color for the map. Returns the new value. If called without a value, returns the unchanged previous value. Setting this is optional. Please set it before making a call to method "as_image($line_name)" in Map::Tube::Plugin::Graph. If not set, it will try to guess and may not be as good as you would expect.The $color can be a simply a color name or hash code (#RRGGBB).
line_change_penalty($penalty)
When calculating shortest routes, each change from one line to another incurs a penalty which is added to the number of hops on the route. The default penalty is 0.5. This method can be used to query the current value or to set it to a new value, which must be at least 0. (Values of 1 or higher probably do not make much sense, since the number of hops should be the dominating factor.) If you just care about the nnumber of hops but not for changes, set it to 0.
PLUGINS
Map::Tube::Plugin::Graph
The Map::Tube::Plugin::Graph plugin adds support to generate the entire map or a map for a particular line as a base64 encoded string of a PNG image. For Map::Tube v3.54 or above, you can set the background color explicitly.
use strict; use warnings;
use MIME::Base64;
use Map::Tube::London;
my $tube = Map::Tube::London->new;
# Optionally, you can override the default background color.
$tube->bgcolor("gray");
# Entire map image
my $name = $tube->name;
open(my $MAP_IMAGE, ">", "$name.png")
or die "ERROR: Can't open [$name.png]: $!";
binmode($MAP_IMAGE);
print $MAP_IMAGE decode_base64($tube->as_image);
close($MAP_IMAGE);
# Just a particular line map image
my $line = 'Bakerloo';
open(my $LINE_IMAGE, ">", "$line.png")
or die "ERROR: Can't open [$line.png]: $!";
binmode($LINE_IMAGE);
print $LINE_IMAGE decode_base64($tube->as_image($line));
close($LINE_IMAGE);Please refer to the documentation for more details.
Map::Tube::Plugin::Formatter
The Map::Tube::Plugin::Formatter plugin adds support to format objects supported by the plugin.
use strict; use warnings;
use Map::Tube::London;
my $tube = Map::Tube::London->new;
my $node = $tube->get_node_by_name('Baker Street');
print $node->to_xml, "\n\n";
print $node->to_json, "\n\n";
print $node->to_yaml, "\n\n";
print $node->to_string, "\n\n";
my $line = $tube->get_line_by_name('Metropolitan');
print $line->to_xml, "\n\n";
print $line->to_json, "\n\n";
print $line->to_yaml, "\n\n";
print $line->to_string, "\n\n";
my $route = $tube->get_shortest_route('Baker Street', 'Wembley Park');
print $route->to_xml, "\n\n";
print $route->to_json, "\n\n";
print $route->to_yaml, "\n\n";
print $route->to_string,"\n\n";Please refer to the documentation for more info.
Map::Tube::Plugin::FuzzyFind
Gisbert W. Selke built the add-on for Map::Tube to find stations and lines by name, possibly partly or inexactly specified. The module is a Moo role which gets plugged into the Map::Tube::* family automatically once it is installed.
use strict; use warnings;
use Map::Tube::London;
my $tube = Map::Tube::London->new();
print 'line matches exactly: ', scalar($tube->fuzzy_find(search => 'erloo', objects => 'lines')), "\n";
print 'line contains : ', scalar($tube->fuzzy_find(search => 'erloo', objects => 'lines', method => 'in')), "\n";Please refer to the documentation for more info.
MAP DATA FORMAT
Map data can be represented in JSON or XML format. The preferred format is JSON. Map::Tube v3.23 or above comes with a handy script map-data-converter, that can be used to change the data format of an existing map data.Below is how we can represent the sample map:
A(1) ---- B(2)
/ \
C(3) -------- F(6) --- G(7) ---- H(8)
\ /
D(4) ---- E(5)JSON
{
"name" : "sample map",
"lines" : {
"line" : [
{ "id" : "A", "name" : "A", "color" : "red" },
{ "id" : "B", "name" : "B", "color" : "#FFFF00" }
]
},
"stations" : {
"station" : [
{ "id" : "A1", "name" : "A1", "line" : "A", "link" : "B2,C3" },
{ "id" : "B2", "name" : "B2", "line" : "A", "link" : "A1,F6" },
{ "id" : "C3", "name" : "C3", "line" : "A,B", "link" : "A1,D4,F6" },
{ "id" : "D4", "name" : "D4", "line" : "A,B", "link" : "C3,E5" },
{ "id" : "E5", "name" : "E5", "line" : "B", "link" : "D4,F6" },
{ "id" : "F6", "name" : "F6", "line" : "B", "link" : "B2,C3,E5" },
{ "id" : "G7", "name" : "G7", "line" : "B", "link" : "F6,H8" },
{ "id" : "H8", "name" : "H8", "line" : "B", "link" : "G7" }
]
}
}XML
<?xml version="1.0" encoding="UTF-8"?>
<tube name="sample map">
<lines>
<line id="A" name="A" color="red" />
<line id="B" name="B" color="#FFFF00"/>
</lines>
<stations>
<station id="A1" name="A1" line="A" link="B2,C3" />
<station id="B2" name="B2" line="A" link="A1,F6" />
<station id="C3" name="C3" line="A,B" link="A1,D4,F6"/>
<station id="D4" name="D4" line="A,B" link="C3,E5" />
<station id="E5" name="E5" line="B" link="D4,F6" />
<station id="F6" name="F6" line="B" link="B2,C3,E5"/>
<station id="G7" name="G7" line="B" link="F6,H8" />
<station id="H8" name="H8" line="B" link="G7" />
</stations>
</tube>MAP VALIDATION
DATA VALIDATION
The package Test::Map::Tube can easily be used to validate raw map data. Anyone building a new map using Map::Tube is advised to have a unit test as a part of their distribution. Just like in Map::Tube::London package, there is a unit test somewhat like below:
use strict; use warnings;
use Test::More;
use Map::Tube::London;
use Test::Map::Tube;
ok_map(Map::Tube::London->new);FUNCTIONAL VALIDATION
The package Test::Map::Tube can easily be used to validate map basic functions provided by Map::Tube.
use strict; use warnings;
use Test::More;
use Test::Map::Tube;
use Map::Tube::London;
ok_map_functions(Map::Tube::London->new);It can also easily be used to validate map routing functions provided by Map::Tube:
use strict; use warnings;
use Test::More;
use Test::Map::Tube;
use Map::Tube::London;
my $map = Map::Tube::London->new;
my @routes = (
"Route 1|Tower Gateway|Aldgate|Tower Gateway,Tower Hill,Aldgate",
"Route 2|Liverpool Street|Monument|Liverpool Street,Bank,Monument",
);
ok_map_routes($map, \@routes);AUTHOR
Mohammad Sajid Anwar, <mohammad.anwar at yahoo.com>
REPOSITORY
https://github.com/manwar/Map-Tube
SEE ALSO
CONTRIBUTORS
Michal Špaček,
<skim at cpan.org>Slaven Rezic,
<srezic at cpan.org>Gisbert W. Selke,
<gws at cpan.org>Toby Inkster,
<tobyink at cpan.org>Ed J,
<etj at cpan.org>
BUGS
Please report any bugs or feature requests through the web interface at https://github.com/manwar/Map-Tube/issues. 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 Map::TubeYou can also look for information at:
BUG Report
CPAN Ratings
Search MetaCPAN
LICENSE AND COPYRIGHT
Copyright (C) 2010 - 2025 Mohammad Sajid Anwar.
This program is free software; you can redistribute it and / or modify it under the terms of the the Artistic License (2.0). You may obtain a copy of the full license at:
http://www.perlfoundation.org/artistic_license_2_0
Any use, modification, and distribution of the Standard or Modified Versions is governed by this Artistic License.By using, modifying or distributing the Package, you accept this license. Do not use, modify, or distribute the Package, if you do not accept this license.
If your Modified Version has been derived from a Modified Version made by someone other than you,you are nevertheless required to ensure that your Modified Version complies with the requirements of this license.
This license does not grant you the right to use any trademark, service mark, tradename, or logo of the Copyright Holder.
This license includes the non-exclusive, worldwide, free-of-charge patent license to make, have made, use, offer to sell, sell, import and otherwise transfer the Package with respect to any patent claims licensable by the Copyright Holder that are necessarily infringed by the Package. If you institute patent litigation (including a cross-claim or counterclaim) against any party alleging that the Package constitutes direct or contributory patent infringement,then this Artistic License to you shall terminate on the date that such litigation is filed.
Disclaimer of Warranty: THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "AS IS' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES. THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT PERMITTED BY YOUR LOCAL LAW. UNLESS REQUIRED BY LAW, NO COPYRIGHT HOLDER OR CONTRIBUTOR WILL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THE PACKAGE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.