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.0');
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
76 trim filter
77 to_perl is_same
78 common_lines get_method_map
79 is_valid_color
80 name name_to_id
81 plugins _active_link
82 _other_links _line_stations
83 _line_station_index _common_lines
84 nodes lines
85 tables routes
86 _lines bgcolor
87 as_graph _get_line_object_by_name
88 )
89 ],
90 );
91
92 with 'Map::Tube';
93
94
95 # Private data member:
96 # Known non-map classes in the Map::Tube namespace. We exclude these quickly.
97 my %_exclude = map { $_ => 1 } qw( API CLI Cookbook Exception Generic Graph GraphViz
98 Line Node Pluggable Route Table Types Utils );
99 # Class or object method:
100 sub list_maps {
101 my( $class, %args ) = @_;
102 $args{namespace} //= [ 'Map::Tube' ];
103 $args{namespace} = [ $args{namespace} ] unless ref( $args{namespace} );
104 my( @namespaces, $name, $namepattern, $verify );
105 @namespaces = map { [ split( /::/, $_ ) ] } @{ $args{namespace} };
106 $name = uc( $args{name} ) if defined( $args{name} );
107 $namepattern = $args{pattern} if defined( $args{pattern} ) && !defined($name);
108 $verify = $args{verify} if defined( $args{verify} );
109 my %files;
110 #
111 # TODO: handle case-sensitive filesystems more efficiently (assuming correct spelling)
112 # TODO: on case-sensitive filesystems, first try to find case-sensitive matching, only then
113 # fall back to case-insensitive matching.
114 # TODO: handle not only module name but also namespaces in case-insensitive manner.
115 #
116 for my $dir(@INC) {
117 my $mydir = $dir;
118 for my $ns(@namespaces) {
119 # We go through some hoops here in order to get proper results both
120 # on case-sensitive and on case-insensitive file systems, while
121 # Perl's module names are always case-sensitive.
122 my @nsparts = @$ns;
123 my $ok = 1;
124 while (@nsparts) {
125 my $p = shift(@nsparts);
126 my $dh;
127 if ( !opendir( $dh, $mydir ) ) {
128 $ok = 0;
129 last;
130 }
131 my($d) = grep { $_ eq $p } readdir($dh);
132 closedir($dh);
133 if ( !defined($d) ) {
134 $ok = 0;
135 last;
136 }
137 $mydir = File::Spec->catdir( $mydir, $d );
138 }
139 next unless $ok;
140
141 my $pattern = File::Spec->catfile( $mydir, '*.pm' );
142 for my $f ( glob($pattern) ) {
143 my( undef, undef, $fname ) = File::Spec->splitpath($f);
144 $fname =~ s/\.pm$//;
145 next if exists( $_exclude{$fname} );
146 next if defined($name) && ( uc($fname) ne $name );
147 next if defined($namepattern) && ( $fname !~ $namepattern );
148 my $modname = join( '::', @$ns, $fname );
149 my $mapname;
150 if ( $verify ) {
151 $mapname = _loadable($modname);
152 next unless defined $mapname;
153 }
154
155 $files{$modname} = { filepath => $f, location => $fname };
156 $files{$modname}{name} = $mapname if defined($mapname);
157 }
158 }
159 }
160
161 return \%files;
162 }
163
164 # #######################################################################
165 #
166 # Private methods
167 #
168 # #######################################################################
169
170
171 sub _builder_map {
172 # Find the concrete map module and instantiate it.
173 # Argument:
174 # The name of a Map::Tube module containing map data
175 # This may be a fully qualified module name (properly written, respecting case)
176 # (e.g., 'Map::Tube::London'), or a "location" (e.g., 'London'). For the latter
177 # case does not matter.
178 # Returns an instance of the specified map.
179 # Croaks if the Map::Tube module cannot be found or cannot be instantiated.
180
181 my( $self, $args ) = @_;
182
183 my $modname = $self->location( );
184 if ( $modname !~ /::/ ) {
185 my $candidates = $self->list_maps( name => $modname, namespace => $self->namespace( ) );
186 croak "Cannot find Map::Tube class '$modname' in namespace(s) @{ $self->namespace( ) }" unless keys %{ $candidates };
187 ($modname) = sort keys %{ $candidates };
188 }
189 eval "require $modname;";
190 croak($@) if $@;
191
192 my $map = eval "$modname->new( \$args )";
193 croak "Cannot instantiate $modname" unless $map;
194
195 $self->_set_location($1) if $modname =~ /.*::(.*)$/;
196
197 return $map;
198 }
199
200
201 sub BUILD {
202 # Final check on arguments, and storing the map instance for future use.
203 # No return value.
204 # Carps or croaks if the argument check finds problems.
205
206 my( $self, $args ) = @_;
207
208 if ( exists($args->{location}) && exists($args->{map}) ) {
209 carp 'Both location and map specified -- ignoring location';
210 } elsif ( !exists($args->{location}) && !exists($args->{map}) ) {
211 croak 'Either location or map need to be specified';
212 }
213
214 if ($self->map( ) ) {
215 # If the map argument has been specified, the Map::Tube instance
216 # is already where it should be. We'll just backfill our location attribute
217 # as a nicety, using the "base name" of the class of the map module.
218 my $classname = ref( $self->map( ) );
219 $classname =~ s/__WITH__.*$//;
220 $classname =~ s/^.*:://;
221 $self->_set_location($classname);
222 } else {
223 # We cannot rely on the built-in Moo lazy builder mechanism
224 # because that will not have been executed by the time the Map::Tube role
225 # BUILD will be executed. So we need to do it here in time.
226 $self->_set_map( $self->_builder_map($args) );
227 }
228
229 for my $plugin (Map::Tube::Pluggable::plugins()) {
230 # Only bother applying the approved plugins.
231 next unless (exists $Map::Tube::PLUGINS->{$plugin});
232 Role::Tiny->apply_roles_to_object($self, $plugin);
233 }
234 return;
235 }
236
237 # my %own_methods = map { $_ => 1 } qw( list_maps location map namespace );
238 around can => sub {
239 # Make the "can" method cleverer to make sure that the underlying concrete Map::Tube
240 # module, to which almost everything is delegated, "can".
241 my( $orig, $self, @args ) = @_;
242 if ( ref($self) && $self->map( ) ) {
243 return if ( $args[0] eq 'xml' && $self->map( )->xml() eq '' );
244 return if ( $args[0] eq 'json' && $self->map( )->json() eq '' );
245 }
246 return $self->$orig(@args) if $self->$orig(@args);
247 return $self->map( )->can(@args) if ref($self) && $self->map( );
248 return;
249 };
250
251
252 sub _loadable {
253 # Helper function: takes a fully qualified module name and checks whether
254 # it can be instantiated and does the Map::Tube role. Returns undef if not,
255 # and otherwise the internal name of the map (if it exists) or the module name itself.
256 my($modname) = @_;
257 eval "require $modname;";
258 return if $@;
259
260 # Map::Tube object.
261 my $map = eval "$modname->new( )";
262 return unless $map;
263
264 return unless $map->does( 'Map::Tube' );
265
266 return $map->name( ) // $modname;
267 }
268
269 1;
270
271 __END__
↑ Summary