/ 
Map-Tube-Generic-v0.1.0
/ Map::Tube::Generic

NAME

Map::Tube::Generic - Interface to a map specified at runtime.

SYNOPSIS

use Map::Tube::Generic;
my $tube = Map::Tube::Generic->new('London');

my $route = $tube->get_shortest_route( 'Embankment', 'Whitechapel');

print "Route: $route\n";

DESCRIPTION

This module allows to find the shortest route between any two given stations in some metro network. The name of the network is specified at runtime. Most interesting methods are provided by the role Map::Tube.

METHODS

CONSTRUCTOR

use Map::Tube::Generic;
my $tube = Map::Tube::Generic->new( location  => <map_name>,
                                    namespace => <namespace>,
                                    map       => <map_object>,
                                    xml       => <not implemented yet>,
                                    json      => <not implemented yet>,
                                    ...
                                  );

The constructor takes arguments specifying which concrete module will supply the information on the metro map. The module must do the Map::Tube role. Almost all method calls will just be delegated to that underlying module, so they are not documented here.

ARGUMENTS

  • location

    The easiest way to specify a metro map is to pass its name via the location argument. This can be just the "base name", e.g., "London". Case does not matter, so "london" or "LONDON" will also do. The module implementing the metro map will be looked for in all the namespaces provided by the namespace argument (q.v.). If more than one module is found, one will be picked at random.

    Alternatively, the location may also be a fully qualified module name, e.g., "Map::Tube::London". In this form, case matters. (This is bound to change in a future version.)

    In any case, the module chosen must do the Map::Tube role.

    The value of the argument must be a string or a code reference that will produce a string.

    Either location or map (but not both) must be specified.

  • namespace

    Optionally, this is a string providing the "namespace" under which the module may reside, e.g., "Map::Tube". (This is also the default value.) In all likelihood, the default value will always suffice, but here you can change it, should the need arise. You may also specify a reference to an array of strings so that multiple namespaces will be searched, or a code reference that will return a string or a reference to an array of strings.

    Note that the namespace(s) will be ignored if the location is given as the fully qualified module name, or if the map argument is used.

  • map

    If you already have an instance of the concrete map network you may pass this in via this argument. It must do the Map::Tube role. Frankly, though, if you already have an instantiated map, you can use it directly, and there is no advantage to wrapping it in a Map::Tube::Generic object.

  • xml

    Not yet implemented.

  • json

    Not yet implemented.

  • ...

    Further arguments may be specified. These will be passed through to the underlying module if and when instantiating it.

location

The "base name" of the underlying module will be returned (e.g., for a Map::Tube::London, it would return "London").

BUILD

If on construction the location argument was used, this will be the value returned. If the map argument was used, the "base name" of the underlying module will be returned (e.g., for a Map::Tube::London, it would return "London").

namespace

Returns the value of the namespace argument from the constructor call (or the default "Map::Tube"), always as a reference to an array of strings.

map

Returns the instance of the underlying concrete metro map.

list_maps( <args...> )

This method may be called either as a class or as an instance method. It returns a reference to a hash whose keys are the module names of available metro maps, optionally filtered by some criteria specified in the optional arguments:

  • name => ...

    If the name of the module implementing the metro map for an area of interest is known, it can be specified here. (Case does not matter.)

  • namepattern => ...

    If the exact name is not known, the "base names" may instead be filtered by a regular expression, e.g., namepattern => qr/^K/ for locations starting with the letter "K". For the pattern, in general, case does matter, but you can easily supply a case-independent pattern.

  • namespace => ...

    The "namespaces" under which to search, specified as a string or a reference to an array of strings. The default is "Map::Tube", which will suffice in practically all cases. (Note that this argument is completely unrelated to what you may, or may not, have given as the namespace argument for the constructor.)

  • verify => ...

    Ordinarily, the search process just goes by the name of the modules but does not check whether the modules found really implement metro maps, because this requires loading each candidate module and is thus somewhat time-consuming. If the option verify with a true value is used, then the additional checks will take place.

The return value is a reference to a hash, where the keys are the fully qualified module names. The values are references to hashes with the keys "filepath", stating the @INC-based path in the file system from where this module would be loaded, and "location", stating the "basename" of the module. If the verify argument was true, there will also be a key "name", which will reflect the name of the metro network as specified in the data for the metro network. (This may be undef.) If the same fully qualified module is found under different paths as per @INC, only the last one will be returned.

can

This method can be used in order to find out which methods are supported by the underlying Map::Tube object. E.g., it can be used to find out whether the tube data are avaialble through the xml( ) or the json( ) method.

BUILD

This is an internal method used in constructing the Map::Tube object.

ERRORS

If something goes wrong, maybe because the specified Map::Tube module was not found, the constructor will die.

CONTRIBUTING

If you find a bug or have an idea for a useful extension, your contribution via this module's issue tracker at https://github.com/gwselke/Map-Tube-Generic/issues is welcome! Pull requests are also appreciated!

AUTHOR

Gisbert W. Selke, TapirSoft Selke & Selke GbR.

COPYRIGHT AND LICENCE

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

SEE ALSO

Map::Tube