blib/lib/Map/Tube/Generic.pm

filter: Statementstmt 93.7% 30 / 32 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub 100% 11 / 11 Podpod n/a totaltotal 95.3% 41 / 43 CC 1 SCAR 0.3
CC
1
Cov
94%
BEGIN
1.3
BEGIN
1.0
BEGIN
1.0
CRAP 1.0
↑ Summary
1 # -*- perl -*-
2 #
3 # Author: Gisbert W. Selke, TapirSoft Selke & Selke GbR.
4 #
5 # Copyright (C) 2025--2026 Gisbert W. Selke. All rights reserved.
6 # This package is free software; you can redistribute it and/or
7 # modify it under the same terms as Perl itself.
8 #
9 # Mail: gws@cpan.org
10 #
11 package Map::Tube::Generic;
12 3 ▶use 5.14.0;
Subroutine BEGIN: called CC=1 SCAR=0.0
13 3 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
14 3 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
15 3 ▶use utf8;
Subroutine BEGIN: called CC=1 SCAR=0.0
16 3 ▶use version 0.77 ( );
Subroutine BEGIN: called CC=1 SCAR=0.0
17
18 our $VERSION = version->declare('v0.2.2');
19
20 =encoding utf8
21
22 =head1 NAME
23
24 Map::Tube::Generic - Interface to a map specified at runtime.
25
26 =cut
27
28 3 ▶use Carp;
Subroutine BEGIN: called CC=1 SCAR=0.0
29 3 ▶use File::Spec;
Subroutine BEGIN: called CC=1 SCAR=0.0
30 3 ▶use Moo;
Subroutine BEGIN: called CC=1 SCAR=0.0
31 3 ▶use namespace::clean;
Subroutine BEGIN: called CC=1 SCAR=0.0
32 3 ▶use Map::Tube::Pluggable;
Subroutine BEGIN: called CC=1 SCAR=0.0
33 0 ▶use Map::Tube;
Subroutine BEGIN: called CC=1 SCAR=2.6
34
35 has location => ( is => 'rwp',
36 isa => sub { carp( "$_[0] is not a string" ) if ref($_[0]) },
37 coerce => sub {
38 my($arg) = @_;
39 $arg = $arg->( ) while ref($arg) eq 'CODE';
40 $arg = "$arg" unless ( ref($_[0]) eq 'HASH' ) || ( ref($_[0]) eq 'ARRAY' );
41 return $arg;
42 },
43 );
44 has namespace => ( is => 'rwp',
45 default => sub { return [ 'Map::Tube' ] },
46 isa => sub { carp( "$_ is not a string" ) for grep { ref($_) } @{ $_[0] } },
47 coerce => sub {
48 my($arg) = @_;
49 $arg = $arg->( ) while ref($arg) eq 'CODE';
50 return ( ref($arg) eq 'ARRAY' ) ? $arg : [ $arg ];
51 },
52 );
53 has map => ( is => 'rwp',
54 isa => sub { carp( "$_[0] does not do the Map::Tube role" ) unless $_[0]->DOES('Map::Tube') },
55 handles => [
56 # These are methods provided either directly by the Map::Tube::xxx class
57 # or by the Map::Tube role.
58 # We cannot just delegate to the Map::Tube::xxx class (because we
59 # do not know it yet) or to the Map::Tube role (because that creates
60 # an infinite recursion for some built-in methods).
61 # This construction is, of course, brittle.
62 # We could fix it by using Moose instead of Moo and using the
63 # meta protocol, but we don't want the big Moose in our living-room.
64 # Instead, it should be checked during module installation
65 # that we are still complete. (That has limited dynamics
66 # but is better than nothing).
67 # Using Module::PrintUsed or Class:Inspector? Or Class::MOP?
68 qw(
69 xml json
70 get_shortest_route get_all_routes
71 get_node_by_id get_node_by_name
72 get_line_by_id get_line_by_name
73 get_lines get_stations
74 get_next_stations get_linked_stations
75 get_map_data line_change_penalty
76 nodes lines
77 tables routes
78 trim filter
79 to_perl is_same
80 common_lines get_method_map
81 is_valid_color
82 name name_to_id
83 plugins _active_link
84 _other_links _link_lines
85 _line_stations _line_station_index
86 _common_lines
87 _lines bgcolor
88 _xml_data _decode_utf8_if_needed
89 _init_map _is_directly_linked
90 _init_table _load_plugins
91 _get_common_lines _capture_common_lines
92 _get_next_link _set_active_links
93 _set_routes _validate_map_structure
94 _get_path _capture_line_station
95 _set_path _validate_multi_lined_nodes
96 _get_length _set_length
97 _get_current_lines _set_current_lines
98 _get_table _get_node_id
99 _order_station_lines _get_line_object_by_name
100 _is_visited _get_line_object_by_id
101 )
102 ],
103 );
104
105 with 'Map::Tube';
106
107
108 # Private data member:
109 # Known non-map classes in the Map::Tube namespace. We exclude these quickly.
110 my %_exclude = map { $_ => 1 } qw( API CLI Cookbook Exception Generic Graph GraphViz
111 Line Node Pluggable Route Table Types Utils );
112 # Class or object method:
113 sub list_maps {
114 my( $class, %args ) = @_;
115 $args{namespace} //= [ 'Map::Tube' ];
116 $args{namespace} = [ $args{namespace} ] unless ref( $args{namespace} );
117 my( @namespaces, $name, $namepattern, $verify );
118 @namespaces = map { [ split( /::/, $_ ) ] } @{ $args{namespace} };
119 $name = uc( $args{name} ) if defined( $args{name} );
120 $namepattern = $args{pattern} if defined( $args{pattern} ) && !defined($name);
121 $verify = $args{verify} if defined( $args{verify} );
122 my %files;
123 #
124 # TODO: handle case-sensitive filesystems more efficiently (assuming correct spelling)
125 # TODO: on case-sensitive filesystems, first try to find case-sensitive matching, only then
126 # fall back to case-insensitive matching.
127 # TODO: handle not only module name but also namespaces in case-insensitive manner.
128 #
129 for my $dir(@INC) {
130 my $mydir = $dir;
131 for my $ns(@namespaces) {
132 # We go through some hoops here in order to get proper results both
133 # on case-sensitive and on case-insensitive file systems, while
134 # Perl's module names are always case-sensitive.
135 my @nsparts = @$ns;
136 my $ok = 1;
137 while (@nsparts) {
138 my $p = shift(@nsparts);
139 my $dh;
140 if ( !opendir( $dh, $mydir ) ) {
141 $ok = 0;
142 last;
143 }
144 my($d) = grep { $_ eq $p } readdir($dh);
145 closedir($dh);
146 if ( !defined($d) ) {
147 $ok = 0;
148 last;
149 }
150 $mydir = File::Spec->catdir( $mydir, $d );
151 }
152 next unless $ok;
153
154 my $pattern = File::Spec->catfile( $mydir, '*.pm' );
155 for my $f ( glob($pattern) ) {
156 my( undef, undef, $fname ) = File::Spec->splitpath($f);
157 $fname =~ s/\.pm$//;
158 next if exists( $_exclude{$fname} );
159 next if defined($name) && ( uc($fname) ne $name );
160 next if defined($namepattern) && ( $fname !~ $namepattern );
161 my $modname = join( '::', @$ns, $fname );
162 my $mapname;
163 if ( $verify ) {
164 $mapname = _loadable($modname);
165 next unless defined $mapname;
166 }
167
168 $files{$modname} = { filepath => $f, location => $fname };
169 $files{$modname}{name} = $mapname if defined($mapname);
170 }
171 }
172 }
173
174 return \%files;
175 }
176
177 # #######################################################################
178 #
179 # Private methods
180 #
181 # #######################################################################
182
183
184 sub _builder_map {
185 # Find the concrete map module and instantiate it.
186 # Argument:
187 # The name of a Map::Tube module containing map data
188 # This may be a fully qualified module name (properly written, respecting case)
189 # (e.g., 'Map::Tube::London'), or a "location" (e.g., 'London'). For the latter
190 # case does not matter.
191 # Returns an instance of the specified map.
192 # Croaks if the Map::Tube module cannot be found or cannot be instantiated.
193
194 my( $self, $args ) = @_;
195
196 my $modname = $self->location( );
197 if ( $modname !~ /::/ ) {
198 my $candidates = $self->list_maps( name => $modname, namespace => $self->namespace( ) );
199 croak "Cannot find Map::Tube class '$modname' in namespace(s) @{ $self->namespace( ) }" unless keys %{ $candidates };
200 ($modname) = sort keys %{ $candidates };
201 }
202 eval "require $modname;";
203 croak($@) if $@;
204
205 my $map = eval "$modname->new( \$args )";
206 croak "Cannot instantiate $modname" unless $map;
207
208 $self->_set_location($1) if $modname =~ /.*::(.*)$/;
209
210 return $map;
211 }
212
213
214 sub BUILD {
215 # Final check on arguments, and storing the map instance for future use.
216 # No return value.
217 # Carps or croaks if the argument check finds problems.
218
219 my( $self, $args ) = @_;
220
221 if ( exists($args->{location}) && exists($args->{map}) ) {
222 carp 'Both location and map specified -- ignoring location';
223 } elsif ( !exists($args->{location}) && !exists($args->{map}) ) {
224 croak 'Either location or map need to be specified';
225 }
226
227 if ($self->map( ) ) {
228 # If the map argument has been specified, the Map::Tube instance
229 # is already where it should be. We'll just backfill our location attribute
230 # as a nicety, using the "base name" of the class of the map module.
231 my $classname = ref( $self->map( ) );
232 $classname =~ s/__WITH__.*$//;
233 $classname =~ s/^.*:://;
234 $self->_set_location($classname);
235 } else {
236 # We cannot rely on the built-in Moo lazy builder mechanism
237 # because that will not have been executed by the time the Map::Tube role
238 # BUILD will be executed. So we need to do it here in time.
239 $self->_set_map( $self->_builder_map($args) );
240 }
241
242 for my $plugin (Map::Tube::Pluggable::plugins()) {
243 # Only bother applying the approved plugins.
244 next unless (exists $Map::Tube::PLUGINS->{$plugin});
245 Role::Tiny->apply_roles_to_object($self, $plugin);
246 }
247 return;
248 }
249
250 # my %own_methods = map { $_ => 1 } qw( list_maps location map namespace );
251 around can => sub {
252 # Make the "can" method cleverer to make sure that the underlying concrete Map::Tube
253 # module, to which almost everything is delegated, "can".
254 my( $orig, $self, @args ) = @_;
255 if ( ref($self) && $self->map( ) ) {
256 return if ( $args[0] eq 'xml' && ( !$self->map( )->can('xml') || $self->map( )->xml() eq '' ) );
257 return if ( $args[0] eq 'json' && ( !$self->map( )->can('json') || $self->map( )->json() eq '' ) );
258 }
259 return $self->$orig(@args) if $self->$orig(@args);
260 return $self->map( )->can(@args) if ref($self) && $self->map( );
261 return;
262 };
263
264
265 sub _loadable {
266 # Helper function: takes a fully qualified module name and checks whether
267 # it can be instantiated and does the Map::Tube role. Returns undef if not,
268 # and otherwise the internal name of the map (if it exists) or the module name itself.
269 my($modname) = @_;
270 eval "require $modname;";
271 return if $@;
272
273 # Map::Tube object.
274 my $map = eval "$modname->new( )";
275 return unless $map;
276
277 return unless $map->does( 'Map::Tube' );
278
279 return $map->name( ) // $modname;
280 }
281
282 1;
283
284 __END__
↑ Summary