| 1 | package Map::Tube::CLI; | ||
| 2 | |||
| 3 | 1 | ▶ | use strict; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 4 | 1 | ▶ | use warnings; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 5 | 1 | ▶ | use version; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 6 | |||
| 7 | our $VERSION = qv('v1.2.0'); | ||
| 8 | our $AUTHORITY = 'cpan:MANWAR'; | ||
| 9 | |||
| 10 | =head1 NAME | ||
| 11 | |||
| 12 | Map::Tube::CLI - Command Line Interface for Map::Tube::* map. | ||
| 13 | |||
| 14 | =head1 VERSION | ||
| 15 | |||
| 16 | Version v1.2.0 | ||
| 17 | |||
| 18 | =cut | ||
| 19 | |||
| 20 | 1 | ▶ | use 5.014; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 21 | 1 | ▶ | use utf8::all; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 22 | 1 | ▶ | use Map::Tube::CLI::Option; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 23 | 0 | ▶ | use Map::Tube::Generic; |
|
Subroutine
BEGIN: called CC=1 SCAR=2.6
| |||
| 24 | use Map::Tube::Exception::FoundUnsupportedMap; | ||
| 25 | use Map::Tube::Exception::InvalidBackgroundColor; | ||
| 26 | use Map::Tube::Exception::InvalidLineName; | ||
| 27 | use Map::Tube::Exception::InvalidStationName; | ||
| 28 | use Map::Tube::Exception::MissingMapName; | ||
| 29 | use Map::Tube::Exception::MissingStationName; | ||
| 30 | use Map::Tube::Exception::MissingSupportedMap; | ||
| 31 | use Map::Tube::Utils qw(is_valid_color); | ||
| 32 | |||
| 33 | use Text::ASCIITable; | ||
| 34 | use Try::Tiny; | ||
| 35 | use Moo; | ||
| 36 | use namespace::autoclean; | ||
| 37 | use MooX::Options; | ||
| 38 | with 'Map::Tube::CLI::Option'; | ||
| 39 | |||
| 40 | =head1 DESCRIPTION | ||
| 41 | |||
| 42 | This module provides a simple command line interface to the package consuming L<Map::Tube>. | ||
| 43 | The distribution also contains a script C<map-tube> for use at the command line which uses this package. | ||
| 44 | |||
| 45 | =head1 SYNOPSIS | ||
| 46 | |||
| 47 | You can list all command line options by giving the C<-h> flag. | ||
| 48 | |||
| 49 | $ map-tube -h | ||
| 50 | USAGE: map-tube [-h] [options...] | ||
| 51 | |||
| 52 | -m --map=String Map name | ||
| 53 | -s --start=String Start station name | ||
| 54 | -e --end=String End station name | ||
| 55 | -p --preferred Show preferred route | ||
| 56 | -g --generate_map Generate map as image | ||
| 57 | -i --image=String Name of image file or format (optional; default | ||
| 58 | format: PNG) | ||
| 59 | --layout=String Layout strategy for image (default: dot) | ||
| 60 | -b --bgcolor=String Map background color | ||
| 61 | -l --line=String Line name to map | ||
| 62 | --line_mappings Generate line mappings as table | ||
| 63 | --line_notes Generate line notes | ||
| 64 | -M --list_maps List supported maps | ||
| 65 | -L --list_lines List lines in given map | ||
| 66 | -S --list_stations List stations in given map | ||
| 67 | -F --fuzzy Fuzzy station name matching (on by default if | ||
| 68 | needed; switch off with --no-fuzzy) | ||
| 69 | -P --penalty=Real Change hop count penalty for line changes (default: 0.5) | ||
| 70 | -t --tabular Show routes and notes in tabular format | ||
| 71 | -f --force Obsolete. Does nothing. Kept for compatibility only. | ||
| 72 | -D --debug Run in debug mode | ||
| 73 | -V --version Show version information | ||
| 74 | |||
| 75 | --usage show a short help message | ||
| 76 | -h show a compact help message | ||
| 77 | --help show a long help message | ||
| 78 | --man show the manual | ||
| 79 | |||
| 80 | =head1 COMMON USAGES | ||
| 81 | |||
| 82 | =head2 Finding the Shortest Route | ||
| 83 | |||
| 84 | =head3 Shortest Route | ||
| 85 | |||
| 86 | You can ask for the shortest route in the London Tube Map as below: (Under Windows use double quotes.) | ||
| 87 | |||
| 88 | $ map-tube --map London --start 'Baker Street' --end 'Wembley Park' | ||
| 89 | |||
| 90 | Baker Street (Bakerloo, Circle, Hammersmith & City, Jubilee, Metropolitan), Finchley Road (Jubilee, Metropolitan), Wembley Park (Jubilee, Metropolitan) | ||
| 91 | |||
| 92 | If any of the station names does not exist literally (up to capitalisation), | ||
| 93 | fuzzy matching will be attempted. If this yields unique stations, they will be | ||
| 94 | used. Otherwise, the candidate stations are displayed and no route will be | ||
| 95 | calculated. You can always force fuzzy matching by adding the "--fuzzy" | ||
| 96 | command line argument. | ||
| 97 | |||
| 98 | =head3 Preferred Shortest Route | ||
| 99 | |||
| 100 | Now a request for the preferred route: | ||
| 101 | |||
| 102 | $ map-tube --map London --start 'Baker Street' --end 'Euston Square' --preferred | ||
| 103 | |||
| 104 | Baker Street (Circle, Hammersmith & City, Metropolitan), Great Portland Street (Circle, Hammersmith & City, Metropolitan), Euston Square (Circle, Hammersmith & City, Metropolitan) | ||
| 105 | |||
| 106 | =head3 Preferred Shortest Route in Tabular Form | ||
| 107 | |||
| 108 | And a request for the preferred route displayed as a table: (This also shows the use of short options.) | ||
| 109 | |||
| 110 | $ map-tube -m London -s 'Baker Street' -e 'Euston Square' -p -t | ||
| 111 | Metro Map London: Route from Baker Street to Euston Square. | ||
| 112 | |||
| 113 | .--------------------------------------------------------------------. | ||
| 114 | | Station Name | Lines | | ||
| 115 | +-----------------------+--------------------------------------------+ | ||
| 116 | | Baker Street | Circle, Hammersmith and City, Metropolitan | | ||
| 117 | | Great Portland Street | Circle, Hammersmith and City, Metropolitan | | ||
| 118 | | Euston Square | Circle, Hammersmith and City, Metropolitan | | ||
| 119 | '-----------------------+--------------------------------------------' | ||
| 120 | |||
| 121 | Baker Street (Circle, Hammersmith & City, Metropolitan), Great Portland Street (Circle, Hammersmith & City, Metropolitan), Euston Square (Circle, Hammersmith & City, Metropolitan) | ||
| 122 | |||
| 123 | =head3 Handling of Tube Line Changes | ||
| 124 | |||
| 125 | Counting the number of hops is one valid way to measure the distance between two stations. | ||
| 126 | Practically speaking, however, having to change lines will add to the perceived distance. | ||
| 127 | To account for this, Map::Tube puts a penalty of one half hop on each line change required, | ||
| 128 | i.e., routes with fewer line changes are slightly more welcome. You can either switch off | ||
| 129 | this behaviour by | ||
| 130 | |||
| 131 | $ map-tube -m London -s 'Baker Street' -e 'Euston Square' --penalty 0 | ||
| 132 | |||
| 133 | or put an even heavier penalty on line changes: | ||
| 134 | |||
| 135 | $ map-tube -m London -s 'Baker Street' -e 'Euston Square' --penalty 2 | ||
| 136 | |||
| 137 | (In this particular case, the output will be identical because there are no line changes involved.) | ||
| 138 | |||
| 139 | =head3 Station Names | ||
| 140 | |||
| 141 | Ideally you will know the exact names of the stations, like in the | ||
| 142 | examples above. If you don't, you can always get a full list of station | ||
| 143 | names with the C<--list-stations> argument (cf. below). But Map::Tube | ||
| 144 | tries to help you if it cannot find the exact station name (case never | ||
| 145 | matters anyway). In this case, it will try to find a similar name. | ||
| 146 | (What exactly is meant by "similar" is a bit involved; never mind.) If | ||
| 147 | it finds a unique candidate, it will use that and notify you that it did | ||
| 148 | some guessing: | ||
| 149 | |||
| 150 | $ map-tube -m London -s Baker -e 'Euston Square' | ||
| 151 | Metro Map London: Route from Baker Street (guessed) to Euston Square. | ||
| 152 | |||
| 153 | .--------------------------------------------------------------------. | ||
| 154 | | Station Name | Lines | | ||
| 155 | +-----------------------+--------------------------------------------+ | ||
| 156 | | Baker Street | Circle, Hammersmith and City, Metropolitan | | ||
| 157 | | Great Portland Street | Circle, Hammersmith and City, Metropolitan | | ||
| 158 | | Euston Square | Circle, Hammersmith and City, Metropolitan | | ||
| 159 | '-----------------------+--------------------------------------------' | ||
| 160 | |||
| 161 | If no clear best guess can be found, you will be offered with some possibilities: | ||
| 162 | |||
| 163 | $ map-tube -m London -s "Back Street" -e 'Euston Square' | ||
| 164 | Map::Tube::CLI::run(): ERROR: Invalid Station Name [Back Street]; maybe one of Baker Street | ||
| 165 | (Bakerloo, Circle, Hammersmith and City, Jubilee, Metropolitan), Becontree (District), | ||
| 166 | Bond Street (Central, Elizabeth, Jubilee), Old Street (Northern), Wood Street (Weaver)? | ||
| 167 | (status: 101) file C:/Strawberry/perl/site/lib/Map/Tube/CLI.pm on line 454 | ||
| 168 | |||
| 169 | You can also use regular expressions: | ||
| 170 | |||
| 171 | $ map-tube -m London -s "Bak.*St.*" -e 'Euston Square' | ||
| 172 | Metro Map London: Route from Baker Street (guessed) to Euston Square. | ||
| 173 | |||
| 174 | .--------------------------------------------------------------------. | ||
| 175 | | Station Name | Lines | | ||
| 176 | +-----------------------+--------------------------------------------+ | ||
| 177 | | Baker Street | Circle, Hammersmith and City, Metropolitan | | ||
| 178 | | Great Portland Street | Circle, Hammersmith and City, Metropolitan | | ||
| 179 | | Euston Square | Circle, Hammersmith and City, Metropolitan | | ||
| 180 | '-----------------------+--------------------------------------------' | ||
| 181 | |||
| 182 | If you can always force fuzzy matching with the argument C<--fuzzy>, or you can | ||
| 183 | completely disable it with C<--no-fuzzy>. | ||
| 184 | |||
| 185 | |||
| 186 | =head2 Images of Maps | ||
| 187 | |||
| 188 | =head3 Generate an Image of the Full Map | ||
| 189 | |||
| 190 | To generate a graphical representation of the entire map, follow the command | ||
| 191 | below. This will generate a PNG file named after the map in your current working | ||
| 192 | directory. (It will silently overwrite any pre-existing file of the same name.) | ||
| 193 | |||
| 194 | $ map-tube --map Delhi --generate_map | ||
| 195 | |||
| 196 | In case you want a different background color to the map then you can try this: | ||
| 197 | |||
| 198 | $ map-tube --map Delhi --bgcolor gray --generate_map | ||
| 199 | |||
| 200 | The output file name is chosen automatically according to the map. It will be displayed | ||
| 201 | on the console. If you want a different file name, do this: | ||
| 202 | |||
| 203 | $ map-tube --map Delhi --generate_map --image Delhicious.png | ||
| 204 | |||
| 205 | This allows you also to pick other output formats than PNG. E.g., you might | ||
| 206 | want a vector graphics file: | ||
| 207 | |||
| 208 | $ map-tube --map Delhi --generate_map --image Delhivector.svg | ||
| 209 | |||
| 210 | Or if you are happy with the default file name but still want to have a non-standard format: | ||
| 211 | |||
| 212 | $ map-tube --map Delhi --generate_map --image pdf | ||
| 213 | |||
| 214 | Which output formats you can choose depends on your particular GraphViz | ||
| 215 | installation, so check the GraphViz documentation. | ||
| 216 | |||
| 217 | There is a number of different approaches to the layout of such | ||
| 218 | diagrams, and GraphViz offers several (again, consult the GraphvIz | ||
| 219 | documentation). The default is C<dot>, but often C<neato> or C<sfdp> | ||
| 220 | also offer good representations. Which one is "best" is a matter of | ||
| 221 | taste and also depends on the map at hand. Try this: | ||
| 222 | |||
| 223 | $ map-tube --map Delhi --generate_map --layout neato | ||
| 224 | |||
| 225 | =head3 Generate Just a Line Map | ||
| 226 | |||
| 227 | To generate a graphical representation of just a particular line, follow | ||
| 228 | the command below. This will generate a PNG file named after the line in your | ||
| 229 | current working directory. (It will silently overwrite any pre-existing file | ||
| 230 | of the same name.) | ||
| 231 | |||
| 232 | $ map-tube --map London --line Bakerloo --generate_map | ||
| 233 | |||
| 234 | In case you want a different background color to the map then you can try this: | ||
| 235 | |||
| 236 | $ map-tube --map London --line DLR --bgcolor yellow --generate_map | ||
| 237 | |||
| 238 | =head2 Additional Information on Lines, Stations, and Maps | ||
| 239 | |||
| 240 | =head3 Generate Line Mappings as a Table | ||
| 241 | |||
| 242 | This will show all stops on the given lane, as far as possible in the correct order: | ||
| 243 | |||
| 244 | $ map-tube --map London --line Bakerloo --line_mappings | ||
| 245 | |||
| 246 | All that has been said above about output file names, image formats and layout algorithms | ||
| 247 | applies also to line maps. | ||
| 248 | |||
| 249 | =head3 Generate Line Notes | ||
| 250 | |||
| 251 | This will show which other lines are serving the stations on the given line. | ||
| 252 | Stations are ordered alphabetically. Only stations that are served by at least | ||
| 253 | one additional line are shown. | ||
| 254 | |||
| 255 | $ map-tube --map London --line Bakerloo --line_notes | ||
| 256 | |||
| 257 | It can also be displayed in tabular form: | ||
| 258 | |||
| 259 | $ map-tube --map London --line Bakerloo --line_notes --tabular | ||
| 260 | |||
| 261 | =head3 List the Lines for the Given Map | ||
| 262 | |||
| 263 | $ map-tube --map London --list_lines | ||
| 264 | |||
| 265 | =head3 List the Stations for the Given Map | ||
| 266 | |||
| 267 | $ map-tube --map London --list_stations | ||
| 268 | |||
| 269 | =head3 List all Supported Maps | ||
| 270 | |||
| 271 | This will show you a list of all tube maps installed on your computer. Faulty | ||
| 272 | maps that cannot be loaded will not be displayed. | ||
| 273 | |||
| 274 | $ map-tube --list_maps | ||
| 275 | |||
| 276 | Note that many more maps may be available on CPAN for you to download and use. | ||
| 277 | See also the documentation of the current version of Map::Tube on CPAN. | ||
| 278 | You could also use L<Task::Map::Tube::Bundle> to install many of the maps. | ||
| 279 | Please make sure you have the latest maps when you install. | ||
| 280 | |||
| 281 | =head2 Error Handling | ||
| 282 | |||
| 283 | If encountering an invalid map or a missing map (i.e., not installed), you get an error | ||
| 284 | message like below, if you do not have the tube map of Kazan installed; if you do have it, | ||
| 285 | it will instead notify you that the starting station does not exist in this map: | ||
| 286 | |||
| 287 | $ map-tube --map Kazan --start 'Baker Street' --end 'Euston Square' | ||
| 288 | ERROR: Missing Map [Kazan]. | ||
| 289 | |||
| 290 | =cut | ||
| 291 | |||
| 292 | # Load a map class on demand. Returns true on success. On failure it warns | ||
| 293 | # (like Module::Pluggable's require option used to) and returns false. | ||
| 294 | sub _load_map_class { | ||
| 295 | my ($class) = @_; | ||
| 296 | |||
| 297 | (my $file = "$class.pm") =~ s{::}{/}g; | ||
| 298 | return 1 if eval { require $file; 1 }; | ||
| 299 | |||
| 300 | my $error = $@ || 'unknown error'; | ||
| 301 | $error =~ s/\s+\z//; | ||
| 302 | warn "Couldn't require $class : $error\n"; | ||
| 303 | return 0; | ||
| 304 | } | ||
| 305 | |||
| 306 | sub BUILD { | ||
| 307 | my ($self) = @_; | ||
| 308 | |||
| 309 | my @caller = caller(0); | ||
| 310 | @caller = caller(2) if $caller[3] eq '(eval)'; | ||
| 311 | |||
| 312 | my $map_name = $self->{map}; | ||
| 313 | my $map_uc_name = uc($map_name//''); | ||
| 314 | # if ($map_uc_name) { | ||
| 315 | # # Load only the requested map (if it is supported and installed) | ||
| 316 | # # rather than every installed map. | ||
| 317 | # my $class = supported_maps()->{uc($map_uc_name)}; | ||
| 318 | # if (defined $class) { | ||
| 319 | # my %installed = map { $_ => 1 } plugins; | ||
| 320 | # if ($installed{$class} && _load_map_class($class)) { | ||
| 321 | # $self->{maps}->{$map_uc_name} = $class->new; | ||
| 322 | # } | ||
| 323 | # } | ||
| 324 | # } | ||
| 325 | try { | ||
| 326 | $self->{maps}->{$map_uc_name} = Map::Tube::Generic->new(location=>$map_name) if $map_name; | ||
| 327 | } | ||
| 328 | catch { | ||
| 329 | # Could not load map. Either we didn't find it, or we found it but it doesn't load. | ||
| 330 | Map::Tube::Exception::MissingSupportedMap->throw({ | ||
| 331 | method => __PACKAGE__."::BUILD", | ||
| 332 | message => "ERROR: Missing Map [$map_name].", | ||
| 333 | filename => $caller[1], | ||
| 334 | line_number => $caller[2] }); | ||
| 335 | }; | ||
| 336 | |||
| 337 | $self->_validate_param; | ||
| 338 | |||
| 339 | } | ||
| 340 | |||
| 341 | =head1 METHODS | ||
| 342 | |||
| 343 | =head2 run() | ||
| 344 | |||
| 345 | This is the main method provided by the package L<Map::Tube::CLI>. It does not | ||
| 346 | expect any parameter. Here is the code from the supplied C<map-tube> script. | ||
| 347 | |||
| 348 | use strict; use warnings; | ||
| 349 | use Map::Tube::CLI; | ||
| 350 | |||
| 351 | Map::Tube::CLI->new_with_options->run; | ||
| 352 | |||
| 353 | =cut | ||
| 354 | |||
| 355 | sub run { | ||
| 356 | my ($self) = @_; | ||
| 357 | |||
| 358 | my $map_obj = $self->map ? $self->{maps}->{uc($self->map)} : undef; | ||
| 359 | |||
| 360 | # Handle these options first because map name may not be present and is not needed: | ||
| 361 | if ($self->version) { | ||
| 362 | print _prepare_version_info($map_obj, $self->map), "\n"; | ||
| 363 | return; | ||
| 364 | } | ||
| 365 | if ($self->list_maps) { | ||
| 366 | my $map_list = _prepare_map_list(); | ||
| 367 | print "Locally Available Metro Maps\n\n"; | ||
| 368 | if ($self->tabular) { | ||
| 369 | my $map_table = Text::ASCIITable->new; | ||
| 370 | $map_table->setCols('Map Name','Description'); | ||
| 371 | $map_table->addRow(@$_) for @$map_list; | ||
| 372 | no warnings; | ||
| 373 | print $map_table; | ||
| 374 | } else { | ||
| 375 | no warnings; | ||
| 376 | print join(', ', @$_), "\n" for @$map_list; | ||
| 377 | } | ||
| 378 | print "(More maps may be available for downlaod and installation on CPAN.)\n"; | ||
| 379 | return; | ||
| 380 | } | ||
| 381 | if (defined $self->penalty) { | ||
| 382 | if ($map_obj->can('line_change_penalty')) { | ||
| 383 | $map_obj->line_change_penalty($self->penalty) | ||
| 384 | } else { | ||
| 385 | warn "Your Map::Tube does not support line change penalties. Please upgrade.\n"; | ||
| 386 | } | ||
| 387 | } | ||
| 388 | |||
| 389 | if ($self->generate_map) { | ||
| 390 | $map_obj->bgcolor($self->bgcolor) if defined $self->bgcolor; | ||
| 391 | my %graph_args = ( line_name=>$self->line, output_file=>undef ); | ||
| 392 | if ($self->image) { | ||
| 393 | my %img_formats = map { lc($_) => 1 } $map_obj->list_formats(); | ||
| 394 | if ( exists $img_formats{lc($self->image)} ) { | ||
| 395 | $graph_args{format} = lc($self->image); | ||
| 396 | } | ||
| 397 | else { | ||
| 398 | $graph_args{output_file} = $self->image; | ||
| 399 | if ( $self->image =~ /.([^.]+)$/ && exists $img_formats{lc($1)} ) { | ||
| 400 | $graph_args{format} = lc($1); | ||
| 401 | } | ||
| 402 | } | ||
| 403 | } | ||
| 404 | $graph_args{driver} = $self->layout if $self->layout; | ||
| 405 | if ($map_obj->can('render')) { | ||
| 406 | my (undef, $fname) = $map_obj->render(%graph_args); | ||
| 407 | print "Image written to $fname\n" if $fname; | ||
| 408 | } | ||
| 409 | else { | ||
| 410 | warn "You do not seem to have Map::Tube::Plugin::Graph installed.\n"; | ||
| 411 | } | ||
| 412 | } | ||
| 413 | elsif ($self->line_mappings) { | ||
| 414 | printf("\n=head1 DESCRIPTION\n\n%s Metro Map: %s Line.\n\n", $self->map, $self->line) unless $self->tabular; | ||
| 415 | print _prepare_line_mappings($map_obj, $self->line); | ||
| 416 | } | ||
| 417 | elsif ($self->line_notes) { | ||
| 418 | printf "\n=head1 NOTE\n\n=over 2\n" unless $self->tabular; | ||
| 419 | print $self->_prepare_line_notes($map_obj); | ||
| 420 | print "\n=back\n" unless $self->tabular; | ||
| 421 | } | ||
| 422 | elsif ($self->list_lines) { | ||
| 423 | print join(",\n", sort @{$map_obj->get_lines}), "\n"; | ||
| 424 | } | ||
| 425 | elsif ($self->list_stations) { | ||
| 426 | my $station_list_table = _prepare_station_list($map_obj); | ||
| 427 | printf("Metro Map %s: Stations.\n\n", $self->map); | ||
| 428 | print $station_list_table; | ||
| 429 | } | ||
| 430 | else { | ||
| 431 | my $route = $map_obj->get_shortest_route($self->start, $self->end); | ||
| 432 | $route = $route->preferred if $self->preferred; | ||
| 433 | if ($self->tabular) { | ||
| 434 | my $route_table = Text::ASCIITable->new; | ||
| 435 | $route_table->setCols('Station Name','Lines'); | ||
| 436 | $route_table->alignCol('Lines','left'); | ||
| 437 | for my $station(@{$route->nodes()}) { | ||
| 438 | $route_table->addRow($station->name, join(', ', @{ $station->line })); | ||
| 439 | } | ||
| 440 | printf("Metro Map %s: Route from %s%s to %s%s.\n\n", $self->map, | ||
| 441 | $self->start, $self->{start_remark}//'', $self->end, $self->{end_remark}//''); | ||
| 442 | print $route_table; | ||
| 443 | } else { | ||
| 444 | no warnings; | ||
| 445 | print $route, "\n"; | ||
| 446 | } | ||
| 447 | if ($self->debug) { | ||
| 448 | print "\n---------DEBUG-----------\n"; | ||
| 449 | foreach my $id (sort keys %{$map_obj->{tables}}) { | ||
| 450 | print "$map_obj->{tables}->{$id}\n"; | ||
| 451 | } | ||
| 452 | print "-------------------------\n"; | ||
| 453 | } | ||
| 454 | print "$@\n" if $@; | ||
| 455 | } | ||
| 456 | } | ||
| 457 | |||
| 458 | |||
| 459 | =head2 supported_maps() | ||
| 460 | |||
| 461 | This method will produce information on the maps that are installed and can be loaded. | ||
| 462 | (More tube maps may be available at CPAN; cf. also the documentaion of Map::Tube.) | ||
| 463 | It does not expect any parameter. It will return a reference to a hash whose keys are plain | ||
| 464 | text city names (in ALL-CAPS) and whose values are the names of the modules that | ||
| 465 | implement the maps. | ||
| 466 | |||
| 467 | =cut | ||
| 468 | |||
| 469 | sub supported_maps { | ||
| 470 | my $maps_found = Map::Tube::Generic::list_maps( ); | ||
| 471 | my %existing_maps = map { uc($maps_found->{$_}->{location}) => $_ } keys %$maps_found; | ||
| 472 | return \%existing_maps; | ||
| 473 | } | ||
| 474 | |||
| 475 | # | ||
| 476 | # | ||
| 477 | # PRIVATE METHODS | ||
| 478 | |||
| 479 | sub _prepare_line_mappings { | ||
| 480 | my ($map, $line_name) = @_; | ||
| 481 | |||
| 482 | my $map_table = Text::ASCIITable->new; | ||
| 483 | $map_table->setCols('Station Name','Connected To'); | ||
| 484 | |||
| 485 | foreach my $station (map { $_->name } @{ $map->get_stations($line_name) }) { | ||
| 486 | $map_table->addRow($station, join(", ", @{$map->get_linked_stations($station, $line_name)})); | ||
| 487 | } | ||
| 488 | |||
| 489 | return $map_table; | ||
| 490 | } | ||
| 491 | |||
| 492 | sub _prepare_line_notes { | ||
| 493 | my ($self, $map) = @_; | ||
| 494 | my $map_name = $self->map; | ||
| 495 | my $line_name = $self->line; | ||
| 496 | |||
| 497 | my $line_name_uc = uc($line_name); | ||
| 498 | my $line_package = { map { $_->{name} => 1 } | ||
| 499 | grep { $line_name_uc ne uc($_->name) && scalar(@{$_->get_stations}) } | ||
| 500 | @{$map->get_lines} | ||
| 501 | }; | ||
| 502 | |||
| 503 | my $notes = $self->tabular ? Text::ASCIITable->new : ""; | ||
| 504 | $notes->setCols("Line $line_name Station",'is also served by line(s)') if $self->tabular; | ||
| 505 | |||
| 506 | my @stations = map { $_->name } @{ $map->get_stations($line_name) }; | ||
| 507 | if ( eval { require Unicode::Collate; 1 } ) { | ||
| 508 | my $collator = Unicode::Collate->new(level => 1); | ||
| 509 | @stations = $collator->sort(@stations); | ||
| 510 | } else { | ||
| 511 | @stations = sort { lc($a) cmp lc($b) } @stations; | ||
| 512 | } | ||
| 513 | |||
| 514 | foreach my $station (@stations) { | ||
| 515 | my @lines = grep { $_ ne $line_name && exists $line_package->{$_} } map { $_->name } @{ $map->get_node_by_name($station)->line }; | ||
| 516 | next unless @lines; | ||
| 517 | if ($self->tabular) { | ||
| 518 | $notes->addRow($station, join(", ", @lines)); | ||
| 519 | } | ||
| 520 | else { | ||
| 521 | my $delim = ' '; | ||
| 522 | foreach my $line (@lines) { | ||
| 523 | $notes .= sprintf("\n=item * The station \"%s\" is also part of\n", $station) if $delim eq ' '; | ||
| 524 | $notes .= sprintf(" %s L<%s Line|Map::Tube::%s::Line::%s>\n", | ||
| 525 | $delim, $line, $map_name, _guess_package_name($line)); | ||
| 526 | $delim = '|'; | ||
| 527 | } | ||
| 528 | } | ||
| 529 | } | ||
| 530 | |||
| 531 | return $notes; | ||
| 532 | } | ||
| 533 | |||
| 534 | sub _prepare_version_info { | ||
| 535 | my ($map, $map_name) = @_; | ||
| 536 | my $msg = "Map::Tube::CLI version $VERSION, Map::Tube version: $Map::Tube::VERSION"; | ||
| 537 | if ($map_name) { | ||
| 538 | my $supported_maps = supported_maps(); | ||
| 539 | my $map_module_name = $supported_maps->{uc($map_name)} // ( 'Map::Tube::' . $map_name ); | ||
| 540 | my $version_ref = $map_module_name . '::VERSION'; | ||
| 541 | my $map_desc = $map ? $map->name() // $map_name : ''; | ||
| 542 | my $map_version; | ||
| 543 | { | ||
| 544 | no strict; | ||
| 545 | $map_version = ${$version_ref} // 'unknown'; | ||
| 546 | } | ||
| 547 | $msg .= ", map $map_name: $map_desc version: $map_version"; | ||
| 548 | } | ||
| 549 | return $msg; | ||
| 550 | } | ||
| 551 | |||
| 552 | sub _prepare_map_list { | ||
| 553 | return [ map { [ $_->{location}, $_->{name} ] } | ||
| 554 | sort { uc($a->{location}) cmp uc($b->{location}) } | ||
| 555 | values %{ Map::Tube::Generic->list_maps( verify => 1 ) } | ||
| 556 | ] ; | ||
| 557 | } | ||
| 558 | |||
| 559 | sub _prepare_station_list { | ||
| 560 | my ($map) = @_; | ||
| 561 | |||
| 562 | my $station_table = Text::ASCIITable->new; | ||
| 563 | $station_table->setCols('Station Name','Served by lines'); | ||
| 564 | $station_table->alignCol('Served by lines','left'); | ||
| 565 | |||
| 566 | my @stations = @{ $map->get_stations() }; | ||
| 567 | |||
| 568 | if ( eval { require Unicode::Collate; 1 } ) { | ||
| 569 | my $collator = Unicode::Collate->new(level => 1); | ||
| 570 | @stations = $collator->sort(@stations); | ||
| 571 | } else { | ||
| 572 | @stations = sort { lc($a) cmp lc($b) } @stations; | ||
| 573 | } | ||
| 574 | |||
| 575 | foreach my $station (@stations) { | ||
| 576 | $station_table->addRow( $station->name, join(', ', @{ $station->line })); | ||
| 577 | } | ||
| 578 | |||
| 579 | return $station_table; | ||
| 580 | } | ||
| 581 | |||
| 582 | sub _guess_package_name { | ||
| 583 | my ($name) = @_; | ||
| 584 | |||
| 585 | my $_name; | ||
| 586 | foreach my $token (split /\s/,$name) { | ||
| 587 | next if ($token =~ /\&/); | ||
| 588 | $_name .= ucfirst(lc($token)); | ||
| 589 | } | ||
| 590 | |||
| 591 | return $_name; | ||
| 592 | } | ||
| 593 | |||
| 594 | sub _identify_station { | ||
| 595 | my ($self, $station) = @_; | ||
| 596 | my @caller = caller(1); | ||
| 597 | @caller = caller(3) if $caller[3] eq '(eval)'; | ||
| 598 | my $map_obj = $self->{maps}->{uc($self->map)}; | ||
| 599 | my $remark = ''; | ||
| 600 | my $station_node; | ||
| 601 | try { | ||
| 602 | $station_node = $map_obj->get_node_by_name($station) unless $self->fuzzy; | ||
| 603 | } catch { | ||
| 604 | }; | ||
| 605 | if (!defined $station_node) { | ||
| 606 | if ((!defined $self->fuzzy || $self->fuzzy) && $map_obj->can('fuzzy_find')) { | ||
| 607 | # Try fuzzy matching. | ||
| 608 | # Different strategies depending on whether we have a common regex meta character ( '.', '?', '*', '+', '[' ). | ||
| 609 | my @fuzzy_methods; | ||
| 610 | push( @fuzzy_methods, 'start', 'in' ) unless $station =~ /[?*+\[]/; | ||
| 611 | push( @fuzzy_methods, 'regex' ) if $station =~ /^[^?*].*[.?*+\[]/; | ||
| 612 | push( @fuzzy_methods, 'levenshtein', 'doublemetaphone', 'ngrams' ) unless $station =~/[?*+\[]/; | ||
| 613 | my @stations; | ||
| 614 | for my $method (@fuzzy_methods) { | ||
| 615 | @stations = $map_obj->fuzzy_find(search=>$station, objects=>'stations', method=>$method); | ||
| 616 | last if @stations; | ||
| 617 | } | ||
| 618 | if (@stations == 1) { | ||
| 619 | $station = $stations[0]->name(); | ||
| 620 | $remark = ' (guessed)'; | ||
| 621 | } | ||
| 622 | elsif (@stations == 0) { | ||
| 623 | Map::Tube::Exception::InvalidStationName->throw({ | ||
| 624 | method => __PACKAGE__."::run", | ||
| 625 | message => ( $self->fuzzy | ||
| 626 | ? "ERROR: No Fuzzy Match for Station Name [$station]." | ||
| 627 | : "ERROR: Invalid Station Name [$station]." | ||
| 628 | ), | ||
| 629 | filename => $caller[1], | ||
| 630 | line_number => $caller[2] }); | ||
| 631 | } | ||
| 632 | else { | ||
| 633 | @stations = ( ( map { $_ ->name() } @stations[0..9] ), '...' ) if @stations > 10; | ||
| 634 | Map::Tube::Exception::InvalidStationName->throw({ | ||
| 635 | method => __PACKAGE__."::run", | ||
| 636 | message => ( $self->fuzzy | ||
| 637 | ? ( "ERROR: Station Not Identified; maybe one of " . join(', ', @stations ) . "?" ) | ||
| 638 | : ( "ERROR: Invalid Station Name [$station]; maybe one of " . join(', ', @stations ) . "?" ) | ||
| 639 | ), | ||
| 640 | filename => $caller[1], | ||
| 641 | line_number => $caller[2] }); | ||
| 642 | } | ||
| 643 | } | ||
| 644 | else { | ||
| 645 | warn "You do not seem to have Map::Tube::Plugin::FuzzyFind installed, " . | ||
| 646 | "so you must enter station names correctly.\n" unless $map_obj->can('fuzzy_find'); | ||
| 647 | Map::Tube::Exception::InvalidStationName->throw({ | ||
| 648 | method => __PACKAGE__."::run", | ||
| 649 | message => "ERROR: Invalid Station Name [$station].", | ||
| 650 | filename => $caller[1], | ||
| 651 | line_number => $caller[2] }); | ||
| 652 | } | ||
| 653 | } | ||
| 654 | |||
| 655 | return ( $station, $remark ); | ||
| 656 | } | ||
| 657 | |||
| 658 | sub _validate_param { | ||
| 659 | my ($self) = @_; | ||
| 660 | |||
| 661 | my @caller = caller(0); | ||
| 662 | @caller = caller(2) if $caller[3] eq '(eval)'; | ||
| 663 | |||
| 664 | my $start = $self->start; | ||
| 665 | my $end = $self->end; | ||
| 666 | my $map = $self->map; | ||
| 667 | my $line = $self->line; | ||
| 668 | my $bgcolor = $self->bgcolor; | ||
| 669 | |||
| 670 | return if $self->version || $self->list_maps; | ||
| 671 | |||
| 672 | Map::Tube::Exception::MissingMapName->throw({ | ||
| 673 | method => __PACKAGE__."::_validate_param", | ||
| 674 | message => "ERROR: Missing Map Name.", | ||
| 675 | filename => $caller[1], | ||
| 676 | line_number => $caller[2] }) | ||
| 677 | unless (defined $map); | ||
| 678 | |||
| 679 | if ($self->generate_map) { | ||
| 680 | if (defined $bgcolor && !(is_valid_color($bgcolor))) { | ||
| 681 | Map::Tube::Exception::InvalidBackgroundColor->throw({ | ||
| 682 | method => __PACKAGE__."::_validate_param", | ||
| 683 | message => "ERROR: Invalid background Color [$bgcolor].", | ||
| 684 | filename => $caller[1], | ||
| 685 | line_number => $caller[2] }); | ||
| 686 | } | ||
| 687 | |||
| 688 | if (defined $line) { | ||
| 689 | Map::Tube::Exception::InvalidLineName->throw({ | ||
| 690 | method => __PACKAGE__."::_validate_param", | ||
| 691 | message => "ERROR: Invalid Line Name [$line].", | ||
| 692 | filename => $caller[1], | ||
| 693 | line_number => $caller[2] }) | ||
| 694 | unless defined $self->{maps}->{uc($map)}->get_line_by_name($line); | ||
| 695 | } | ||
| 696 | } | ||
| 697 | |||
| 698 | if ($self->line_mappings || $self->line_notes) { | ||
| 699 | |||
| 700 | Map::Tube::Exception::InvalidLineName->throw({ | ||
| 701 | method => __PACKAGE__."::_validate_param", | ||
| 702 | message => "ERROR: Invalid Line Name [$line].", | ||
| 703 | filename => $caller[1], | ||
| 704 | line_number => $caller[2] }) | ||
| 705 | unless defined $self->{maps}->{uc($map)}->get_line_by_name($line); | ||
| 706 | } | ||
| 707 | |||
| 708 | unless ( $self->generate_map | ||
| 709 | || $self->line_mappings | ||
| 710 | || $self->line_notes | ||
| 711 | || $self->list_lines | ||
| 712 | || $self->list_stations) { | ||
| 713 | |||
| 714 | warn "--line option will be ignored" if defined $line; # --line option has been used for no good | ||
| 715 | |||
| 716 | Map::Tube::Exception::MissingStationName->throw({ | ||
| 717 | method => __PACKAGE__."::_validate_param", | ||
| 718 | message => "ERROR: Missing Station Name [start].", | ||
| 719 | filename => $caller[1], | ||
| 720 | line_number => $caller[2] }) | ||
| 721 | unless defined $start; | ||
| 722 | ($self->{start}, $self->{start_remark}) = $self->_identify_station($start); | ||
| 723 | |||
| 724 | Map::Tube::Exception::MissingStationName->throw({ | ||
| 725 | method => __PACKAGE__."::_validate_param", | ||
| 726 | message => "ERROR: Missing Station Name [end].", | ||
| 727 | filename => $caller[1], | ||
| 728 | line_number => $caller[2] }) | ||
| 729 | unless defined $end; | ||
| 730 | ($self->{end}, $self->{end_remark}) = $self->_identify_station($end); | ||
| 731 | |||
| 732 | } | ||
| 733 | |||
| 734 | } | ||
| 735 | |||
| 736 | =head1 AUTHOR | ||
| 737 | |||
| 738 | Mohammad Sajid Anwar, C<< <mohammad.anwar at yahoo.com> >> | ||
| 739 | |||
| 740 | =head1 CONTRIBUTORS | ||
| 741 | |||
| 742 | Gisbert W. Selke, C<< <gws at cpan.org> >> | ||
| 743 | |||
| 744 | =head1 REPOSITORY | ||
| 745 | |||
| 746 | L<https://github.com/manwar/Map-Tube-CLI> | ||
| 747 | |||
| 748 | =head1 BUGS | ||
| 749 | |||
| 750 | Please report any bugs or feature requests through the web interface at L<https://github.com/manwar/Map-Tube-CLI/issues>. | ||
| 751 | I will be notified and then you'll automatically be notified of progress on your bug as I make changes. | ||
| 752 | |||
| 753 | =head1 SUPPORT | ||
| 754 | |||
| 755 | You can find documentation for this module with the perldoc command. | ||
| 756 | |||
| 757 | perldoc Map::Tube::CLI | ||
| 758 | |||
| 759 | You can also look for information at: | ||
| 760 | |||
| 761 | =over 4 | ||
| 762 | |||
| 763 | =item * BUG Report | ||
| 764 | |||
| 765 | L<https://github.com/manwar/Map-Tube-CLI/issues> | ||
| 766 | |||
| 767 | =item * Search MetaCPAN | ||
| 768 | |||
| 769 | L<http://metacpan.org/dist/Map-Tube-CLI/> | ||
| 770 | |||
| 771 | =back | ||
| 772 | |||
| 773 | =head1 LICENSE AND COPYRIGHT | ||
| 774 | |||
| 775 | Copyright (C) 2015 - 2026 Mohammad Sajid Anwar. | ||
| 776 | |||
| 777 | This program is free software; you can redistribute it and / or modify it under | ||
| 778 | the terms of the the Artistic License (2.0). You may obtain a copy of the full | ||
| 779 | license at: | ||
| 780 | |||
| 781 | L<http://www.perlfoundation.org/artistic_license_2_0> | ||
| 782 | |||
| 783 | Any use, modification, and distribution of the Standard or Modified Versions is | ||
| 784 | governed by this Artistic License.By using, modifying or distributing the Package, | ||
| 785 | you accept this license. Do not use, modify, or distribute the Package, if you do | ||
| 786 | not accept this license. | ||
| 787 | |||
| 788 | If your Modified Version has been derived from a Modified Version made by someone | ||
| 789 | other than you,you are nevertheless required to ensure that your Modified Version | ||
| 790 | complies with the requirements of this license. | ||
| 791 | |||
| 792 | This license does not grant you the right to use any trademark, service mark, | ||
| 793 | tradename, or logo of the Copyright Holder. | ||
| 794 | |||
| 795 | This license includes the non-exclusive, worldwide, free-of-charge patent license | ||
| 796 | to make, have made, use, offer to sell, sell, import and otherwise transfer the | ||
| 797 | Package with respect to any patent claims licensable by the Copyright Holder that | ||
| 798 | are necessarily infringed by the Package. If you institute patent litigation | ||
| 799 | (including a cross-claim or counterclaim) against any party alleging that the | ||
| 800 | Package constitutes direct or contributory patent infringement,then this Artistic | ||
| 801 | License to you shall terminate on the date that such litigation is filed. | ||
| 802 | |||
| 803 | Disclaimer of Warranty: THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER AND | ||
| 804 | CONTRIBUTORS "AS IS' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES. THE IMPLIED | ||
| 805 | WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR | ||
| 806 | NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT PERMITTED BY YOUR LOCAL LAW. UNLESS | ||
| 807 | REQUIRED BY LAW, NO COPYRIGHT HOLDER OR CONTRIBUTOR WILL BE LIABLE FOR ANY DIRECT, | ||
| 808 | INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING IN ANY WAY OUT OF THE USE | ||
| 809 | OF THE PACKAGE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. | ||
| 810 | |||
| 811 | =cut | ||
| 812 | |||
| 813 | 1; # End of Map::Tube::CLI | ||