| 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__ | ||