The first post in this series introduced us to Map::Tube. There, we built the fundamental structure of the Map::Tube::Hannover module and created the basic map file for the Hannover tram network. This time, we’ll look at a map file’s structure and extend the network. At the end, we’ll visualise a graph of the railway network we’ve created so far.

Structural understanding

Now that we’ve created a basic map, our goal is to understand the structure of Map::Tube maps a bit more. This way we won’t trip up when extending our map to a more full network.

As a reminder, the map file we have at present looks like this:

{
    "name"  : "Hannover",
    "lines" : {
        "line" : [
            {
                "id" : "L1",
                "name" : "Linie 1"
            }
        ]
    },
    "stations" : {
        "station" : [
            {
                "id" : "H1",
                "name" : "Hauptbahnhof",
                "line" : "L1",
                "link" : "H2"
            },
            {
                "id" : "H2",
                "name" : "Langenhagen",
                "line" : "L1",
                "link" : "H1"
            }
        ]
    }
}

Let’s consider each of the elements in this map.

Each map can have a name. This is a string providing a human-readable name of the map, specified by the name attribute. Even though a map doesn’t necessarily have to have a name, it’s very handy to have, hence I’ve included it here.

Each map has one lines attribute which contains a line array containing the individual lines in the network. There should be at least one line in the map. Each line has to have an ID (specified by the id attribute) and a name (specified by the name attribute).

A valid map must also have at least two stations on one line. We define stations in the stations attribute. It contains a station array of individual stations. A given station must have an ID (given by the id attribute) and a name (given by the name attribute). We must assign a station to at least one of the lines specified in the lines attribute. It should also link to at least one other station by specifying the relevant ID in its link attribute.

There are more things that a map file can contain. For instance, a line can have a color attribute to specify its colour. Also, stations can link to other stations indirectly by using the other_link attribute. This way we can represent connections via something like a tunnel, passageway or escalator.

For all the gory details, check out the formal requirements for maps section of the Map::Tube::Cookbook documentation.

Extending the network

Where to from here? Well, Linie 1 needs more stations to better reflect the situation in real life. Also, the network needs more lines as well as connections between those lines, again reflecting reality better. Fortunately, these are things we can test, so we’ll expand the test suite as we go along.

We’d best get on with it then!

Walking the line

We currently only have two stations in our network. That’s not enough! To flesh things out a bit, let’s add some more stations along Linie 1. To be specific, let’s add the other terminal station on that line, Sarstedt, as well as stations between Hauptbahnhof and the respective terminal stations. I’ve decided to choose Kabelkamp on the north side and Laatzen on the south side.

One thing that we’re going to have to be careful with is giving each station an ID. How are we going to do that in some kind of systematic way? The first thing I thought of was to go left to right across the network. By this, I mean that the station furthest in the west along the given line is what I shall consider to be the first station along that line. This decision is arbitrary, but it should be good enough for our purposes.

Although it’s not clear from the Üstra network plan,¹ it turns out that Langenhagen is further west than Sarstedt. So, I chose Langenhagen to be the first station along that line. Because this is also the first line in the network, Langenhagen has the honour of having the first station ID in the map file.

Thus, for Linie 1, we have these stations, their respective new labels, and their links:

Our goal for now is to have these stations connected along Linie 1 with their respective IDs and links. We’ll achieve this goal in small steps so that we’re not changing too much in one go.

Note also that I’m doing all this work by hand. This allows us to see how all the pieces fit together, which is one main goal of this HOWTO. In reality, however, a railway network is much more complex and with many more stations. Thus, to create the full network, one would need an automated way to extract line and station data from e.g. OpenStreetMap. We would then collect this information and export it in the form that Map::Tube needs. But, that’s not important right now, so we’ll continue adding stations and lines manually.

Each station in our current network describes the connection it has to other stations via its link attribute. Stations at the ends of the line only link to one other station because that’s what it means for a station to be at the end of a line. The remaining stations link to two stations each, connecting one end of the line to the other like the proverbial string of pearls. In general, one can have many links at a given station, especially if many lines cross at a given station. Right now we don’t need this extra complexity and will keep things simple.

Let’s kick-start the implementation of the full list of stations for Linie 1 by adding the station Sarstedt. To get the ball rolling, we’ll start (as usual) with a test.

What we want to check is that there is a route from Langenhagen to Sarstedt and that stations along that route match our expectations. How do we go about doing this? Again, the Map::Tube framework comes to our rescue. It provides the ok_map_routes() assertion in the Test::Map::Tube module which we can use to check our route. Also, the docs help again, by providing a simple route-checking example.

Before we add this test, let’s remove some code duplication in our test suite. Note that currently, we’re creating a Map::Tube::Hannover object twice in the tests. Really, we only need to do that once. Let’s instantiate a single object and pass that to our test functions.

Assign a variable called $hannover to the instantiated Map::Tube::Hannover object before the ok_map*() functions, like so:

my $hannover = Map::Tube::Hannover->new;

Then replace Map::Tube::Hannover->new in the calls to the ok_map*() functions with the new variable:

ok_map($hannover);
ok_map_functions($hannover);

Our test file (t/map-tube-hannover.t) now looks like this:

use strict;
use warnings;

use Test::More;

use Map::Tube::Hannover;
use Test::Map::Tube;

my $hannover = Map::Tube::Hannover->new;

ok_map($hannover);
ok_map_functions($hannover);

done_testing();

Running this test with prove, we find that the tests still pass.

$ prove -lr t/map-tube-hannover.t
t/map-tube-hannover.t .. ok
All tests successful.
Files=1, Tests=2,  0 wallclock secs ( 0.04 usr  0.00 sys +  0.48 cusr  0.05 csys =  0.57 CPU)
Result: PASS

Great! That’s worthy of a commit:

$ git commit -m "Extract repeated object instantiation into variable in tests" t/map-tube-hannover.t
[main f9005d1] Extract repeated object instantiation into variable in tests
 1 file changed, 4 insertions(+), 2 deletions(-)

Now we’re ready to check the route from Langenhagen to Sarstedt via Hauptbahnhof. We start by defining an array of strings containing route descriptions:

my @routes = (
    "Route 1|Langenhagen|Sarstedt|Langenhagen,Hauptbahnhof,Sarstedt",
);

Although this array only contains one element, we’ll be extending it later, so using a plural name is ok in this situation. Also, the ok_map_routes() test function requires an array reference as one of its arguments, hence creating an array now is sensible forward-thinking.

We check the route by calling ok_map_routes() like so:

ok_map_routes($hannover, \@routes);

The complete test file is now:

use strict;
use warnings;

use Test::More;

use Map::Tube::Hannover;
use Test::Map::Tube;

my $hannover = Map::Tube::Hannover->new;

ok_map($hannover);
ok_map_functions($hannover);

my @routes = (
    "Route 1|Langenhagen|Sarstedt|Langenhagen,Hauptbahnhof,Sarstedt",
);

ok_map_routes($hannover, \@routes);

done_testing();

We don’t expect the tests to pass. Even so, what feedback do they give us?

$ prove -lr t/map-tube-hannover.t
t/map-tube-hannover.t .. 1/? Map::Tube::get_node_by_name(): ERROR: Invalid Station Name [Sarstedt]. (status: 101) file /home/cochrane/perl5/perlbrew/perls/perl-5.38.3/lib/site_perl/5.38.3/Map/Tube.pm on line 897
# Tests were run but no plan was declared and done_testing() was not seen.
# Looks like your test exited with 255 just after 2.
t/map-tube-hannover.t .. Dubious, test returned 255 (wstat 65280, 0xff00)
All 2 subtests passed

Test Summary Report
-------------------
t/map-tube-hannover.t (Wstat: 65280 (exited 255) Tests: 2 Failed: 0)
  Non-zero exit status: 255
  Parse errors: No plan found in TAP output
Files=1, Tests=2,  1 wallclock secs ( 0.03 usr  0.01 sys +  0.47 cusr  0.05 csys =  0.56 CPU)
Result: FAIL

Ok, so Map::Tube::Hannover doesn’t know about the station Sarstedt. Let’s update the map file and add a station entry for Sarstedt, linking it to Hauptbahnhof at this step. We’ll also relabel Langenhagen and Hauptbahnhof and reorder the entries within the map file so that Langenhagen is at the top and Sarstedt at the bottom, thus matching the north-south direction of this line. Remember that the links I’m using right now aren’t those that we want in the end: this is merely a step along that path.

Our list of stations now looks like this:

    "stations" : {
        "station" : [
            {
                "id" : "H1",
                "name" : "Langenhagen",
                "line" : "L1",
                "link" : "H3"
            },
            {
                "id" : "H3",
                "name" : "Hauptbahnhof",
                "line" : "L1",
                "link" : "H1,H5"
            },
            {
                "id" : "H5",
                "name" : "Sarstedt",
                "line" : "L1",
                "link" : "H3"
            }
        ]
    }

Testing this change:

$ prove -lr t/map-tube-hannover.t
t/map-tube-hannover.t .. ok
All tests successful.
Files=1, Tests=3,  1 wallclock secs ( 0.06 usr  0.00 sys +  0.49 cusr  0.05 csys =  0.60 CPU)
Result: PASS

Great! We’ve got a working route from Langenhagen to Sarstedt! Let’s add in the stations that we left out in the last step.

Update the routes test to this:

my @routes = (
    "Route 1|Langenhagen|Sarstedt|Langenhagen,Kabelkamp,Hauptbahnhof,Laatzen,Sarstedt",
);

ok_map_routes($hannover, \@routes);

And check what the test output tells us:

$ prove -lr t/map-tube-hannover.t
t/map-tube-hannover.t .. 1/? Map::Tube::get_node_by_name(): ERROR: Invalid Station Name [Kabelkamp]. (status: 101) file /home/cochrane/perl5/perlbrew/perls/perl-5.38.3/lib/site_perl/5.38.3/Test/Map/Tube.pm on line 1434
# Tests were run but no plan was declared and done_testing() was not seen.
# Looks like your test exited with 255 just after 2.
t/map-tube-hannover.t .. Dubious, test returned 255 (wstat 65280, 0xff00)
All 2 subtests passed

Test Summary Report
-------------------
t/map-tube-hannover.t (Wstat: 65280 (exited 255) Tests: 2 Failed: 0)
  Non-zero exit status: 255
  Parse errors: No plan found in TAP output
Files=1, Tests=2,  0 wallclock secs ( 0.03 usr  0.00 sys +  0.50 cusr  0.04 csys =  0.57 CPU)
Result: FAIL

Ok, Kabelkamp is missing. Adding its entry to the map file after Langenhagen, and updating the links for the Langenhagen and Hauptbahnhof stations, we now have this stations list:

    "stations" : {
        "station" : [
            {
                "id" : "H1",
                "name" : "Langenhagen",
                "line" : "L1",
                "link" : "H2"
            },
            {
                "id" : "H2",
                "name" : "Kabelkamp",
                "line" : "L1",
                "link" : "H1,H3"
            },
            {
                "id" : "H3",
                "name" : "Hauptbahnhof",
                "line" : "L1",
                "link" : "H2,H5"
            },
            {
                "id" : "H5",
                "name" : "Sarstedt",
                "line" : "L1",
                "link" : "H3"
            }
        ]
    }

and re-running the tests, we get:

$ prove -lr t/map-tube-hannover.t
t/map-tube-hannover.t .. 1/? Map::Tube::get_node_by_name(): ERROR: Invalid Station Name [Laatzen]. (status: 101) file /home/cochrane/perl5/perlbrew/perls/perl-5.38.3/lib/site_perl/5.38.3/Test/Map/Tube.pm on line 1434
# Tests were run but no plan was declared and done_testing() was not seen.
# Looks like your test exited with 255 just after 2.
t/map-tube-hannover.t .. Dubious, test returned 255 (wstat 65280, 0xff00)
All 2 subtests passed

Test Summary Report
-------------------
t/map-tube-hannover.t (Wstat: 65280 (exited 255) Tests: 2 Failed: 0)
  Non-zero exit status: 255
  Parse errors: No plan found in TAP output
Files=1, Tests=2,  0 wallclock secs ( 0.03 usr  0.00 sys +  0.48 cusr  0.05 csys =  0.56 CPU)
Result: FAIL

The tests are still failing, but we’re getting the failure that we expect to see. In other words, we expect to see the error about Kabelkamp disappear but expect to see an error about Laatzen. This is because we haven’t added Laatzen yet. Adding the station entry for Laatzen and fixing up the links in the stations list, we get:

    "stations" : {
        "station" : [
            {
                "id" : "H1",
                "name" : "Langenhagen",
                "line" : "L1",
                "link" : "H2"
            },
            {
                "id" : "H2",
                "name" : "Kabelkamp",
                "line" : "L1",
                "link" : "H1,H3"
            },
            {
                "id" : "H3",
                "name" : "Hauptbahnhof",
                "line" : "L1",
                "link" : "H2,H4"
            },
            {
                "id" : "H4",
                "name" : "Laatzen",
                "line" : "L1",
                "link" : "H3,H5"
            },
            {
                "id" : "H5",
                "name" : "Sarstedt",
                "line" : "L1",
                "link" : "H4"
            }
        ]
    }

You’ll find that the tests now pass:

$ prove -lr t/map-tube-hannover.t
t/map-tube-hannover.t .. ok
All tests successful.
Files=1, Tests=3,  0 wallclock secs ( 0.03 usr  0.00 sys +  0.51 cusr  0.03 csys =  0.57 CPU)
Result: PASS

Yay!

That’s worth another commit:

$ git commit -m "Extend list of stations on Linie 1" share/hannover-map.json t/map-tube-hannover.t
[main a742db3] Extend list of stations on Linie 1
 2 files changed, 27 insertions(+), 3 deletions(-)

Seeing the bigger picture

To visualise what our map looks like, we can use the Map::Tube::Plugin::Graph plugin. Let’s install the plugin and see what it does:

$ cpanm Map::Tube::Plugin::Graph

Note that you might need to install Graphviz before installing the plugin, e.g.:

$ sudo apt install graphviz

We’re going to create a small program to convert our Map::Tube map into a PNG image of a Graphviz graph. To keep things nice and tidy, let’s create a bin/ directory to keep our program in:

$ mkdir bin

Now, with your favourite editor, open a file called bin/map2image.pl and enter into it the following code:

use strict;
use warnings;

use lib qw(lib);

use Map::Tube::Hannover;

my $hannover = Map::Tube::Hannover->new;
my $map_name = $hannover->name;

open(my $map_image, ">", "$map_name.png")
    or die "ERROR: Can't open $map_name.png: $!";
binmode($map_image);
print $map_image $hannover->as_png;
close($map_image);

# vim: expandtab shiftwidth=4

In this program, we specify the location of the lib directory explicitly. This saves us from having to use -I lib when invoking perl on the command line. We then import our Map::Tube::Hannover module and instantiate a new Map::Tube::Hannover object. We also save the map’s name for later use as part of the output image filename.

Then we open the output file and barf if something went wrong. Since the output image is a PNG, we need to set the output mode to binary. After that, we print the output of the Map::Tube::Plugin::Graph plugin’s as_png() method² to file and close the file.

Running our new program like so:

$ perl bin/map2image.pl

produces an image file called Hannover.png in the base project directory. Opening this image in an image viewer, you should output similar to this:

Nice!

It’s fairly obvious from the input map file that our network is a straight line. Even so, it’s nice to see this in an image rather than having to deduce it from only the map file’s structure.

It’ll be handy having such a tool around when developing the map further, so let’s add it to the repository and commit that change:

$ git commit -m "Add program to convert map into a PNG image"
[main bb709e8] Add program to convert map into a PNG image
 1 file changed, 17 insertions(+)
 create mode 100644 bin/map2image.pl

Wrapping up

We didn’t do as much this time, but that’s OK. We put in a lot of work in the previous post getting everything up and running, so taking it easy for a bit will let us catch our breath. Still, we weren’t mucking around. We used test-driven development to extend the tram network map for Hannover and wrote a small program to visualise it. We’re making steady progress toward our goal: a working Map::Tube map that we can use to find our way from station to station.

The next post in the series will describe how to add more lines to the network as well as how to use colour to tell them apart. Until then, keep cool till after school!

Originally posted on https://peateasea.de.

Image credits: Hannover coat of arms: Wikimedia Commons, U-Bahn symbol: Wikimedia Commons, Langenhagen coat of arms: Wikimedia Commons, Sarstedt coat of arms: Wikimedia Commons

Thumbnail credits: Swiss Cottage Underground Station (Jubilee Line) by Hugh Llewelyn

Mohammad Sajid Anwar’s post in last year’s Perl Advent Calendar about his Map::Tube module intrigued me. I decided I wanted to build such a map for the tram network in the city where I live: Hannover, Germany. Along the way, I thought it’d be nice to have a detailed HOWTO explaining the steps needed to create a Map::Tube map for one’s city of interest. Since I enjoy explaining things in detail, this got … long. So I broke it up into parts.

Welcome to the first post in a five-part series about how to create Map::Tube maps.

Series introduction

Originally I wrote this as a single post, which made it, you might say, rather protracted. I’ve thus split it up into five separate posts, each building upon the previous. This way each is more digestible and hopefully the reader doesn’t–in the words of P.D.Q. Bach–fall into a confused slumber. Let’s see how I manage…

In this five-part series, we’re going to:

• Set up a Perl module and test-drive development of the most basic Map::Tube map we can create (this post).
• Understand the structure of Map::Tube map files and then extend the map to more stations along the first line, displaying a graph of the line.
• Continue test-driving our map and add more lines and their stations, using colour to tell the lines apart.
• Make the map better reflect the real tram network in Hannover, Germany and start finding routes between stations in the network.
• Learn the advanced topic of how to create indirect connections between stations.

This first post is the longest because I spend time discussing how to set up a module from scratch. Experienced readers can skip this section if they so wish and go directly to the section about building the Map::Tube map file guided by tests.

As I mentioned in my post about finding all tram stops in Hannover, Mohammad Sajid Anwar’s Perl Advent Calendar article about his Perl-based routing network module for railway systems interested me and I wanted to create my own. This series of posts will use Hannover as the main focus to show you how to build Map::Tube maps, giving you the information you need to create your own.

There’s a lot to get through, so we’d better get started!

Creating a stub module

Each map for a given railway network is a Perl module in its own right. Hence, the first thing we need to do is create a stub module for our project. Maps for specific cities follow the same naming pattern: Map::Tube::<city-name>. Their project directories follow a similar naming pattern: Map-Tube-<city-name>. Thus, for our current example, the goal is to create a module called Map::Tube::Hannover within a directory named Map-Tube-Hannover. Let’s do that now.

Starting from scratch

For the rest of the discussion, I’m going to assume that you have a recent perlbrew-ed Perl¹ and that you’ve set that all up properly.

As mentioned in the perlnewmod documentation, the recommended way to create a new stub module (including its files and directory layout) is to use the module-starter program. This isn’t distributed with Perl, so we have to install it before we can use it. It’s part of the Module::Starter distribution; install it now with cpanm:

$ cpanm Module::Starter

To create our stub Map::Tube::Hannover module we run module-starter, giving it some required module meta-data:

$ module-starter --module=Map::Tube::Hannover --author="Paul Cochrane" --email=ptc@cpan.org \
    --ignores=git --ignores=manifest
Created starter directories and files

The --ignores=git and --ignores=manifest options create .gitignore and MANIFEST.SKIP files for us. Thus, anything we don’t need in the repository or the final CPAN distribution is skipped and ignored from the get-go. This is handy as it saves mucking about with admin stuff when we could be getting going with our shiny new module.

The module-starter command created a directory called Map-Tube-Hannover in the current directory and filled it with some standard files every Perl distribution/module should have. Let’s enter the directory and see what we’ve got.

$ cd Map-Tube-Hannover
$ tree
.
├── Changes
├── lib
│   └── Map
│       └── Tube
│           └── Hannover.pm
├── Makefile.PL
├── MANIFEST.SKIP
├── README
├── t
│   ├── 00-load.t
│   ├── manifest.t
│   ├── pod-coverage.t
│   └── pod.t
└── xt
    └── boilerplate.t

5 directories, 10 files

We see that module-starter created a Perl module file (lib/Map/Tube/Hannover.pm) for our planned Map::Tube::Hannover module. The command also created the associated (sub-)directory structure, a test directory with some useful initial tests, as well as various module-related build and information files.

This is a great starting point, so let’s save this state by creating a Git repository in this directory and adding the files to the repo in an initial commit.²

$ git init
Initialized empty Git repository in /path/to/Map-Tube-Hannover/.git/
$ git add .
$ git commit -m "Initial import of Map::Tube::Hannover stub module files"
[main (root-commit) 7bd778e] Initial import of Map::Tube::Hannover stub module files
 11 files changed, 380 insertions(+)
 create mode 100644 .gitignore
 create mode 100644 Changes
 create mode 100644 MANIFEST.SKIP
 create mode 100644 Makefile.PL
 create mode 100644 README
 create mode 100644 lib/Map/Tube/Hannover.pm
 create mode 100644 t/00-load.t
 create mode 100644 t/manifest.t
 create mode 100644 t/pod-coverage.t
 create mode 100644 t/pod.t
 create mode 100644 xt/boilerplate.t

If you want to follow along with how I built things, the Git repo for this project is on GitHub.

Running all tests in the stub module

Personally, I love tests. They help reduce risk and (if the project has high test coverage) give me confidence that the code is doing what I expect it to do. They also help me be more fearless when refactoring a codebase. A good test suite can make for a wonderful development experience.

So, before we start implementing things, let’s build the project and run the test suite so that we know that everything is working as we expect. Yes, I expect the authors of Module::Starter will have created everything correctly, but it’s a good feeling to know that one is starting from a solid foundation before changing anything.

To build the project, we create its Makefile by running Makefile.PL with perl. Then we simply call make test:

$ perl Makefile.PL
Generating a Unix-style Makefile
Writing Makefile for Map::Tube::Hannover
Writing MYMETA.yml and MYMETA.json
$ make test
cp lib/Map/Tube/Hannover.pm blib/lib/Map/Tube/Hannover.pm
PERL_DL_NONLAZY=1 "/home/cochrane/perl5/perlbrew/perls/perl-5.38.3/bin/perl" "-MExtUtils::Command::MM" "-MTest::Harness" "-e" "undef *Test::Harness::Switches; test_harness(0, 'blib/lib', 'blib/arch')" t/*.t
t/00-load.t ....... 1/? # Testing Map::Tube::Hannover 0.01, Perl 5.038003, /home/cochrane/perl5/perlbrew/perls/perl-5.38.3/bin/perl
t/00-load.t ....... ok
t/manifest.t ...... skipped: Author tests not required for installation
t/pod-coverage.t .. skipped: Author tests not required for installation
t/pod.t ........... skipped: Author tests not required for installation
All tests successful.
Files=4, Tests=1,  0 wallclock secs ( 0.04 usr  0.01 sys +  0.34 cusr  0.03 csys =  0.42 CPU)
Result: PASS

Cool! The tests passed! Erm, ‘test’, I should say, as only one ran. That test showed that the module can be loaded (this is what t/00-load.t does). However, some of our tests didn’t run because they’re only to be run by module authors. To run these tests, we need to set the RELEASE_TESTING environment variable:

$ RELEASE_TESTING=1 make test
PERL_DL_NONLAZY=1 "/home/cochrane/perl5/perlbrew/perls/perl-5.38.3/bin/perl" "-MExtUtils::Command::MM" "-MTest::Harness" "-e" "undef *Test::Harness::Switches; test_harness(0, 'blib/lib', 'blib/arch')" t/*.t
t/00-load.t ....... 1/? # Testing Map::Tube::Hannover 0.01, Perl 5.038003, /home/cochrane/perl5/perlbrew/perls/perl-5.38.3/bin/perl
t/00-load.t ....... ok
t/manifest.t ...... skipped: Test::CheckManifest 0.9 required
t/pod-coverage.t .. skipped: Test::Pod::Coverage 1.08 required for testing POD coverage
t/pod.t ........... skipped: Test::Pod 1.22 required for testing POD
All tests successful.
Files=4, Tests=1,  0 wallclock secs ( 0.02 usr  0.01 sys +  0.32 cusr  0.04 csys =  0.39 CPU)
Result: PASS

Hrm, the author tests were still skipped. We need to install some modules from CPAN to get everything running:

$ cpanm Test::CheckManifest Test::Pod::Coverage Test::Pod

This time the author tests run, but the t/manifest.t test fails:

$ RELEASE_TESTING=1 make test
PERL_DL_NONLAZY=1 "/home/cochrane/perl5/perlbrew/perls/perl-5.38.3/bin/perl" "-MExtUtils::Command::MM" "-MTest::Harness" "-e" "undef *Test::Harness::Switches; test_harness(0, 'blib/lib', 'blib/arch')" t/*.t
t/00-load.t ....... 1/? # Testing Map::Tube::Hannover 0.01, Perl 5.038003, /home/cochrane/perl5/perlbrew/perls/perl-5.38.3/bin/perl
t/00-load.t ....... ok
t/manifest.t ...... Bailout called.  Further testing stopped:  Cannot find a MANIFEST. Please check!
t/manifest.t ...... Dubious, test returned 255 (wstat 65280, 0xff00)
Failed 1/1 subtests
FAILED--Further testing stopped: Cannot find a MANIFEST. Please check!
make: *** [Makefile:851: test_dynamic] Error 255

Weird! I didn’t expect that.

It turns out that we’ve not created an initial MANIFEST file. That’s easy to fix, though. We only need to run make with the manifest target:

$ make manifest
"/home/cochrane/perl5/perlbrew/perls/perl-5.38.3/bin/perl" "-MExtUtils::Manifest=mkmanifest" -e mkmanifest
Added to MANIFEST: Changes
Added to MANIFEST: lib/Map/Tube/Hannover.pm
Added to MANIFEST: Makefile.PL
Added to MANIFEST: MANIFEST
Added to MANIFEST: README
Added to MANIFEST: t/00-load.t
Added to MANIFEST: t/manifest.t
Added to MANIFEST: t/pod-coverage.t
Added to MANIFEST: t/pod.t
Added to MANIFEST: xt/boilerplate.t

So far, so good. Let’s see what the tests say now:

$ RELEASE_TESTING=1 make test
PERL_DL_NONLAZY=1 "/home/cochrane/perl5/perlbrew/perls/perl-5.38.3/bin/perl" "-MExtUtils::Command::MM" "-MTest::Harness" "-e" "undef *Test::Harness::Switches; test_harness(0, 'blib/lib', 'blib/arch')" t/*.t
t/00-load.t ....... 1/? # Testing Map::Tube::Hannover 0.01, Perl 5.038003, /home/cochrane/perl5/perlbrew/perls/perl-5.38.3/bin/perl
t/00-load.t ....... ok
t/manifest.t ...... ok
t/pod-coverage.t .. ok
t/pod.t ........... ok
All tests successful.
Files=4, Tests=4,  0 wallclock secs ( 0.04 usr  0.00 sys +  0.41 cusr  0.05 csys =  0.50 CPU)
Result: PASS

That’s better!

You’ll note that although we’ve created some files not tracked by Git (e.g. the Makefile and MANIFEST files), the working directory is still clean:

$ git status
On branch main
nothing to commit, working tree clean

This is because the --ignores=git option passed to module-starter generates a .gitignore file which ignores the MANIFEST among other such files. Nice!

Specifying test dependencies

Since we installed some modules as part of getting everything running, we need to update our dependencies. These dependencies aren’t required to get the module up and running. Nor are they strictly required to test everything, because they’re tests for module authors, not for users of the module. However, since we’re creating a module, we’re our own module author, so it’s a good idea to set up the author tests. Thus, we need to specify them as recommended test-stage prerequisites. Neil Bowers has a good blog post about specifying dependencies for your CPAN distribution which describes things in more detail. For our case here, this boils down to inserting the following code at the end of the %WriteMakefileArgs hash in Makefile.PL:

    # rest of %WriteMakefileArgs content
    META_MERGE => {
        "meta-spec" => { version => 2 },
        prereqs => {
            test => {
                recommends => {
                    'Test::CheckManifest' => '0.9',
                    'Test::Pod::Coverage' => '1.08',
                    'Test::Pod' => '1.22',
                },
            },
        },
    },

Let’s try running the tests again to make sure that we haven’t broken anything:

$ RELEASE_TESTING=1 make test
Makefile out-of-date with respect to Makefile.PL
Cleaning current config before rebuilding Makefile...
make -f Makefile.old clean > /dev/null 2>&1
"/home/cochrane/perl5/perlbrew/perls/perl-5.38.3/bin/perl" Makefile.PL
Checking if your kit is complete...
Looks good
Generating a Unix-style Makefile
Writing Makefile for Map::Tube::Hannover
Writing MYMETA.yml and MYMETA.json
==> Your Makefile has been rebuilt. <==
==> Please rerun the make command.  <==
false
make: *** [Makefile:809: Makefile] Error 1

Oops, we forgot to rebuild the Makefile. Let’s do that quickly:

$ perl Makefile.PL
Generating a Unix-style Makefile
Writing Makefile for Map::Tube::Hannover
Writing MYMETA.yml and MYMETA.json

Now the test suite runs and passes as we hope:

$ RELEASE_TESTING=1 make test
PERL_DL_NONLAZY=1 "/home/cochrane/perl5/perlbrew/perls/perl-5.38.3/bin/perl" "-MExtUtils::Command::MM" "-MTest::Harness" "-e" "undef *Test::Harness::Switches; test_harness(0, 'blib/lib', 'blib/arch')" t/*.t
t/00-load.t ....... 1/? # Testing Map::Tube::Hannover 0.01, Perl 5.038003, /home/cochrane/perl5/perlbrew/perls/perl-5.38.3/bin/perl
t/00-load.t ....... ok
t/manifest.t ...... ok
t/pod-coverage.t .. ok
t/pod.t ........... ok
All tests successful.
Files=4, Tests=4,  0 wallclock secs ( 0.03 usr  0.01 sys +  0.42 cusr  0.05
csys =  0.51 CPU)
Result: PASS

Great! It’s time for another commit.

$ git commit -m "Add recommended test-stage dependencies" Makefile.PL
[main 819c069] Add recommended test-stage dependencies
 1 file changed, 12 insertions(+)

Testing times

Now that we’re sure our test suite is working properly (and we’ve got a clean working directory), we can start developing Map::Tube::Hannover by … adding another test! But where to start? Fortunately for us, the Map::Tube docs mention a basic data validation test as well as a basic functional validation test to ensure that the input data makes sense and that basic map functionality is available. That’s a nice starting point, so let’s do that.

Getting the basics right

Open your favourite editor and create a file called t/map-tube-hannover.t and fill it with this code:³

use strict;
use warnings;

use Test::More;

use Map::Tube::Hannover;
use Test::Map::Tube;

ok_map(Map::Tube::Hannover->new);
ok_map_functions(Map::Tube::Hannover->new);

done_testing();

Running the test suite (but avoiding the author tests for now), we find that things aren’t working.

$ make test
PERL_DL_NONLAZY=1 "/home/cochrane/perl5/perlbrew/perls/perl-5.38.3/bin/perl" "-MExtUtils::Command::MM" "-MTest::Harness" "-e" "undef *Test::Harness::Switches; test_harness(0, 'blib/lib', 'blib/arch')" t/*.t
t/00-load.t ............ 1/? # Testing Map::Tube::Hannover 0.01, Perl 5.038003, /home/cochrane/perl5/perlbrew/perls/perl-5.38.3/bin/perl
t/00-load.t ............ ok
t/manifest.t ........... skipped: Author tests not required for installation
t/map-tube-hannover.t .. Can't locate Test/Map/Tube.pm in @INC (you may need to install the Test::Map::Tube module) (@INC entries checked: /path/to/Map-Tube-Hannover/blib/lib /path/to/Map-Tube-Hannover/blib/arch /home/cochrane/perl5/perlbrew/perls/perl-5.38.3/lib/site_perl/5.38.3/x86_64-linux /home/cochrane/perl5/perlbrew/perls/perl-5.38.3/lib/site_perl/5.38.3 /home/cochrane/perl5/perlbrew/perls/perl-5.38.3/lib/5.38.3/x86_64-linux /home/cochrane/perl5/perlbrew/perls/perl-5.38.3/lib/5.38.3 .) at t/map-tube-hannover.t line 7.
BEGIN failed--compilation aborted at t/map-tube-hannover.t line 7.
t/map-tube-hannover.t .. Dubious, test returned 2 (wstat 512, 0x200)
No subtests run
t/pod-coverage.t ....... skipped: Author tests not required for installation
t/pod.t ................ skipped: Author tests not required for installation

Test Summary Report
-------------------
t/map-tube-hannover.t (Wstat: 512 (exited 2) Tests: 0 Failed: 0)
  Non-zero exit status: 2
  Parse errors: No plan found in TAP output
Files=5, Tests=1,  0 wallclock secs ( 0.04 usr  0.01 sys +  0.38 cusr  0.07 csys =  0.50 CPU)
Result: FAIL
Failed 1/5 test programs. 0/1 subtests failed.
make: *** [Makefile:851: test_dynamic] Error 255

This is completely ok: we expected that the tests wouldn’t pass. We’re using the tests to help guide us as we slowly build the Map::Tube::Hannover module.

The first error we have is:

Can't locate Test/Map/Tube.pm in @INC (you may need to install the Test::Map::Tube module)

As the message says, we can try to get further by installing Test::Map::Tube:

$ cpanm Test::Map::Tube

This will install almost 90 distributions in a freshly-built Perl, so you might want to go and have a walk or get an appropriate beverage while cpanm does its thing.

Becoming more objective

Welcome back! Now that the next set of dependencies has been installed, we make a mental note to add Test::Map::Tube to the list of required test dependencies in Makefile.PL. Then we try running the tests again:

$ make test
PERL_DL_NONLAZY=1 "/home/cochrane/perl5/perlbrew/perls/perl-5.38.3/bin/perl" "-MExtUtils::Command::MM" "-MTest::Harness" "-e" "undef *Test::Harness::Switches; test_harness(0, 'blib/lib', 'blib/arch')" t/*.t
t/00-load.t ............ 1/? # Testing Map::Tube::Hannover 0.01, Perl 5.038003, /home/cochrane/perl5/perlbrew/perls/perl-5.38.3/bin/perl
t/00-load.t ............ ok
t/manifest.t ........... skipped: Author tests not required for installation
t/map-tube-hannover.t .. Can't locate object method "new" via package "Map::Tube::Hannover" at t/map-tube-hannover.t line 9.
t/map-tube-hannover.t .. Dubious, test returned 255 (wstat 65280, 0xff00)
No subtests run
t/pod-coverage.t ....... skipped: Author tests not required for installation
t/pod.t ................ skipped: Author tests not required for installation

Test Summary Report
-------------------
t/map-tube-hannover.t (Wstat: 65280 (exited 255) Tests: 0 Failed: 0)
  Non-zero exit status: 255
  Parse errors: No plan found in TAP output
Files=5, Tests=1,  0 wallclock secs ( 0.05 usr  0.00 sys +  0.67 cusr  0.08 csys =  0.80 CPU)
Result: FAIL
Failed 1/5 test programs. 0/1 subtests failed.
make: *** [Makefile:857: test_dynamic] Error 255

This time we’ve got a problem in the module we’re creating. There’s something about a method new not being available. If you have a look at lib/Map/Tube/Hannover.pm, you’ll find that it’s filled with lots of docs, but there’s almost no code. How do we solve this? Well, the hint is in the error message above:

Can't locate object method "new"

If we see words like “object” and “method”, this means we’re dealing with object orientation.⁴ Thus, we need to turn our package into a class so that the failing test can call a new method and hence create an instance of the Map::Tube::Hannover class. There are several ways to create classes in Perl, so which one do we use? The hint is in the first sentence of Map::Tube’s DESCRIPTION:

The core module defined as Role (Moo) to process the map data.

In other words, we need to use Moo for object orientation. This should have been installed along with Test::Map::Tube, but just in case it wasn’t, you can install it with cpanm:

$ cpanm Moo

To use Moo to turn our package into a class, we only need to import it. Open lib/Map/Tube/Hannover.pm in your favourite editor and add the line

use Moo;

just after the use warnings; statement.

We don’t really need to run the full test suite each time we’re developing this code, so let’s use prove on only the t/map-tube-hannover.t test file instead:

$ prove -lr t/map-tube-hannover.t
t/map-tube-hannover.t ..     # Not a Map::Tube object

    #   Failed test 'An object'
    #   at /home/cochrane/perl5/perlbrew/perls/perl-5.38.3/lib/site_perl/5.38.3/Test/Map/Tube.pm line 196.
    # Looks like you failed 1 test of 1.
t/map-tube-hannover.t .. 1/?
#   Failed test 'ok_map_data'
#   at t/map-tube-hannover.t line 9.
Don't know how to access underlying map data at /home/cochrane/perl5/perlbrew/perls/perl-5.38.3/lib/5.38.3/Test/Builder.pm line 374.
# Tests were run but no plan was declared and done_testing() was not seen.
# Looks like your test exited with 255 just after 1.
t/map-tube-hannover.t .. Dubious, test returned 255 (wstat 65280, 0xff00)
Failed 1/1 subtests

Test Summary Report
-------------------
t/map-tube-hannover.t (Wstat: 65280 (exited 255) Tests: 1 Failed: 1)
  Failed test:  1
  Non-zero exit status: 255
  Parse errors: No plan found in TAP output
Files=1, Tests=1,  1 wallclock secs ( 0.04 usr  0.00 sys +  0.36 cusr  0.02 csys =  0.42 CPU)
Result: FAIL

The tests still aren’t passing, but that’s ok, we’re getting somewhere. The important part here is:

# Not a Map::Tube object

Ok, so how do we make this into a Map::Tube object? We use the with statement from Moo, which

Composes one or more Moo::Role (or Role::Tiny) roles into the current class.

Add the following code under the use Moo; statement we added earlier:

with 'Map::Tube';

Hasten JSON, bring a basin!

Running the test again will still fail, but this time we get a different error:⁵

$ prove -lr t/map-tube-hannover.t
t/map-tube-hannover.t .. ERROR: Can't apply Map::Tube role, missing 'xml' or 'json'. at /home/cochrane/perl5/perlbrew/perls/perl-5.38.3/lib/site_perl/5.38.3/Map/Tube.pm line 148.
t/map-tube-hannover.t .. Dubious, test returned 255 (wstat 65280, 0xff00)
No subtests run

Test Summary Report
-------------------
t/map-tube-hannover.t (Wstat: 65280 (exited 255) Tests: 0 Failed: 0)
  Non-zero exit status: 255
  Parse errors: No plan found in TAP output
Files=1, Tests=0,  1 wallclock secs ( 0.03 usr  0.01 sys +  0.41 cusr  0.04 csys =  0.49 CPU)
Result: FAIL

The central issue is here:

Can't apply Map::Tube role, missing 'xml' or 'json'.

What does that mean?

We’ve arrived at the core of the problem we’re trying to solve: we now need to create the input map file describing the railway network. This file can be either XML or JSON formatted, hence why the error message mentions that there is missing XML or JSON.

To load the map file, we need to define either a json() or xml() method, depending upon the format we’ve chosen. The map file defines the lines and stations associated with our railway network and their connections.

Loading lazily

One pattern is to place the map file in a share/ directory in the project’s base directory and to load it lazily by defining the respective json() or xml() method with the is option set to lazy, i.e.

has json => (is => 'lazy');

or

has xml => (is => 'lazy');

Because this is “lazy”, we need to define the builder method as well, e.g. for JSON-formatted files:

sub _build_json { dist_file('Map-Tube-Hannover', 'hannover-map.json') }

or for XML-formatted files:

sub _build_xml { dist_file('Map-Tube-Hannover', 'hannover-map.xml') }

It’s also possible to do this in one step, which is the approach that I prefer and which we’ll discuss now.

Direct by default

Another pattern for loading Map::Tube map files is to set the default option in the json() or xml() method, passing a sub which returns the file’s location. I found this to be a more direct approach and hence have used this pattern here.

As mentioned above, one usually places this file in a directory called share/ located in the project’s root directory. What’s not always clear is how we should name this file or how we connect it to the Map::Tube::<whatever> class. In the end, it doesn’t matter and one can simply follow the pattern used in e.g. Map::Tube::London, i.e. call the file something like <city-name>-map.json.

How to connect this file to the Map::Tube::<whatever> class is described in the Map::Tube::Cookbook WORK WITH A MAP documentation. The trick is to create a getter called json()⁶ which returns the name of the input file. If you use the share/ directory pattern, you can use the File::Share module to get the location within the dist easily.

Let’s implement this now. Create the share/ directory and then create an empty input map file by touching it:

$ mkdir share
$ touch share/hannover-map.json

Now we import the dist_file function from the File::Share module by adding the following code after the use Moo; statement:⁷

use File::Share qw(dist_file);

Note that to be able to use this module, we’ll have to install it:

$ cpanm File::Share

We’ll also have to make another mental note to add this as a prerequisite in our Makefile.PL. We’ll get around to that later.

Further down the module, remove the stub function1 and function2 definitions that module-starter created for us and replace them with the recommended json getter:

has json => (
    is => 'ro',
    default => sub {
        return dist_file('Map-Tube-Hannover', 'hannover-map.json')
    }
);

Slowly bringing data into form

Running the test file gives a new error! Yay!

$ prove -lr t/map-tube-hannover.t
t/map-tube-hannover.t .. Map::Tube::_init_map(): ERROR: Malformed Map Data (/path/to/Map-Tube-Hannover/share/hannover-map.json): malformed JSON string, neither array, object, number, string or atom, at character offset 1 (before "(end of string)")
 (status: 126) file /home/cochrane/perl5/perlbrew/perls/perl-5.38.3/lib/site_perl/5.38.3/Map/Tube.pm on line 151
t/map-tube-hannover.t .. Dubious, test returned 255 (wstat 65280, 0xff00)
No subtests run

Test Summary Report
-------------------
t/map-tube-hannover.t (Wstat: 65280 (exited 255) Tests: 0 Failed: 0)
  Non-zero exit status: 255
  Parse errors: No plan found in TAP output
Files=1, Tests=0,  1 wallclock secs ( 0.03 usr  0.00 sys +  0.44 cusr  0.02 csys =  0.49 CPU)
Result: FAIL

We seem to have malformed map data. That’s to be expected because the input file is empty.

Since it’s JSON, it’ll need some curly braces in it at the very least. Let’s add some to it and see what happens:

$ echo "{}" > share/hannover-map.json
$ prove -lr t/map-tube-hannover.t
t/map-tube-hannover.t .. Map::Tube::_validate_map_structure(): ERROR: Invalid line structure in map data. (status: 128) file /home/cochrane/perl5/perlbrew/perls/perl-5.38.3/lib/site_perl/5.38.3/Map/Tube.pm on line 151
t/map-tube-hannover.t .. Dubious, test returned 255 (wstat 65280, 0xff00)
No subtests run

Test Summary Report
-------------------
t/map-tube-hannover.t (Wstat: 65280 (exited 255) Tests: 0 Failed: 0)
  Non-zero exit status: 255
  Parse errors: No plan found in TAP output
Files=1, Tests=0,  0 wallclock secs ( 0.03 usr  0.00 sys +  0.46 cusr  0.01 csys =  0.50 CPU)
Result: FAIL

Another different error! Nice. We don’t want to be crawling forward like this all day, though. We need some real data in this file and with the correct structure. Fortunately, both the Map::Tube JSON docs and the Map::Tube::Cookbook formal requirements for maps describe this for us nicely.

Our basic structure will need a name and a lines object containing a line array of all lines in our railway network. We’ll also need a stations object containing a station array of all stations in the network and how they are connected to the lines. Phew! That was a mouthful! How does that look in practice? Let’s implement it!

Open the map file (share/hannover-map.json) in your favourite editor and enter the following data structure:

{
    "name"  : "Hannover",
    "lines" : {
        "line" : [
            {
                "id" : "L1",
                "name" : "Linie 1"
            }
        ]
    },
    "stations" : {
        "station" : [
            {
                "id" : "H1",
                "name" : "Hauptbahnhof",
                "line" : "L1",
                "link" : "H1"
            }
        ]
    }
}

This creates a map called Hannover, with one line (called Linie 1) and one station on that line (Hauptbahnhof). The link attribute must be set, hence we’ve set it to point to the station itself. I expect this to give an error because links should be between stations, not to themselves. However, this is the smallest basic example that I could think of. The station’s ID, H1, that I’ve used here doesn’t represent Hauptbahnhof 1 (as one could mistake it to mean) but means Hannover 1 because this will be the first station in the Hannover network.

Let’s see what the tests now tell us.

$ prove -lr t/map-tube-hannover.t
t/map-tube-hannover.t ..     # Line id L1 defined but serves only one station

    #   Failed test 'Hannover'
    #   at /home/cochrane/perl5/perlbrew/perls/perl-5.38.3/lib/site_perl/5.38.3/Test/Map/Tube.pm line 196.
    # Station ID H1 links to itself

    #   Failed test 'Hannover'
    #   at /home/cochrane/perl5/perlbrew/perls/perl-5.38.3/lib/site_perl/5.38.3/Test/Map/Tube.pm line 196.
    # Looks like you failed 2 tests of 14.
t/map-tube-hannover.t .. 1/?
#   Failed test 'ok_map_data'
#   at t/map-tube-hannover.t line 9.
Map::Tube::get_shortest_route(): ERROR: Missing Station Name. (status: 100) file /home/cochrane/perl5/perlbrew/perls/perl-5.38.3/lib/site_perl/5.38.3/Map/Tube.pm on line 193

#   Failed test at t/map-tube-hannover.t line 10.
#          got: 0
#     expected: 1
# Looks like you failed 2 tests of 2.
t/map-tube-hannover.t .. Dubious, test returned 2 (wstat 512, 0x200)
Failed 2/2 subtests

Test Summary Report
-------------------
t/map-tube-hannover.t (Wstat: 512 (exited 2) Tests: 2 Failed: 2)
  Failed tests:  1-2
  Non-zero exit status: 2
Files=1, Tests=2,  1 wallclock secs ( 0.03 usr  0.01 sys +  0.46 cusr  0.07 csys =  0.57 CPU)
Result: FAIL

As I guessed, this still gives us an error. Even so, we’re getting somewhere. Focusing on the first error:

Line id L1 defined but serves only one station

we see we’ve been told that the line defined by the ID L1 only serves one station (true, it does, but that’s something we’ll change soon). We’ve also been told that the station referred to by the ID H1 links to itself,

Station ID H1 links to itself

which is what we already thought was dodgy. It’s nice that the basic validation test checks such things!

Ok, let’s add another station to see what happens. In our share/hannover-map.json map file, we extend the network to include the station Langenhagen⁸ and we change the links so that the stations connect to one another. The map file now looks like this:

{
    "name"  : "Hannover",
    "lines" : {
        "line" : [
            {
                "id" : "L1",
                "name" : "Linie 1"
            }
        ]
    },
    "stations" : {
        "station" : [
            {
                "id" : "H1",
                "name" : "Hauptbahnhof",
                "line" : "L1",
                "link" : "H2"
            },
            {
                "id" : "H2",
                "name" : "Langenhagen",
                "line" : "L1",
                "link" : "H1"
            }
        ]
    }
}

A note for anyone familiar with Hannover and its tram system: yes, the stations Hauptbahnhof and Langenhagen are on the same line (Linie 1), however, they are not directly linked to one another. Langenhagen is the final station along that line heading northwards; Hauptbahnhof is effectively the middle of the entire network. We’ll flesh out a more full version of the network as we go along.

Running the tests this time gives:

$ prove -lr t/map-tube-hannover.t
t/map-tube-hannover.t .. ok
All tests successful.
Files=1, Tests=1,  1 wallclock secs ( 0.03 usr  0.01 sys +  0.50 cusr  0.02 csys =  0.56 CPU)
Result: PASS

Success!! Go and have a bit of a dance! You’ve created your first functional Map::Tube map! :tada:

Now things get interesting. We can start adding new lines and stations and start linking them together. Then we can see how to use Map::Tube::Hannover to find routes between stations and even show a graph of the railway network.

Let’s not get too far ahead of ourselves though. Let’s stay calm and focused and take things one step at a time.

Staying committed

But first, we’ve got some unfinished business. We’ve added some modules as dependencies, so we need to ensure that our Makefile.PL includes them and commit that change. We also need to add our first iteration of the map file to the Git repository as well as the code which integrates it into the Map::Tube framework and its test. To work!

If you remember correctly, the first module we added was Test::Map::Tube. We need to add this to the TEST_REQUIRES key in the %WriteMakefileArgs hash. Open Makefile.PL and extend TEST_REQUIRES to look like this:

    TEST_REQUIRES => {
        'Test::More'      => '0',
        'Test::Map::Tube' => '4.03',
    },

Note that the Test::More requirement was already present. We’ve specified the version number for Test::Map::Tube to be '4.03' because this is the version I used when writing this HOWTO. If you’re following along at home, I recommend checking what the current version is and using that number instead.

The remaining dependencies are “prerequisite Perl modules”, hence we need to set the PREREQ_PM hash key in %WriteMakefileArgs. Change the initial value from

    PREREQ_PM => {
        #'ABC'              => '1.6',
        #'Foo::Bar::Module' => '5.0401',
    },

to

    PREREQ_PM => {
        'File::Share' => '0',
        'Map::Tube'   => '4.03',
        'Moo'         => '0',
    },

where I’ve again chosen to select the specific Map::Tube version being used for this HOWTO. I’ve set the other modules to use version '0' because any version should be sufficient for our purposes. Technically, we don’t need to add the Map::Tube dependency because it’s pulled in by Test::Map::Tube. Still, it’s a good idea to add this dependency explicitly as this ends up in the project metadata, informing your users and any tools such as MetaCPAN, CPANTS and CPAN testers what is required to build and run the module. Also, I’ve listed the prerequisites alphabetically so that it’s easier to find and update this list in the future.

Looking at the diff for these changes, you should see something like this:

$ git diff Makefile.PL
diff --git a/Makefile.PL b/Makefile.PL
index b889368..22afd9a 100644
--- a/Makefile.PL
+++ b/Makefile.PL
@@ -14,11 +14,13 @@ my %WriteMakefileArgs = (
         'ExtUtils::MakeMaker' => '0',
     },
     TEST_REQUIRES => {
-        'Test::More' => '0',
+        'Test::More'      => '0',
+        'Test::Map::Tube' => '4.03',
     },
     PREREQ_PM => {
-        #'ABC'              => '1.6',
-        #'Foo::Bar::Module' => '5.0401',
+        'File::Share' => '0',
+        'Map::Tube'   => '4.03',
+        'Moo'         => '0',
     },
     dist  => { COMPRESS => 'gzip -9f', SUFFIX => 'gz', },
     clean => { FILES => 'Map-Tube-Hannover-*' },

Let’s commit that change:

$ git commit -m "Add base and test deps for first working example" Makefile.PL
[main e4e6f93] Add base and test deps for first working example
 1 file changed, 5 insertions(+), 3 deletions(-)

The remaining changes are all interrelated. The change to import the relevant third-party modules into our main module, the addition of the input map file, the code which links this to Map::Tube, as well as the test file, are all sufficiently related that it makes sense to bundle all these changes into a single commit.⁹

$ git add t/map-tube-hannover.t share/hannover-map.json lib/Map/Tube/Hannover.pm
$ git commit -m "
> Add initial minimal working map input file
>
> This is a first-cut implementation of the railway network for Hannover.
> Note that this is *not* intended to reflect the real-world situation just yet.
> I've chosen to use station names here which make the initial validation tests
> pass and which vaguely reflect the nature of the network itself.  Both
> stations do exist on Linie 1, however are separated by several other stations
> in reality.  Since the validation tests pass, we know that things are wired
> up to the Map::Tube framework properly."
[main fb94aab] Add initial minimal working map input file
 Date: Sun Mar 30 20:02:06 2025 +0200
 4 files changed, 55 insertions(+), 14 deletions(-)
 create mode 100644 share/hannover-map.json
 create mode 100644 t/map-tube-hannover.t
 create mode 100644 t/map-tube-hannover.t

Note that you should not enter the greater-than signs at the beginning of each line of the commit message entered above. These are the line continuation markers shown by the shell. In other words, if you’re following along and want to enter the commit message shown above, you will need to remove the > (including the space) from the text.

Wrapping up

That should do for today! We got a lot done! We created a new module from scratch and then used test-driven development to create the fundamental structure for Map::Tube::Hannover while also creating the most basic Map::Tube map file we could.

In the second post in the series, we’ll carefully extend the network to create a full line and then create a graph of the stations. Until then!

Originally posted on https://peateasea.de.

Image credits: Wikimedia Commons, Noto-Emoji project, Wikimedia Commons

Thumbnail credits: Swiss Cottage Underground Station (Jubilee Line) by Hugh Llewelyn