| 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.1'); | ||
| 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( )->xml() eq '' ); | ||
| 257 | return if ( $args[0] eq '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__ | ||