Test/Map/Tube.pm

filter: Statementstmt 90.0% 18 / 20 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub 100% 7 / 7 Podpod n/a totaltotal 92.5% 25 / 27 CC 1 SCAR 0.4
CC
1
Cov
90%
BEGIN
1.3
BEGIN
1.0
BEGIN
1.0
CRAP 1.0
« Map/Tube/Node.pm ↑ Summary Map/Tube.pm »
1 package Test::Map::Tube;
2  
3 25 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 25 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
5 25 ▶use version;
Subroutine BEGIN: called CC=1 SCAR=0.0
6  
7 our $VERSION = qv('v5.2.0');
8 our $AUTHORITY = 'cpan:MANWAR';
9  
10 =head1 NAME
11  
12 Test::Map::Tube - Module for testing Map::Tube data and features.
13  
14 =head1 VERSION
15  
16 Version v5.2.0
17  
18 =head1 DESCRIPTION
19  
20 The module may be used for two complementary purposes: during development of a
21 tube map, it checks for map authors whether the data structures are consistent
22 and follow the rules for Map::Tube data. The other use case is during installation
23 of a map by the user, where it ensures a functioning installation.
24  
25 =head1 SYNOPSIS
26  
27 =head2 Validate ONLY map data.
28  
29 use strict;
30 use warnings;
31 use Test::More;
32  
33 my $min_ver = 3.93;
34 eval "use Test::Map::Tube $min_ver";
35 plan skip_all => "Test::Map::Tube $min_ver required" if $@;
36  
37 use Map::Tube::London;
38 ok_map_data(Map::Tube::London->new);
39  
40 =head2 Validate ONLY map functions.
41  
42 use strict;
43 use warnings;
44 use Test::More;
45  
46 my $min_ver = 3.93;
47 eval "use Test::Map::Tube $min_ver";
48 plan skip_all => "Test::Map::Tube $min_ver required" if $@;
49 plan skip_all => 'These tests are for authors only!'
50 unless ( $ENV{AUTHOR_TESTING} || $ENV{RELEASE_TESTING} );
51  
52 use Map::Tube::London; # or any other Map::Tube map
53 ok_map_functions(Map::Tube::London->new);
54  
55 =head2 Validate BOTH map data and functions.
56  
57 use strict;
58 use warnings;
59 use Test::More;
60  
61 my $min_ver = 3.93;
62 eval "use Test::Map::Tube $min_ver tests => 2";
63 plan skip_all => "Test::Map::Tube $min_ver required" if $@;
64  
65 use Map::Tube::London; # or any other Map::Tube map
66 my $map = Map::Tube::London->new;
67 ok_map_data($map);
68 ok_map_functions($map);
69  
70 =head2 Validate map data, functions and routes.
71  
72 use strict;
73 use warnings;
74 use Test::More;
75  
76 my $min_ver = 3.75;
77 eval "use Test::Map::Tube $min_ver tests => 3";
78 plan skip_all => "Test::Map::Tube $min_ver required" if $@;
79  
80 use Map::Tube::London; # or any other Map::Tube map
81 my $map = Map::Tube::London->new;
82 ok_map_data($map);
83 ok_map_functions($map);
84  
85 my @routes = (
86 "Route 1|Tower Gateway|Aldgate|Tower Gateway, Tower Hill, Aldgate",
87 "Route 2|Liverpool Street|Monument|Liverpool Street, Bank, Monument",
88 );
89 ok_map_routes($map, \@routes);
90  
91  
92 For testing at install time, there are only two tests: C<ok_map_functions( )> and
93 C<ok_map_routes( )>. C<ok_map_functions( )> internally runs several different subtests.
94  
95 For testing during development, there are a number of separate tests, each checking for a
96 particular issue. Usually, though, a portmanteau test, C<ok_map_data( )>, is employed which will
97 run almost all the individual tests in one go. Details are provided below.
98  
99 =cut
100  
101 # ###### All further documentation at the end of this file ######
102  
103 25 ▶use 5.012;
Subroutine BEGIN: called CC=1 SCAR=0.0
104 25 ▶use Test::More;
Subroutine BEGIN: called CC=1 SCAR=0.0
105 25 ▶use Data::Compare;
Subroutine BEGIN: called CC=1 SCAR=0.0
106 0 ▶use Map::Tube::Route;
Subroutine BEGIN: called CC=1 SCAR=2.6
107  
108 my %testnames = (
109 ok_map_data => -1,
110 ok_map => -1,
111 not_ok_map_data => -1,
112 not_ok_map => -1,
113 ok_map_routes => -1,
114 ok_map_functions => -1, # = -1 => never use this from within ok_map_data
115 ok_map_loadable => 2, # > 1 => always use this first from within ok_map_data
116 ok_map_connected => 1, # = 1 => by default use this from within ok_map_data
117 ok_line_definitions => 1,
118 ok_line_names_unique => 1,
119 ok_line_ids_unique => 1,
120 ok_lines_used => 1,
121 ok_lines_indexed => 1,
122 ok_lines_run_through => 1,
123 ok_links_bidirectional => 0,
124 ok_station_ids => 1,
125 ok_station_names_different => 0, # = 0 => by default don't use this from within ok_map_data
126 ok_station_names_complete => 0,
127 ok_stations_linked => 1,
128 ok_stations_self_linked => 1,
129 ok_stations_multilinked => 1,
130 ok_stations_multilined => 1,
131 ok_stations_linked_share_lines => 1,
132 );
133  
134 sub import {
135 my ($self, %plan) = @_;
136 my $caller = caller;
137  
138 for my $function (keys %testnames) {
139 no strict 'refs';
140 *{$caller . "::" . $function} = \&$function;
141 }
142  
143 Test::More->builder( )->exported_to($caller);
144 Test::More->builder( )->plan(%plan);
145  
146 return;
147 }
148  
149  
150 sub ok_map_data($;$$) {
151 my( $map, $argref, $message ) = @_;
152 my $tb = Test::More->builder( );
153 if ( defined($argref) && ( ref($argref) eq '' ) ) {
154 $message //= $argref;
155 undef($argref);
156 }
157 my %args;
158 $args{name} = $message if defined $message;
159 $args{$_} = $argref->{$_} for keys %{ $argref };
160 my $want_array = wantarray;
161  
162 # Default set of tests to use (unless we're told not to):
163 my %tests2use;
164 %tests2use = map { $_ => defined($args{name}) ? { name => $args{name} } : { } }
165 grep { $testnames{$_} > 0 }
166 keys %testnames unless $args{only};
167  
168 # Check which tests are to exclude, to include or to configure:
169 for my $testname( grep { exists( $testnames{$_} ) } keys %args ) {
170 if ( $args{$testname} && ( $testnames{$testname} >= 0 ) ) {
171 # Include this test
172 $tests2use{$testname} //= { };
173 $tests2use{$testname}{name} = $args{name} if defined( $args{name} );
174 if ( ref( $args{$testname} ) eq 'HASH' ) {
175 # ... and pass these arguments:
176 $tests2use{$testname}{$_} = $args{$testname}->{$_} for keys %{ $args{$testname} };
177 }
178 } else {
179 # Do not include this test:
180 delete( $tests2use{$testname} ) unless ( $testnames{$testname} > 1 );
181 }
182 }
183  
184 # Now call them all:
185 my $all_ok = 1;
186 my @all_results;
187 my $test_level = $tb->level( );
188 $tb->level( $test_level+1 );
189  
190 # All the individual tests will be counted as just one top-level test:
191 subtest 'ok_map_data' => sub {
192 for my $testname( sort { ( $testnames{$b} <=> $testnames{$a} ) || ( $a cmp $b ) } keys %tests2use ) {
193 no strict 'refs';
194 my( $ok, @results );
195 if ($want_array) {
196 ( $ok, @results ) = (\&{ $testname })->( $map, $tests2use{$testname} );
197 push( @all_results, @results );
198 } else {
199 $ok = (\&{ $testname })->( $map, $tests2use{$testname} );
200 }
201 $all_ok &&= $ok;
202 }
203 };
204  
205 $tb->level( $test_level );
206 return $want_array ? ( $all_ok, @all_results ) : $all_ok;
207 }
208  
209  
210 sub ok_map($;$$) {
211 # Deprecated alias of ok_map_data( )
212 my( $map, $argref, $message ) = @_;
213 my $tb = Test::More->builder( );
214  
215 my $test_level = $tb->level( );
216 $tb->level( $test_level+1 );
217  
218 if (wantarray) {
219 my( $ok, @messages ) = ok_map_data( $map, $argref, $message );
220 $tb->level( $test_level );
221 return ( $ok, @messages );
222 } else {
223 my $ok = ok_map_data( $map, $argref, $message );
224 $tb->level( $test_level );
225 return $ok;
226 }
227 }
228  
229  
230 sub not_ok_map_data($;$$) {
231 my( $map, $argref, $message ) = @_;
232 my $tb = Test::More->builder( );
233  
234 my $test_level = $tb->level( );
235 $tb->level( $test_level+1 );
236  
237 my( $ok, @messages ) = ok_map_data( $map, $argref, $message );
238 if (wantarray) {
239 if ($ok) {
240 my $name = ( defined($argref) && ( ref($argref) eq 'HASH' ) && exists( $argref->{name} ) )
241 ? $argref->{name}
242 : ( $map->name( ) // 'A Map::Tube' );
243 $tb->level( $test_level );
244 return ( !$ok, 'No errors found in map data for ' . $name );
245 } else {
246 $tb->level( $test_level );
247 return (!$ok);
248 }
249 } else {
250 $tb->level( $test_level );
251 return $ok;
252 }
253 }
254  
255  
256 sub not_ok_map($;$$) {
257 # Deprecated alias of not_ok_map_data( )
258 my( $map, $argref, $message ) = @_;
259 my $tb = Test::More->builder( );
260  
261 my $test_level = $tb->level( );
262 $tb->level( $test_level+1 );
263  
264 my( $ok, @messages ) = not_ok_map_data( $map, $argref, $message );
265 if (wantarray) {
266 $tb->level( $test_level );
267 return ( $ok, @messages );
268 } else {
269 $tb->level( $test_level );
270 return $ok;
271 }
272 }
273  
274  
275 sub ok_map_functions ($;$) {
276 my ($object, $message) = @_;
277 Test::More->builder( )->is_num( _ok_map_functions($object), 1, $message );
278 return;
279 }
280  
281  
282 sub ok_map_routes($$;$) {
283 my ( $object, $routes, $message ) = @_;
284 my @errors = _ok_map_routes( $object, $routes );
285 if (!@errors) {
286 return Test::More->builder( )->is_num( 1, 1, $message );
287 }
288 for (@errors) {
289 my ( $g, $e, $d ) = @$_;
290 my ( $gs, $es ) = map join( "\n", @{$_->nodes} ), $g, $e;
291 Test::More->builder( )->is_eq( $gs, $es, $message||$d )
292 }
293 return;
294 }
295  
296  
297 sub ok_map_loadable($;$) {
298 # Check whether the map object is defined, looks like a Map::Tube object
299 # and contains valid data as per Map::Tube built-in base line checks.
300 # It does not perform any deep data validity checks beyond.
301 #
302 # Arguments:
303 # $map : an object, presumably a Map::Tube object
304 # $argref : an optional hash ref with further arguments for the test.
305 # Only the entry for name will be used as a name to identify the map to the user.
306 #
307 # Return:
308 # in scalar context: a boolean indicating success (truey) or failure (falsey).
309 # Any diagnostics will have been output at the time of return.
310 # in array context: a list containing a boolean (as above), followed by all diagnostic
311 # messages (if any).
312 # It is the responsibility of the caller to display these messages
313 # to the user.
314 #
315 my ( $object, $argref ) = @_;
316 my $tb = Test::More->builder( );
317 my $name = ( defined($argref) && ( ref($argref) eq 'HASH' ) && exists( $argref->{name} ) )
318 ? $argref->{name}
319 : 'An object';
320 my $max_msg = ( defined($argref) && ( ref($argref) eq 'HASH' ) && exists( $argref->{max_messages} ) )
321 ? $argref->{max_messages}
322 : 0;
323 my $ok = 1;
324 my @results;
325  
326 if ( !defined($object) ) {
327 ( $ok, @results ) = _emit_diagnostics( $name, wantarray, $ok, 'Object undefined', \@results );
328 } elsif ( !$object->does('Map::Tube') ) {
329 ( $ok, @results ) = _emit_diagnostics( $name, wantarray, $ok, 'Not a Map::Tube object', \@results, $max_msg );
330 } else {
331 # Don't need to test the following, because that is already tested on construction of the
332 # Map::Tube object, so if this is amiss, we'll never even get here.
333 # eval { $object->get_map_data; };
334 # return 'No map data found' if $@;
335 }
336  
337 $ok = $tb->ok( 1, $name ) if $ok;
338  
339 return wantarray ? ( $ok, @results ) : $ok;
340 }
341  
342  
343 sub ok_line_names_unique($;$) {
344 # Line names must be unique.
345 # Station names must also be unique, but since newer versions of Map::Tube already test this
346 # on init, we don't repeat this.
347 # This test presupposes that the map is loadable as per ok_map_loadable( ).
348 #
349 # Arguments:
350 # $map : a loadable Map::Tube object
351 # $argref : an optional hash ref with further arguments for the test.
352 # Only the entry for name will be used as a name to identify the map to the user.
353 #
354 # Return:
355 # in scalar context: a boolean indicating success (truey) or failure (falsey).
356 # Any diagnostics will have been output at the time of return.
357 # in array context: a list containing a boolean (as above), followed by all diagnostic
358 # messages (if any).
359 # It is the responsibility of the caller to display these messages
360 # to the user.
361 my ( $map, $argref ) = @_;
362 my $tb = Test::More->builder( );
363 $map = _prepare_raw_map($map) unless exists $map->{_rawinfo};
364 my $name = ( defined($argref) && ( ref($argref) eq 'HASH' ) && exists( $argref->{name} ) )
365 ? $argref->{name}
366 : ( $map->name( ) // 'A Map::Tube' );
367 my $max_msg = ( defined($argref) && ( ref($argref) eq 'HASH' ) && exists( $argref->{max_messages} ) )
368 ? $argref->{max_messages}
369 : 0;
370 my $rawinfo = $map->{_rawinfo};
371 my $ok = 1;
372 my @results;
373  
374 # Check that no line name comes up more than once (taking into account exact spelling):
375 my @dup_names = sort grep { scalar( @{ $rawinfo->{line_names}{$_} } ) > 1 } keys %{ $rawinfo->{line_names} };
376 ( $ok, @results ) = _emit_diagnostics( $name, wantarray, $ok,
377 "Line name $_ defined more than once (ids " .
378 join( ', ', @{ $rawinfo->{line_names}{$_} } ) . ')',
379 \@results, $max_msg
380 ) for @dup_names;
381  
382 # Check that no line name comes up more than once after upper-casing:
383 @dup_names = ( );
384 for my $uc_name ( sort keys %{ $rawinfo->{line_names_uc} } ) {
385 my @names = keys %{ $rawinfo->{line_names_uc}{$uc_name} };
386 push( @dup_names, $uc_name ) if ( scalar(@names) > 1 );
387 }
388 ( $ok, @results ) = _emit_diagnostics( $name, wantarray, $ok,
389 "Line name $_ defined more than once with different spelling: " .
390 join( ', ', sort keys( %{ $rawinfo->{line_names_uc}{$_} } ) ),
391 \@results, $max_msg
392 ) for @dup_names;
393  
394 $ok = $tb->ok( 1, $name ) if $ok;
395  
396 return wantarray ? ( $ok, @results ) : $ok;
397 }
398  
399  
400 sub ok_line_ids_unique($;$) {
401 # Line ids must be unique.
402 # This test presupposes that the map is loadable as per ok_map_loadable( ).
403 #
404 # Arguments:
405 # $map : a loadable Map::Tube object
406 # $argref : an optional hash ref with further arguments for the test.
407 # Only the entry for name will be used as a name to identify the map to the user.
408 #
409 # Return:
410 # in scalar context: a boolean indicating success (truey) or failure (falsey).
411 # Any diagnostics will have been output at the time of return.
412 # in array context: a list containing a boolean (as above), followed by all diagnostic
413 # messages (if any).
414 # It is the responsibility of the caller to display these messages
415 # to the user.
416 my ( $map, $argref ) = @_;
417 my $tb = Test::More->builder( );
418 $map = _prepare_raw_map($map) unless exists $map->{_rawinfo};
419 my $name = ( defined($argref) && ( ref($argref) eq 'HASH' ) && exists( $argref->{name} ) )
420 ? $argref->{name}
421 : ( $map->name( ) // 'A Map::Tube' );
422 my $max_msg = ( defined($argref) && ( ref($argref) eq 'HASH' ) && exists( $argref->{max_messages} ) )
423 ? $argref->{max_messages}
424 : 0;
425 my $rawinfo = $map->{_rawinfo};
426 my $ok = 1;
427 my @results;
428  
429 my @dup_ids = sort grep { scalar( @{ $rawinfo->{line_ids_defined}->{$_} } ) > 1 } keys %{ $rawinfo->{line_ids_defined} };
430 for (@dup_ids) {
431 my $msg;
432 my $n = scalar( @{ $rawinfo->{line_ids_defined}->{$_} } );
433 if ( ( $n == 2 ) &&
434 ( uc( $rawinfo->{line_ids_defined}->{$_}->[0] ) eq uc( $rawinfo->{line_ids_defined}->{$_}->[1] ) ) &&
435 ( $rawinfo->{line_ids_defined}->{$_}->[0] ne $rawinfo->{line_ids_defined}->{$_}->[1] ) ) {
436 $msg = "Line id $_ defined more than once in different writing (case)";
437 } else {
438 $msg = "Line id $_ defined $n times";
439 }
440 ( $ok, @results ) = _emit_diagnostics( $name, wantarray, $ok, $msg, \@results, $max_msg );
441 }
442  
443 $ok = $tb->ok( 1, $name ) if $ok;
444  
445 return wantarray ? ( $ok, @results ) : $ok;
446 }
447  
448  
449 sub ok_station_names_different($;$) {
450 # Station ids must be unique (case-insensitive), but since newer versions of Map::Tube
451 # already test this on init, we don't repeat this. The same goes for station names.
452 # Instead, we check here whether no two station names look "similar enough" to assume
453 # one might be a typo for the other.
454 # This is in many ways a fallible test and cannot be applied indiscriminately.
455 # Hence, it can be tweaked in two ways:
456 # a) by setting the maximum Levenshtein distance for two names to be considered equal. Set
457 # to 0 in order to test only for complete equality.
458 # b) by setting a threshold for the total number of similar entries below which no problem
459 # will be reported. Default is 0 (so all issues will be reported). Set it, e.g., to 5
460 # if you know that your map contains 5 legitimate pairs of similar entries.
461 #
462 # Arguments:
463 # $map : a loadable Map::Tube object
464 # $argref : an optional hash ref with further arguments for the test.
465 # The entry for name will be used as a name to identify the map to the user.
466 # dist_limit sets the maximum distance as outlined above. Default: 2.
467 # max_allowed sets the threshold on the number of issues as outlined above.
468 # Default: 0.
469 #
470 # Return:
471 # in scalar context: a boolean indicating success (truey) or failure (falsey).
472 # Any diagnostics will have been output at the time of return.
473 # in array context: a list containing a boolean (as above), followed by all diagnostic
474 # messages (if any).
475 # It is the responsibility of the caller to display these messages
476 # to the user.
477 #
478 my ( $map, $argref ) = @_;
479 my $tb = Test::More->builder( );
480 $map = _prepare_raw_map($map) unless exists $map->{_rawinfo};
481 my $name = ( defined($argref) && ( ref($argref) eq 'HASH' ) && exists( $argref->{name} ) )
482 ? $argref->{name}
483 : ( $map->name( ) // 'A Map::Tube' );
484 my $max_msg = ( defined($argref) && ( ref($argref) eq 'HASH' ) && exists( $argref->{max_messages} ) )
485 ? $argref->{max_messages}
486 : 0;
487 my $dist_limit = ( defined($argref) && ( ref($argref) eq 'HASH' ) && exists( $argref->{dist_limit} ) )
488 ? $argref->{dist_limit}
489 : 2;
490 my $max_allowed = ( defined($argref) && ( ref($argref) eq 'HASH' ) && exists( $argref->{max_allowed} ) )
491 ? $argref->{max_allowed}
492 : 0;
493 my $rawinfo = $map->{_rawinfo};
494 my $ok = 1;
495 my @results;
496  
497 eval 'use Text::Levenshtein::XS qw(distance)';
498 return _emit_diagnostics( $name, wantarray, $ok,
499 'Module Text::Levenshtein::XS required for name similarity testing',
500 \@results, $max_msg ) if $@;
501  
502 my @similar_names;
503 my @station_names = sort keys %{ $rawinfo->{station_names} };
504 while (@station_names) {
505 my $station = shift(@station_names);
506 push( @similar_names, map { ":$station:$_:" } grep { ( $station ne $_ ) &&
507 ( distance( $station, $_ ) <= $dist_limit )
508 } @station_names );
509 }
510  
511 if ( scalar(@similar_names) > $max_allowed ) {
512 ( $ok, @results ) = _emit_diagnostics( $name, wantarray, $ok,
513 scalar(@similar_names) .
514 ' similar name pair(s) found at or below distance ' .
515 $dist_limit,
516 \@results, $max_msg
517 );
518 ( $ok, @results ) = _emit_diagnostics( $name, wantarray, $ok,
519 "Similar names maybe due to typo? $_",
520 \@results, $max_msg
521 ) for @similar_names;
522 }
523  
524 $ok = $tb->ok( 1, $name ) if $ok;
525  
526 return wantarray ? ( $ok, @results ) : $ok;
527 }
528  
529  
530 sub ok_station_names_complete($;$) {
531 # Station ids must be unique, but since newer versions of Map::Tube already test this on
532 # init, we don't repeat this. Instead, we check here that no station name is a proper prefix
533 # of another one; otherwise, one might be an accidentally abbreviated name.
534 # This is in many ways a fallible test and cannot be applied indiscriminately.
535 # Hence, it can be tweaked by setting a threshold for the total number of similar entries
536 # below which no problem will be reported. Default is 0 (so all issues will be reported).
537 # Set it, e.g., to 5 if you know that your map contains 5 legitimate pairs of entries where
538 # one looks like an abbreviated version of the other, but isn't.
539 #
540 # Arguments:
541 # $map : a loadable Map::Tube object
542 # $argref : an optional hash ref with further arguments for the test.
543 # The entry for name will be used as a name to identify the map to the user.
544 # max_allowed sets the threshold on the number of issues as outlined above.
545 # Default: 0.
546 #
547 # Return:
548 # in scalar context: a boolean indicating success (truey) or failure (falsey).
549 # Any diagnostics will have been output at the time of return.
550 # in array context: a list containing a boolean (as above), followed by all diagnostic
551 # messages (if any).
552 # It is the responsibility of the caller to display these messages
553 # to the user.
554 #
555 my ( $map, $argref ) = @_;
556 my $tb = Test::More->builder( );
557 $map = _prepare_raw_map($map) unless exists $map->{_rawinfo};
558 my $name = ( defined($argref) && ( ref($argref) eq 'HASH' ) && exists( $argref->{name} ) )
559 ? $argref->{name}
560 : ( $map->name( ) // 'A Map::Tube' );
561 my $max_msg = ( defined($argref) && ( ref($argref) eq 'HASH' ) && exists( $argref->{max_messages} ) )
562 ? $argref->{max_messages}
563 : 0;
564 my $max_allowed = ( defined($argref) && ( ref($argref) eq 'HASH' ) && exists( $argref->{max_allowed} ) )
565 ? $argref->{max_allowed}
566 : 0;
567 my $rawinfo = $map->{_rawinfo};
568 my $ok = 1;
569 my @results;
570  
571 my @incomplete_names;
572 my @station_names = sort keys %{ $rawinfo->{station_names} };
573 while (@station_names) {
574 my $station = shift(@station_names);
575 push( @incomplete_names, map { ":$station:$_:" } grep { ( $station ne $_ ) &&
576 ( $station eq substr( $_, 0, length($station) ) )
577 } @station_names );
578 }
579  
580 if ( scalar(@incomplete_names) > $max_allowed ) {
581 ( $ok, @results ) = _emit_diagnostics( $name, wantarray, $ok,
582 scalar(@incomplete_names) . ' possibly partial name pair(s) found', \@results,
583 $max_msg
584 );
585 ( $ok, @results ) = _emit_diagnostics( $name, wantarray, $ok, "Incomplete name? $_", \@results, $max_msg
586 ) for @incomplete_names;
587 }
588 $ok = $tb->ok( 1, $name ) if $ok;
589  
590 return wantarray ? ( $ok, @results ) : $ok;
591 }
592  
593  
594 sub ok_lines_used($;$) {
595 # All lines serving some station must be defined (does not apply to other_links),
596 # but since newer versions of Map::Tube already test this on init, we don't repeat this.
597 # All defined lines must be serving some station (possibly within other_links),
598 # and, in fact, more than just one.
599 # (It seems that Test::Map::Tube does test for the former, but the message is a bit cryptic:
600 # "get_lines() returns incorrect line entries".)
601 # Lines must not come up both in ordinary and in other_links.
602 #
603 # Arguments:
604 # $map : a loadable Map::Tube object
605 # $argref : an optional hash ref with further arguments for the test.
606 # Only the entry for name will be used as a name to identify the map to the user.
607 #
608 # Return:
609 # in scalar context: a boolean indicating success (truey) or failure (falsey).
610 # Any diagnostics will have been output at the time of return.
611 # in array context: a list containing a boolean (as above), followed by all diagnostic
612 # messages (if any).
613 # It is the responsibility of the caller to display these messages
614 # to the user.
615 #
616 my ( $map, $argref ) = @_;
617 my $tb = Test::More->builder( );
618 $map = _prepare_raw_map($map) unless exists $map->{_rawinfo};
619 my $name = ( defined($argref) && ( ref($argref) eq 'HASH' ) && exists( $argref->{name} ) )
620 ? $argref->{name}
621 : ( $map->name( ) // 'A Map::Tube' );
622 my $max_msg = ( defined($argref) && ( ref($argref) eq 'HASH' ) && exists( $argref->{max_messages} ) )
623 ? $argref->{max_messages}
624 : 0;
625 my $rawinfo = $map->{_rawinfo};
626 my $ok = 1;
627 my @results;
628  
629 my @unserve_line_ids = sort grep { !$rawinfo->{line_ids_used}{$_} && !exists( $rawinfo->{other_link_used}{$_} ) }
630 keys %{ $rawinfo->{line_ids_defined} };
631 if (@unserve_line_ids) {
632 ( $ok, @results ) = _emit_diagnostics( $name, wantarray, $ok,
633 "Line id $_ defined but serves no stations (not even as other_link)",
634 \@results, $max_msg
635 ) for @unserve_line_ids;
636 }
637  
638 my @serve1_line_ids = sort grep { ( $rawinfo->{line_ids_used}{$_} == 1 ) && !exists( $rawinfo->{other_link_used}{$_} ) }
639 keys %{ $rawinfo->{line_ids_defined} };
640 if (@serve1_line_ids) {
641 ( $ok, @results ) = _emit_diagnostics( $name, wantarray, $ok,
642 "Line id $_ defined but serves only one station",
643 \@results, $max_msg
644 ) for @serve1_line_ids;
645 }
646  
647 my @line_and_other_link = sort grep { $rawinfo->{line_ids_used}{$_} && exists( $rawinfo->{other_link_used}{$_} ) }
648 keys %{ $rawinfo->{line_ids_used} };
649 if (@line_and_other_link) {
650 ( $ok, @results ) = _emit_diagnostics( $name, wantarray, $ok,
651 "Line id $_ used both as ordinary link and in other_link",
652 \@results, $max_msg
653 ) for @line_and_other_link;
654 }
655  
656 $ok = $tb->ok( 1, $name ) if $ok;
657  
658 return wantarray ? ( $ok, @results ) : $ok;
659 }
660  
661  
662 sub ok_stations_linked_share_lines($;$) {
663 # Stations that are linked must share at least one line (possibly through other_link).
664 # Lines serving some station must also serve at least one linked station (ordinary link).
665 # other_links at some station must also be named at at least one of the linked stations.
666 #
667 # Arguments:
668 # $map : a loadable Map::Tube object
669 # $argref : an optional hash ref with further arguments for the test.
670 # Only the entry for name will be used as a name to identify the map to the user.
671 #
672 # Return:
673 # in scalar context: a boolean indicating success (truey) or failure (falsey).
674 # Any diagnostics will have been output at the time of return.
675 # in array context: a list containing a boolean (as above), followed by all diagnostic
676 # messages (if any).
677 # It is the responsibility of the caller to display these messages
678 # to the user.
679 #
680 my ( $map, $argref ) = @_;
681 my $tb = Test::More->builder( );
682 $map = _prepare_raw_map($map) unless exists $map->{_rawinfo};
683 my $name = ( defined($argref) && ( ref($argref) eq 'HASH' ) && exists( $argref->{name} ) )
684 ? $argref->{name}
685 : ( $map->name( ) // 'A Map::Tube' );
686 my $max_msg = ( defined($argref) && ( ref($argref) eq 'HASH' ) && exists( $argref->{max_messages} ) )
687 ? $argref->{max_messages}
688 : 0;
689 my $rawinfo = $map->{_rawinfo};
690 my $ok = 1;
691 my @results;
692  
693 for my $station1 ( sort keys %{ $rawinfo->{station_linked_to_stations} } ) {
694 for my $station2 ( sort grep { $_ gt $station1 } keys %{ $rawinfo->{station_linked_to_stations}{$station1} } ) {
695 my $linect = scalar( grep { exists( $rawinfo->{station_served_by_lines}{$station2}{$_} ) }
696 keys %{ $rawinfo->{station_served_by_lines}{$station1} }
697 );
698 ( $ok, @results ) = _emit_diagnostics( $name, wantarray, $ok,
699 "Stations id $station1 and $station2 are linked but share no line",
700 \@results, $max_msg
701 ) unless $linect;
702 }
703 }
704  
705 for my $station ( sort keys %{ $rawinfo->{station_served_by_lines} } ) {
706 for my $line( grep { $rawinfo->{station_served_by_lines}{$station}{$_} == 1 }
707 keys %{ $rawinfo->{station_served_by_lines}{$station} }
708 ) {
709 my $stationct = grep { exists( $rawinfo->{station_served_by_lines}{$_}{$line} ) }
710 keys %{ $rawinfo->{station_linked_to_stations}{$station} };
711 $stationct += grep { exists( $rawinfo->{station_served_by_lines}{$_}{$line} ) }
712 keys %{ $rawinfo->{station_linked_from_stations}{$station} };
713 ( $ok, @results ) = _emit_diagnostics( $name, wantarray, $ok,
714 "Line id $line at station id $station serves neither a linked nor a linking station",
715 \@results, $max_msg
716 ) unless $stationct;
717 }
718 }
719  
720 for my $station ( sort keys %{ $rawinfo->{station_served_by_lines} } ) {
721 for my $line( grep { $rawinfo->{station_served_by_lines}{$station}{$_} == 2 }
722 keys %{ $rawinfo->{station_served_by_lines}{$station} }
723 ) {
724 my $stationct = grep { exists( $rawinfo->{station_served_by_lines}{$_}{$line} ) }
725 keys %{ $rawinfo->{station_linked_to_stations}{$station} };
726 ( $ok, @results ) = _emit_diagnostics( $name, wantarray, $ok,
727 "Other_link id $line at station id $station does not serve any linked station",
728 \@results, $max_msg
729 ) unless $stationct;
730 }
731 }
732  
733 $ok = $tb->ok( 1, $name ) if $ok;
734  
735 return wantarray ? ( $ok, @results ) : $ok;
736 }
737  
738  
739 sub ok_links_bidirectional($;$) {
740 # Are stations all linked symmetrically?
741 # This is optional -- links may legally be unidirectional.
742 # This is in many ways a fallible test and cannot be applied indiscriminately. Hence,
743 # it is optional to use this. Also, it can be tweaked by passing the ids (not names!) of
744 # lines that are known to be at least partially unidirectional.
745 # In general it is a good idea to check all those lines that are fully bidirectional (which
746 # in general is the vast majority) in order to catch accidental omissions of links.
747 #
748 # Arguments:
749 # $map : a loadable Map::Tube object
750 # $argref : an optional hash ref with further arguments for the test.
751 # The entry for name will be used as a name to identify the map to the user.
752 # The entry for exclude is the id of a single line to be excluded from
753 # the bidi check, or a reference to an array of such ids.
754 #
755 # Return:
756 # in scalar context: a boolean indicating success (truey) or failure (falsey).
757 # Any diagnostics will have been output at the time of return.
758 # in array context: a list containing a boolean (as above), followed by all diagnostic
759 # messages (if any).
760 # It is the responsibility of the caller to display these messages
761 # to the user.
762 #
763 my ( $map, $argref ) = @_;
764 my $tb = Test::More->builder( );
765 $map = _prepare_raw_map($map) unless exists $map->{_rawinfo};
766 my $name = ( defined($argref) && ( ref($argref) eq 'HASH' ) && exists( $argref->{name} ) )
767 ? $argref->{name}
768 : ( $map->name( ) // 'A Map::Tube' );
769 my $max_msg = ( defined($argref) && ( ref($argref) eq 'HASH' ) && exists( $argref->{max_messages} ) )
770 ? $argref->{max_messages}
771 : 0;
772 my %skip_lines_ids = ( defined($argref) && ( ref($argref) eq 'HASH' ) && exists( $argref->{exclude} ) )
773 ? ( map { uc($_) => 1 } ( ( ref($argref->{exclude}) eq 'ARRAY' )
774 ? @{ $argref->{exclude} }
775 : $argref->{exclude}
776 )
777 )
778 : ( );
779 my $rawinfo = $map->{_rawinfo};
780 my $ok = 1;
781 my @results;
782  
783 for my $station( sort keys %{ $rawinfo->{station_linked_to_stations} } ) {
784 for my $station1( grep { !exists( $rawinfo->{station_linked_to_stations}{$_}{$station} ) }
785 keys %{ $rawinfo->{station_linked_to_stations}{$station} }
786 ) {
787 my $linect = 0;
788 my @involved_lines;
789 my $exceptct = 0;
790 for my $line( keys( %{ $rawinfo->{station_served_by_lines}->{$station} } ) ) {
791 next unless exists $rawinfo->{station_served_by_lines}->{$station1}->{$line};
792 next if exists( $skip_lines_ids{$line} );
793 push( @involved_lines, $line );
794 }
795 ( $ok, @results ) = _emit_diagnostics( $name, wantarray, $ok,
796 "Station id $station linked to $station1 but not vice versa " .
797 "via line(s) id " . join( ',', sort @involved_lines ),
798 \@results, $max_msg
799 ) if @involved_lines;
800 }
801 }
802  
803 $ok = $tb->ok( 1, $name ) if $ok;
804  
805 return wantarray ? ( $ok, @results ) : $ok;
806 }
807  
808  
809 sub ok_lines_indexed($;$) {
810 # Each line must have either all or no stations indexed (but not some aye, some nay).
811 # Each line's indices must be unique.
812 #
813 # Arguments:
814 # $map : a loadable Map::Tube object
815 # $argref : an optional hash ref with further arguments for the test.
816 # Only the entry for name will be used as a name to identify the map to the user.
817 #
818 # Return:
819 # in scalar context: a boolean indicating success (truey) or failure (falsey).
820 # Any diagnostics will have been output at the time of return.
821 # in array context: a list containing a boolean (as above), followed by all diagnostic
822 # messages (if any).
823 # It is the responsibility of the caller to display these messages
824 # to the user.
825 #
826 my ( $map, $argref ) = @_;
827 my $tb = Test::More->builder( );
828 $map = _prepare_raw_map($map) unless exists $map->{_rawinfo};
829 my $name = ( defined($argref) && ( ref($argref) eq 'HASH' ) && exists( $argref->{name} ) )
830 ? $argref->{name}
831 : ( $map->name( ) // 'A Map::Tube' );
832 my $max_msg = ( defined($argref) && ( ref($argref) eq 'HASH' ) && exists( $argref->{max_messages} ) )
833 ? $argref->{max_messages}
834 : 0;
835 my $rawinfo = $map->{_rawinfo};
836 my $ok = 1;
837 my @results;
838  
839 my @partially_indexed = sort grep { ( $rawinfo->{line_ids_indexed}{$_} != 0 ) &&
840 ( $rawinfo->{line_ids_indexed}{$_} != $rawinfo->{line_ids_used}{$_} )
841 } keys %{ $rawinfo->{line_ids_used} };
842 if (@partially_indexed) {
843 ( $ok, @results ) = _emit_diagnostics( $name, wantarray, $ok,
844 "Line id $_ is partially indexed but not completely", \@results, $max_msg
845 ) for @partially_indexed;
846 }
847  
848 my @messed_up_lines;
849 for my $line( sort keys %{ $rawinfo->{line_id_has_indices} } ) {
850 my @nonuniq_idx = grep { $rawinfo->{line_id_has_indices}{$line}{$_} > 1 }
851 keys %{ $rawinfo->{line_id_has_indices}{$line} };
852 ( $ok, @results ) = _emit_diagnostics( $name, wantarray, $ok,
853 "Line id $line has non-unique indices: " .
854 join( ',', sort { $a <=> $b } @nonuniq_idx ),
855 \@results, $max_msg
856 ) if @nonuniq_idx;
857 }
858  
859 $ok = $tb->ok( 1, $name ) if $ok;
860  
861 return wantarray ? ( $ok, @results ) : $ok;
862 }
863  
864  
865 sub ok_lines_run_through($;$) {
866 # Each line should be weakly connected, i.e., there should be no gaps in lines (at least
867 # not when disregarding directionality).
868 # If exceptionally this is known not to hold for certain lines, their ids (not names) can
869 # be passed to this method.
870 #
871 # Arguments:
872 # $map : a loadable Map::Tube object
873 # $argref : an optional hash ref with further arguments for the test.
874 # The entry for name will be used as a name to identify the map to the user.
875 # The entry for exclude is the id of a single line to be excluded from
876 # the connectivity check, or a reference to an array of such ids.
877 #
878 # Return:
879 # in scalar context: a boolean indicating success (truey) or failure (falsey).
880 # Any diagnostics will have been output at the time of return.
881 # in array context: a list containing a boolean (as above), followed by all diagnostic
882 # messages (if any).
883 # It is the responsibility of the caller to display these messages
884 # to the user.
885 #
886 my ( $map, $argref ) = @_;
887 my $tb = Test::More->builder( );
888 $map = _prepare_raw_map($map) unless exists $map->{_rawinfo};
889 my $name = ( defined($argref) && ( ref($argref) eq 'HASH' ) && exists( $argref->{name} ) )
890 ? $argref->{name}
891 : ( $map->name( ) // 'A Map::Tube' );
892 my $max_msg = ( defined($argref) && ( ref($argref) eq 'HASH' ) && exists( $argref->{max_messages} ) )
893 ? $argref->{max_messages}
894 : 0;
895 my %skip_lines_ids = ( defined($argref) && ( ref($argref) eq 'HASH' ) && exists( $argref->{exclude} ) )
896 ? ( map { uc($_) => 1 } ( ( ref($argref->{exclude}) eq 'ARRAY' )
897 ? @{ $argref->{exclude} }
898 : $argref->{exclude}
899 )
900 )
901 : ( );
902 my $rawinfo = $map->{_rawinfo};
903 my $ok = 1;
904 my @results;
905  
906 eval 'use Graph';
907 return _emit_diagnostics( $name, wantarray, $ok, 'Module Graph required for testing connectedness of map', \@results,
908 $max_msg ) if $@;
909  
910 # For each line separately:
911 # Build a list of pairs of (directly) linked stations on this line
912 for my $line_id( grep { !exists( $skip_lines_ids{$_} ) } keys %{ $rawinfo->{line_ids_defined} } ) {
913 my @all_links;
914 for my $station( grep { exists( $rawinfo->{station_served_by_lines}->{$_}->{$line_id} ) }
915 keys %{ $rawinfo->{station_linked_to_stations} }
916 ) {
917 push( @all_links, [ $station, $_ ] ) for grep { ( $rawinfo->{station_served_by_lines}->{$_}->{$line_id} ) }
918 keys %{ $rawinfo->{station_linked_to_stations}->{$station}
919 };
920 }
921  
922 my $graph = Graph->new( directed => 1, edges => \@all_links );
923 if ( !$graph->is_weakly_connected( ) ) {
924 my @components = $graph->weakly_connected_components( );
925 ( $ok, @results ) = _emit_diagnostics( $name, wantarray, $ok,
926 "Line id $line_id consists of " . scalar(@components) .
927 ' separate components',
928 \@results, $max_msg );
929 }
930 }
931  
932 $ok = $tb->ok( 1, $name ) if $ok;
933  
934 return wantarray ? ( $ok, @results ) : $ok;
935 }
936  
937  
938 sub ok_map_connected($;$) {
939 # Is the whole map connected, i.e., are there routes between any two stations?
940 # If so: are there connections between any two stations? (Might not be if there are
941 # unidirectional links).
942 # In either case, show examples of stations in different components if any.
943 # For maps that are known not to be connected, the expected maximum number of components
944 # may be specified. Defaults to 1.
945 #
946 # Arguments:
947 # $map : a loadable Map::Tube object
948 # $argref : an optional hash ref with further arguments for the test.
949 # The entry for name will be used as a name to identify the map to the user.
950 # max_allowed sets the threshold on the number of issues as outlined above.
951 # Default: 0
952 #
953 # Return:
954 # in scalar context: a boolean indicating success (truey) or failure (falsey).
955 # Any diagnostics will have been output at the time of return.
956 # in array context: a list containing a boolean (as above), followed by all diagnostic
957 # messages (if any).
958 # It is the responsibility of the caller to display these messages
959 # to the user.
960 #
961 my ( $map, $argref ) = @_;
962 my $tb = Test::More->builder( );
963 $map = _prepare_raw_map($map) unless exists $map->{_rawinfo};
964 my $name = ( defined($argref) && ( ref($argref) eq 'HASH' ) && exists( $argref->{name} ) )
965 ? $argref->{name}
966 : ( $map->name( ) // 'A Map::Tube' );
967 my $max_msg = ( defined($argref) && ( ref($argref) eq 'HASH' ) && exists( $argref->{max_messages} ) )
968 ? $argref->{max_messages}
969 : 0;
970 my $max_allowed = ( defined($argref) && ( ref($argref) eq 'HASH' ) && exists( $argref->{max_allowed} ) )
971 ? $argref->{max_allowed}
972 : 0;
973 my $rawinfo = $map->{_rawinfo};
974 my $ok = 1;
975 my @results;
976  
977 eval 'use Graph';
978 return _emit_diagnostics( $name, wantarray, $ok,
979 'Module Graph required for testing connectedness of map', \@results,
980 $max_msg ) if $@;
981  
982 # Build a list of pairs of (directly) linked stations (possibly by other_link)
983 my @all_links;
984 for my $station( keys %{ $rawinfo->{station_linked_to_stations} } ) {
985 push( @all_links, [ $station, $_ ] ) for keys %{ $rawinfo->{station_linked_to_stations}->{$station} };
986 }
987 # note( "*** Total number of links: ", scalar(@all_links) );
988  
989 my $graph = Graph->new( directed => 1, edges => \@all_links );
990  
991 # Check whether map is (somehow) connected, ignoring possible unidirectionality:
992 if ( !$graph->is_weakly_connected( ) ) {
993 my @components = sort { ( scalar(@$b) <=> scalar(@$a) ) ||
994 ( join( ':', sort(@$a) ) cmp join( ':', sort(@$b) ) )
995 } $graph->weakly_connected_components( );
996 if ( scalar(@components) > $max_allowed ) {
997 my @examples = sort map { ( sort(@$_) )[0] } @components;
998 ( $ok, @results ) = _emit_diagnostics( $name, wantarray, $ok,
999 'Map has ' . scalar(@components) .
1000 ' separate components; e.g., stations with ids ' .
1001 join( ', ', @examples ),
1002 \@results, $max_msg
1003 );
1004 }
1005 }
1006  
1007 if ($ok) {
1008 # Map is at least weakly connected, but maybe not all stations reachable from
1009 # each other station?
1010 if ( !$graph->is_strongly_connected( ) ) {
1011 my @components = sort { ( scalar(@$b) <=> scalar(@$a) ) ||
1012 ( join( ':', sort(@$a) ) cmp join( ':', sort(@$b) ) )
1013 } $graph->strongly_connected_components( );
1014 # Components sorted descending by size in a strictly reproducible order
1015 if ( scalar(@components) > $max_allowed ) {
1016 my( $station1, @examples ) = map { ( sort(@$_) )[0] } @components;
1017 # $station1 is taken from the largest component, because we assume that one
1018 # to be the "healthiest"
1019 my @unlinked;
1020 diag('For big maps this test may take long... ') if ( scalar(@all_links) > 50 );
1021 # because the Graph module has to do a lot of work upfront
1022 for (sort @examples) {
1023 my $unlink = $graph->is_reachable( $station1, $_ ) ? ( $_ . '//' . $station1 ) : ( $station1 . '//' . $_ );
1024 push( @unlinked, $unlink );
1025 }
1026 ($ok, @results) = _emit_diagnostics( $name, wantarray, $ok,
1027 'Not every station reachable from every other station -- map has ' .
1028 scalar(@components) .
1029 ' separate components; e.g., stations with ids ' .
1030 join( ', ', sort @unlinked ),
1031 \@results, $max_msg
1032 );
1033 }
1034 }
1035 }
1036  
1037 $ok = $tb->ok( 1, $name ) if $ok;
1038  
1039 return wantarray ? ( $ok, @results ) : $ok;
1040 }
1041  
1042  
1043 sub ok_line_definitions($;$) {
1044 # Line Ids must not contain comma or colon (for syntactical reasons).
1045 # Color specifications must be either hex (#RRGGBB) or from a pre-defined set of
1046 # color names (see Map::Tube::Utils).
1047 #
1048 # Arguments:
1049 # $map : a loadable Map::Tube object
1050 # $argref : an optional hash ref with further arguments for the test.
1051 # Only the entry for name will be used as a name to identify the map to the user.
1052 #
1053 # Return:
1054 # in scalar context: a boolean indicating success (truey) or failure (falsey).
1055 # Any diagnostics will have been output at the time of return.
1056 # in array context: a list containing a boolean (as above), followed by all diagnostic
1057 # messages (if any).
1058 # It is the responsibility of the caller to display these messages
1059 # to the user.
1060 #
1061 my ( $map, $argref ) = @_;
1062 my $tb = Test::More->builder( );
1063 $map = _prepare_raw_map($map) unless exists $map->{_rawinfo};
1064 my $name = ( defined($argref) && ( ref($argref) eq 'HASH' ) && exists( $argref->{name} ) )
1065 ? $argref->{name}
1066 : ( $map->name( ) // 'A Map::Tube' );
1067 my $max_msg = ( defined($argref) && ( ref($argref) eq 'HASH' ) && exists( $argref->{max_messages} ) )
1068 ? $argref->{max_messages}
1069 : 0;
1070 my $rawinfo = $map->{_rawinfo};
1071 my $ok = 1;
1072 my @results;
1073  
1074 ($ok, @results ) = _emit_diagnostics( $name, wantarray, $ok,
1075 "Line ID '$_' must not contain comma (,) or colon (:)",
1076 \@results, $max_msg
1077 ) for grep { /[,:]/ } sort keys %{ $rawinfo->{line_names} };
1078  
1079 eval 'use Map::Tube::Utils';
1080 return _emit_diagnostics( $name, wantarray, $ok,
1081 'Map::Tube::Utils required for testing color names', \@results,
1082 $max_msg ) if $@;
1083  
1084 ($ok, @results ) = _emit_diagnostics( $name, wantarray, $ok,
1085 'Line ' . $_->{name} . ' has invalid color ' . $_->{color},
1086 \@results, $max_msg
1087 ) for grep { defined( $_->{color} ) && !Map::Tube::Utils::is_valid_color($_->{color}) }
1088 @{ $map->{lines} };
1089  
1090 $ok = $tb->ok( 1, $name ) if $ok;
1091  
1092 return wantarray ? ( $ok, @results ) : $ok;
1093 }
1094  
1095  
1096 sub ok_station_ids($;$) {
1097 # Station Ids must not contain comma or colon (for syntactical reasons).
1098 #
1099 # Arguments:
1100 # $map : a loadable Map::Tube object
1101 # $argref : an optional hash ref with further arguments for the test.
1102 # Only the entry for name will be used as a name to identify the map to the user.
1103 #
1104 # Return:
1105 # in scalar context: a boolean indicating success (truey) or failure (falsey).
1106 # Any diagnostics will have been output at the time of return.
1107 # in array context: a list containing a boolean (as above), followed by all diagnostic
1108 # messages (if any).
1109 # It is the responsibility of the caller to display these messages
1110 # to the user.
1111 #
1112 my ( $map, $argref ) = @_;
1113 my $tb = Test::More->builder( );
1114 my $name = ( defined($argref) && ( ref($argref) eq 'HASH' ) && exists( $argref->{name} ) )
1115 ? $argref->{name}
1116 : ( $map->name( ) // 'A Map::Tube' );
1117 my $max_msg = ( defined($argref) && ( ref($argref) eq 'HASH' ) && exists( $argref->{max_messages} ) )
1118 ? $argref->{max_messages}
1119 : 0;
1120 my $ok = 1;
1121 my @results;
1122  
1123 ($ok, @results ) = _emit_diagnostics( $name, wantarray, $ok,
1124 "Station ID '$_' must not contain comma (,) or colon (:)",
1125 \@results, $max_msg
1126 ) for grep { /[,:]/ } sort keys %{ $map->{nodes} };
1127  
1128 $ok = $tb->ok( 1, $name ) if $ok;
1129  
1130 return wantarray ? ( $ok, @results ) : $ok;
1131 }
1132  
1133  
1134 sub ok_stations_linked($;$) {
1135 # Linked-to stations must be defined as stations.
1136 #
1137 # Arguments:
1138 # $map : a loadable Map::Tube object
1139 # $argref : an optional hash ref with further arguments for the test.
1140 # Only the entry for name will be used as a name to identify the map to the user.
1141 #
1142 # Return:
1143 # in scalar context: a boolean indicating success (truey) or failure (falsey).
1144 # Any diagnostics will have been output at the time of return.
1145 # in array context: a list containing a boolean (as above), followed by all diagnostic
1146 # messages (if any).
1147 # It is the responsibility of the caller to display these messages
1148 # to the user.
1149 #
1150 my ( $map, $argref ) = @_;
1151 my $tb = Test::More->builder( );
1152 my $name = ( defined($argref) && ( ref($argref) eq 'HASH' ) && exists( $argref->{name} ) )
1153 ? $argref->{name}
1154 : ( $map->name( ) // 'A Map::Tube' );
1155 my $max_msg = ( defined($argref) && ( ref($argref) eq 'HASH' ) && exists( $argref->{max_messages} ) )
1156 ? $argref->{max_messages}
1157 : 0;
1158 my $ok = 1;
1159 my @results;
1160  
1161 my %linked;
1162 for my $id( sort keys %{ $map->{nodes} } ) {
1163 $linked{$_}{$id}++ for ( sort grep { ( $_ ne '' ) && !exists( $map->{nodes}->{$_} ) } split( /\,/, $map->{nodes}->{$id}->{link} ) );
1164 }
1165  
1166 ($ok, @results ) = _emit_diagnostics( $name, wantarray, $ok,
1167 "Undefined station ID $_ is linked to from station(s) " .
1168 join( ',', sort keys %{ $linked{$_} } ),
1169 \@results, $max_msg
1170 ) for sort keys %linked;
1171  
1172 $ok = $tb->ok( 1, $name ) if $ok;
1173  
1174 return wantarray ? ( $ok, @results ) : $ok;
1175 }
1176  
1177  
1178 sub ok_stations_self_linked($;$) {
1179 # Stations should not be linked to themselves.
1180 #
1181 # Arguments:
1182 # $map : a loadable Map::Tube object
1183 # $argref : an optional hash ref with further arguments for the test.
1184 # Only the entry for name will be used as a name to identify the map to the user.
1185 #
1186 # Return:
1187 # in scalar context: a boolean indicating success (truey) or failure (falsey).
1188 # Any diagnostics will have been output at the time of return.
1189 # in array context: a list containing a boolean (as above), followed by all diagnostic
1190 # messages (if any).
1191 # It is the responsibility of the caller to display these messages
1192 # to the user.
1193 #
1194 my ( $map, $argref ) = @_;
1195 my $tb = Test::More->builder( );
1196 $map = _prepare_raw_map($map) unless exists $map->{_rawinfo};
1197 my $name = ( defined($argref) && ( ref($argref) eq 'HASH' ) && exists( $argref->{name} ) )
1198 ? $argref->{name}
1199 : ( $map->name( ) // 'A Map::Tube' );
1200 my $max_msg = ( defined($argref) && ( ref($argref) eq 'HASH' ) && exists( $argref->{max_messages} ) )
1201 ? $argref->{max_messages}
1202 : 0;
1203 my $rawinfo = $map->{_rawinfo};
1204 my $ok = 1;
1205 my @results;
1206  
1207 ($ok, @results ) = _emit_diagnostics( $name, wantarray, $ok,
1208 "Station ID $_ links to itself", \@results, $max_msg
1209 ) for sort grep { exists( $rawinfo->{station_linked_to_stations}{$_}{$_} ) }
1210 keys %{ $rawinfo->{station_linked_to_stations} };
1211  
1212 $ok = $tb->ok( 1, $name ) if $ok;
1213  
1214 return wantarray ? ( $ok, @results ) : $ok;
1215 }
1216  
1217  
1218 sub ok_stations_multilinked($;$) {
1219 # Stations should not name linked stations more than once.
1220 # (Any two stations may be linked by more than one line, but the link should still name
1221 # each station only once.)
1222 #
1223 # Arguments:
1224 # $map : a loadable Map::Tube object
1225 # $argref : an optional hash ref with further arguments for the test.
1226 # Only the entry for name will be used as a name to identify the map to the user.
1227 #
1228 # Return:
1229 # in scalar context: a boolean indicating success (truey) or failure (falsey).
1230 # Any diagnostics will have been output at the time of return.
1231 # in array context: a list containing a boolean (as above), followed by all diagnostic
1232 # messages (if any).
1233 # It is the responsibility of the caller to display these messages
1234 # to the user.
1235 #
1236 my ( $map, $argref ) = @_;
1237 my $tb = Test::More->builder( );
1238 my $name = ( defined($argref) && ( ref($argref) eq 'HASH' ) && exists( $argref->{name} ) )
1239 ? $argref->{name}
1240 : ( $map->name( ) // 'A Map::Tube' );
1241 my $max_msg = ( defined($argref) && ( ref($argref) eq 'HASH' ) && exists( $argref->{max_messages} ) )
1242 ? $argref->{max_messages}
1243 : 0;
1244 my $ok = 1;
1245 my @results;
1246  
1247 for my $station ( sort keys %{ $map->{nodes} } ) {
1248 my %links;
1249 $links{$_}++ for split( /,/, $map->{nodes}->{$station}->{link} );
1250 ($ok, @results ) = _emit_diagnostics( $name, wantarray, $ok,
1251 "Station ID $station links to station ID $_ " .
1252 $links{$_} . ' times',
1253 \@results, $max_msg
1254 ) for sort grep { $links{$_} > 1 } keys %links;
1255 }
1256  
1257 $ok = $tb->ok( 1, $name ) if $ok;
1258  
1259 return wantarray ? ( $ok, @results ) : $ok;
1260 }
1261  
1262  
1263 sub ok_stations_multilined($;$) {
1264 # Stations should not name the same line more than once.
1265 # This applies only to regular links, not to other_links, where multiple mentions are
1266 # quite normal.
1267 #
1268 # Arguments:
1269 # $map : a loadable Map::Tube object
1270 # $argref : an optional hash ref with further arguments for the test.
1271 # Only the entry for name will be used as a name to identify the map to the user.
1272 #
1273 # Return:
1274 # in scalar context: a boolean indicating success (truey) or failure (falsey).
1275 # Any diagnostics will have been output at the time of return.
1276 # in array context: a list containing a boolean (as above), followed by all diagnostic
1277 # messages (if any).
1278 # It is the responsibility of the caller to display these messages
1279 # to the user.
1280 #
1281 my ( $map, $argref ) = @_;
1282 my $tb = Test::More->builder( );
1283 $map = _prepare_raw_map($map) unless exists $map->{_rawinfo};
1284 my $name = ( defined($argref) && ( ref($argref) eq 'HASH' ) && exists( $argref->{name} ) )
1285 ? $argref->{name}
1286 : ( $map->name( ) // 'A Map::Tube' );
1287 my $max_msg = ( defined($argref) && ( ref($argref) eq 'HASH' ) && exists( $argref->{max_messages} ) )
1288 ? $argref->{max_messages}
1289 : 0;
1290 my $rawinfo = $map->{_rawinfo};
1291 my $ok = 1;
1292 my @results;
1293  
1294 for my $station ( sort keys %{ $rawinfo->{station_line_count} } ) {
1295 ($ok, @results ) = _emit_diagnostics( $name, wantarray, $ok,
1296 "Station ID $station names line ID $_ " .
1297 $rawinfo->{station_line_count}->{$station}->{$_} . ' times',
1298 \@results, $max_msg
1299 ) for sort grep { $rawinfo->{station_line_count}->{$station}->{$_} > 1 }
1300 keys %{ $rawinfo->{station_line_count}->{$station} };
1301 }
1302  
1303 $ok = $tb->ok( 1, $name ) if $ok;
1304  
1305 return wantarray ? ( $ok, @results ) : $ok;
1306 }
1307  
1308  
1309 # add more test definitions here...
1310  
1311  
1312 #
1313 #
1314 # PRIVATE METHODS
1315  
1316  
1317 sub _ok_map_functions {
1318 my ($object) = @_;
1319  
1320 return 0 unless ( defined $object && $object->does('Map::Tube') );
1321  
1322 my $actual;
1323 eval { $actual = $object->get_map_data };
1324 ($@) and ( carp('no map data found' ) and return 0 );
1325  
1326 # get_shortest_route()
1327 eval { $object->get_shortest_route };
1328 ($@) or ( carp('get_shortest_route() with no param') and return 0 );
1329 eval { $object->get_shortest_route('Foo') };
1330 ($@) or ( carp('get_shortest_route() with one param') and return 0 );
1331 eval { $object->get_shortest_route( 'Foo', 'Bar' ) };
1332 ($@) or ( carp('get_shortest_route() with two invalid params') and return 0 );
1333 my $from_station = $actual->{stations}->{station}->[0]->{name};
1334 my $to_station = $actual->{stations}->{station}->[1]->{name};
1335 eval { $object->get_shortest_route( $from_station, 'Bar' ) };
1336 ($@) or ( carp('get_shortest_route() with invalid to station') and return 0 );
1337 eval { $object->get_shortest_route( 'Foo', $to_station ) };
1338 ($@) or ( carp('get_shortest_route() with invalid from station') and return 0 );
1339 eval { $object->get_shortest_route( $from_station, $to_station ) };
1340 ($@) and carp($@) and return 0;
1341  
1342 # get_name()
1343 if ( exists $actual->{name} && defined $actual->{name}) {
1344 ( $object->name eq $actual->{name} )
1345 or ( carp('name() returns incorrect map name') and return 0 );
1346 }
1347  
1348 # get_lines()
1349 my $lines_count = scalar(@{$actual->{lines}->{line}});
1350 ( scalar( @{ $object->get_lines} ) == $lines_count )
1351 or ( carp('get_lines() returns incorrect line entries') and return 0 );
1352  
1353 # get_stations()
1354 eval { $object->get_stations('Not-A-Valid-Line-Name') };
1355 ($@) or ( carp('get_stations() with invalid line name') and return 0 );
1356 my $line_name = $actual->{lines}->{line}->[0]->{name};
1357 ( scalar( @{ $object->get_stations($line_name)} ) > 0 )
1358 or ( carp('get_stations() returns incorrect station entries') and return 0 );
1359  
1360 # get_next_stations()
1361 eval { $object->get_next_stations };
1362 ($@) or ( carp('get_next_stations() with no param' . Dumper($@) ) and return 0 );
1363 eval { $object->get_next_stations('Not-A-Valid-Station-Name') };
1364 ($@) or ( carp('get_next_stations() with invalid station name') and return 0 );
1365 ( scalar( @{ $object->get_next_stations($from_station) } ) > 0 )
1366 or (carp('get_next_stations() returns incorrect station entries') and return 0 );
1367  
1368 # get_line_by_id()
1369 eval { $object->get_line_by_id };
1370 ($@) or ( carp('get_line_by_id() with no param') and return 0 );
1371 eval { $object->get_line_by_id('Not-A-Valid-Line-ID') };
1372 ($@) or ( carp('get_line_by_id() with invalid id') and return 0 );
1373 my $line_id = $actual->{lines}->{line}->[0]->{id};
1374 eval { $object->get_line_by_id($line_id) };
1375 ($@) and ( carp($@) and return 0 );
1376  
1377 # get_line_by_name() - handle in case Map::Tube::Plugin::FuzzyNames is installed.
1378 eval { $object->get_line_by_name($line_name) };
1379 ($@) and ( carp($@) and return 0 );
1380 eval { my $l = $object->get_line_by_name('Not-A-Valid-Line-Name'); croak() unless defined $l };
1381 ($@) or ( carp('get_line_by_name() with invalid line name') and return 0 );
1382 eval { my $l = $object->get_line_by_name; croak() unless defined $l; };
1383 ($@) or ( carp('get_line_by_name() with no param') and return 0 );
1384  
1385 # get_node_by_id()
1386 eval { $object->get_node_by_id };
1387 ($@) or ( carp('get_node_by_id() with no param') and return 0 );
1388 eval { $object->get_node_by_id('Not-A-Valid-Node-ID') };
1389 ($@) or ( carp('get_node_by_id() with invalid node id') and return 0 );
1390 my $station_id = $actual->{stations}->{station}->[0]->{id};
1391 eval { $object->get_node_by_id($station_id) };
1392 ($@) and ( carp($@) and return 0 );
1393  
1394 # add_station()
1395 eval { $object->get_line_by_id($line_id)->add_station };
1396 ($@) or ( carp('add_station() with no param') and return 0 );
1397 eval { $object->get_line_by_id($line_id)->add_station('Not-A-Valid-Station') };
1398 ($@) or ( carp('add_station() with invalid node object') and return 0 );
1399 eval { $object->get_line_by_id($line_id)->add_station($object->get_node_by_id($station_id)) };
1400 ($@) and ( carp($@) and return 0 );
1401  
1402 # get_node_by_name()
1403 eval { $object->get_node_by_name };
1404 ($@) or ( carp('get_node_by_name() with no param') and return 0 );
1405 eval { $object->get_node_by_name('Not-A-Valid-Node-Name') };
1406 ($@) or ( carp('get_node_by_name() with invalid node name') and return 0 );
1407 eval { $object->get_node_by_name($from_station) };
1408 ($@) and ( carp($@) and return 0 );
1409  
1410 return 1;
1411 }
1412  
1413 sub _ok_map_routes {
1414 my ( $object, $routes ) = @_;
1415 return 0 unless ( defined $object && $object->does('Map::Tube') );
1416 eval { $object->get_map_data };
1417 ($@) and ( carp('no map data found') and return 0 );
1418 my @failed;
1419 foreach (@$routes) {
1420 chomp;
1421 next if /^\#/;
1422 next if /^\s+$/;
1423 my ( $description, $from, $to, $route ) = split /\|/;
1424 my $got = $object->get_shortest_route( $from, $to );
1425 my $expected = _expected_route( $object, $route );
1426 next if Compare( $got, $expected );
1427 push @failed, [ $got, $expected, $description ];
1428 }
1429 return @failed;
1430 }
1431  
1432 sub _expected_route {
1433 my ($object, $route) = @_;
1434  
1435 my $nodes = [];
1436 foreach my $name ( split /\,/,$route ) {
1437 my @_names = $object->get_node_by_name($name);
1438 push @$nodes, $_names[0];
1439 }
1440  
1441 return Map::Tube::Route->new(
1442 { from => $nodes->[0],
1443 to => $nodes->[-1],
1444 nodes => $nodes
1445 });
1446 }
1447  
1448  
1449 sub _emit_diagnostics($$$$$$) {
1450 # Handle the nitty-gritty of producing (negative) diagnostics in various contexts
1451 my( $name, $want_array, $ok, $msg, $results, $max_msg ) = @_;
1452 my $tb = Test::More->builder( );
1453 my $test_level = $tb->level( );
1454 $tb->level( $test_level+1 );
1455  
1456 if ($want_array) {
1457 $ok = 0;
1458 } else {
1459 diag($msg) if ( !$max_msg || ( scalar( @{ $results } ) < $max_msg ) );
1460 $ok &&= $tb->ok( 0, $name );
1461 }
1462 push( @{ $results }, $msg ) if ( !$max_msg || ( scalar( @{ $results } ) < $max_msg ) );
1463  
1464 $tb->level( $test_level );
1465 return $want_array ? ( $ok, @{ $results } ) : $ok;
1466 }
1467  
1468  
1469 use Carp;
1470  
1471 sub _prepare_raw_map {
1472 # analyse the original map data (XML or JSON) and store it
1473 # surreptitiously in the Map::Tube object for later use.
1474 my $map = shift;
1475 return _prepare_xml_map($map ) if $map->can('xml');
1476 return _prepare_json_map($map) if $map->can('json');
1477 croak( "Don't know how to access underlying map data" );
1478 }
1479  
1480  
1481 sub _prepare_xml_map {
1482 # analyse the original map data (XML format) and store them
1483 # surreptitiously in the Map::Tube object for later use.
1484 eval 'use XML::Twig';
1485 plan skip_all => 'XML::Twig required' if $@;
1486  
1487 my $map = shift;
1488 my $xml = XML::Twig->new( );
1489 $xml->parsefile( $map->xml( ) );
1490 my $root = $xml->root( );
1491 my( %line_names, %line_names_uc, %line_ids_defined, %line_ids_used,
1492 %line_ids_indexed, %line_id_has_indices, %other_link_used,
1493 %station_names, %station_ids_defined, %station_ids_used,
1494 %station_linked_to_stations, %station_linked_from_stations, %station_served_by_lines,
1495 %station_line_count,
1496 );
1497  
1498 my $line = $root->first_child('lines')->first_child('line');
1499 while ($line) {
1500 my $id_case = $line->att('id');
1501 my $id = uc($id_case);
1502 my $name = $line->att('name');
1503 $line_names_uc{uc($name)} //= { };
1504 $line_names{$name} //= [ ];
1505 $line_names_uc{uc($name)}{$name}++;
1506 push( @{ $line_names{$name} }, $id );
1507 $line_ids_defined{$id} //= [ ];
1508 push( @{ $line_ids_defined{$id} }, $id_case );
1509 $line_ids_used{$id} = 0;
1510 $line_ids_indexed{$id} = 0;
1511 $line = $line->next_sibling( );
1512 }
1513  
1514 my $station = $root->first_child('stations')->first_child('station');
1515 while ($station) {
1516 my $id = $station->att('id');
1517 my $name = $station->att('name');
1518 $station_names{$name} //= [ ];
1519 push( @{ $station_names{$name} }, $id );
1520 $station_ids_defined{$id}++;
1521 $station_ids_used{$_}++ for map { ( split(/:/) )[0] } split( /,/, $station->att('link') );
1522 $station_linked_to_stations{$id}{$_} |= 1 for map { ( split(/:/) )[0] } split( /,/, $station->att('link') );
1523 $station_linked_from_stations{$_}{$id} |= 1 for map { ( split(/:/) )[0] } split( /,/, $station->att('link') );
1524  
1525 for ( map { uc( ( split( /:/) )[0] ) } split( /,/, $station->att('line') ) ) {
1526 $line_ids_used{uc($_)}++;
1527 $station_served_by_lines{$id}{$_} |= 1;
1528 $station_line_count{$id}{$_}++;
1529 }
1530 for ( grep { scalar( split(/:/) ) > 1 } split( /,/, $station->att('line') ) ) {
1531 # line entry with station index
1532 my( $line, $idx ) = split( /:/, $_ );
1533 $line = uc($line);
1534 $line_ids_indexed{$line}++;
1535 $line_id_has_indices{$line}{$idx}++;
1536 }
1537  
1538 if ( defined( $station->att('other_link') ) ) {
1539 for my $other_link ( split( /,/, $station->att('other_link') ) ) {
1540 my( $ol, $target ) = split( /:/, $other_link );
1541 $other_link_used{$ol}++;
1542 $station_ids_used{$target}++;
1543 $station_linked_to_stations{$id}{$target} |= 2;
1544 $station_linked_from_stations{$target}{$id} |= 2;
1545 $station_served_by_lines{$id}{$ol} |= 2;
1546 }
1547 }
1548  
1549 $station = $station->next_sibling( );
1550 }
1551  
1552 $map->{_rawinfo} = { line_names => \%line_names,
1553 line_names_uc => \%line_names_uc,
1554 line_ids_defined => \%line_ids_defined,
1555 line_ids_used => \%line_ids_used,
1556 line_ids_indexed => \%line_ids_indexed,
1557 line_id_has_indices => \%line_id_has_indices,
1558 station_names => \%station_names,
1559 station_ids_defined => \%station_ids_defined,
1560 station_ids_used => \%station_ids_used,
1561 station_line_count => \%station_line_count,
1562 other_link_used => \%other_link_used,
1563 station_linked_to_stations => \%station_linked_to_stations,
1564 station_linked_from_stations => \%station_linked_from_stations,
1565 station_served_by_lines => \%station_served_by_lines,
1566 };
1567 return $map;
1568 }
1569  
1570  
1571 sub _prepare_json_map {
1572 # analyse the original map data (JSON format) and store them
1573 # surreptitiously in the Map::Tube object for later use.
1574 eval 'use Map::Tube::Utils';
1575 plan skip_all => 'Map::Tube::Utils required (should have been installed along with Map::Tube)' if $@;
1576  
1577 my $map = shift;
1578 my( %line_names, %line_names_uc, %line_ids_defined, %line_ids_used,
1579 %line_ids_indexed, %line_id_has_indices, %other_link_used,
1580 %station_names, %station_ids_defined, %station_ids_used,
1581 %station_linked_to_stations, %station_linked_from_stations, %station_served_by_lines,
1582 %station_line_count,
1583 );
1584  
1585 my $json = Map::Tube::Utils::to_perl( $map->json( ) );
1586  
1587 for my $line ( @{ $json->{lines}{line} } ) {
1588 my $id_case = $line->{id};
1589 my $id = uc($id_case);
1590 my $name = $line->{name};
1591 $line_names_uc{uc($name)} //= { };
1592 $line_names{$name} //= [ ];
1593 $line_names_uc{uc($name)}{$name}++;
1594 push( @{ $line_names{$name} }, $id );
1595 $line_ids_defined{$id} //= [ ];
1596 push( @{ $line_ids_defined{$id} }, $id_case );
1597 $line_ids_used{$id} = 0;
1598 $line_ids_indexed{$id} = 0;
1599 }
1600  
1601 for my $station ( @{ $json->{stations}{station} } ) {
1602 my $id = $station->{id};
1603 my $name = $station->{name};
1604 $station_names{$name} //= [ ];
1605 push( @{ $station_names{$name} }, $id );
1606 $station_ids_defined{$id}++;
1607 $station_ids_used{$_}++ for map { ( split(/:/) )[0] } split( /,/, $station->{link} );
1608 $station_linked_to_stations{$id}{$_} |= 1 for map { ( split(/:/) )[0] } split( /,/, $station->{link} );
1609 $station_linked_from_stations{$_}{$id} |= 1 for map { ( split(/:/) )[0] } split( /,/, $station->{link} );
1610  
1611 for ( map { uc( ( split( /:/) )[0] ) } split( /,/, $station->{line} ) ) {
1612 $line_ids_used{$_}++;
1613 $station_served_by_lines{$id}{$_} |= 1;
1614 $station_line_count{$id}{$_}++;
1615 }
1616 for ( grep { scalar( split(/:/) ) > 1 } split( /,/, $station->{line} ) ) {
1617 my( $line, $idx ) = split( /:/, $_ );
1618 $line = uc($line);
1619 $line_ids_indexed{$line}++;
1620 $line_id_has_indices{$line}{$idx}++;
1621 }
1622  
1623 if ( exists( $station->{other_link} ) ) {
1624 for my $other_link ( split( /,/, $station->{other_link} ) ) {
1625 my( $ol, $target ) = split( /:/, $other_link );
1626 $other_link_used{$ol}++;
1627 $station_ids_used{$target}++;
1628 $station_linked_to_stations{$id}{$target} |= 2;
1629 $station_linked_from_stations{$target}{$id} |= 2;
1630 $station_served_by_lines{$id}{$ol} |= 2;
1631 }
1632 }
1633 }
1634  
1635 $map->{_rawinfo} = { line_names => \%line_names,
1636 line_names_uc => \%line_names_uc,
1637 line_ids_defined => \%line_ids_defined,
1638 line_ids_used => \%line_ids_used,
1639 line_ids_indexed => \%line_ids_indexed,
1640 line_id_has_indices => \%line_id_has_indices,
1641 station_names => \%station_names,
1642 station_ids_defined => \%station_ids_defined,
1643 station_ids_used => \%station_ids_used,
1644 station_line_count => \%station_line_count,
1645 other_link_used => \%other_link_used,
1646 station_linked_to_stations => \%station_linked_to_stations,
1647 station_linked_from_stations => \%station_linked_from_stations,
1648 station_served_by_lines => \%station_served_by_lines,
1649 };
1650 return $map;
1651 }
1652  
1653 1;
1654  
1655 __END__
« Map/Tube/Node.pm ↑ Summary Map/Tube.pm »