summaryrefslogtreecommitdiff
path: root/scripts
diff options
context:
space:
mode:
authorDaniel Friesel <derf@finalrewind.org>2014-01-09 23:27:07 +0100
committerDaniel Friesel <derf@finalrewind.org>2014-01-09 23:27:07 +0100
commite09d537040b29ae318d859d84d6ec7036439b0de (patch)
tree6cd19402f7bcdd85ca8e640765d5e7b8d1e01e70 /scripts
parent73f33c43170032b8b278ffd8622faac3253219e3 (diff)
IRIS/Stations: Add documentation
Diffstat (limited to 'scripts')
-rwxr-xr-xscripts/acronyms.pl95
1 files changed, 95 insertions, 0 deletions
diff --git a/scripts/acronyms.pl b/scripts/acronyms.pl
index 9d55b3f..3687f40 100755
--- a/scripts/acronyms.pl
+++ b/scripts/acronyms.pl
@@ -59,4 +59,99 @@ sub get_station_by_name {
}
1;
+
+__END__
+
+=head1 NAME
+
+Travel::Status::DE::IRIS::Stations - Station name to station code mapping
+
+=head1 SYNOPSIS
+
+ use Travel::Status::DE::IRIS::Stations;
+
+ my $name = 'Essen Hbf';
+ my @stations = Travel::Status::DE::IRIS::Stations::get_station_by_name(
+ $name);
+
+ if (@stations < 1) {
+ # no matching stations
+ }
+ elsif (@stations > 1) {
+ # too many matches
+ }
+ else {
+ printf("Input '%s' matched station code %s (as '%s')\n",
+ $name, @{$stations[0]});
+ }
+
+=head1 VERSION
+
+version 0.00
+
+=head1 DESCRIPTION
+
+This module contains a mapping of DeutscheBahn station names to station codes.
+A station name is a (perhaps slightly abbreviated) string naming a particular
+station; a station code is a two to five character denoting a station for the
+IRIS web service.
+
+Example station names (code in parentheses) are:
+"Essen HBf" (EE), "Aachen Schanz" (KASZ), "Do UniversitE<auml>t" (EDUV).
+
+B<Note:> Station codes may contain whitespace.
+
+=head1 METHODS
+
+=over
+
+=item Travel::Status::DE::IRIS::get_stations
+
+Returns a list of [station code, station name] listrefs lexically sorted by
+station name.
+
+=item Travel::Status::DE::IRIS::get_station_by_name(I<$name>)
+
+Returns a list of [station code, station name] listrefs where the station
+name matches I<$name>.
+
+Matching happens in two steps: If a case-insensitive exact match exists, only
+this one is returned. Otherwise, all stations whose name contains I<$name> as
+a substring (also case-insensitive) are returned.
+
+This two-step behaviour makes sure that not prefix-free stations can still be
+matched directly. For instance, both "Essen-Steele" and "Essen-Steele Ost"
+are valid station names, but "essen-steele" will only return "Essen-Steele".
+
+=back
+
+=head1 DIAGNOSTICS
+
+None.
+
+=head1 DEPENDENCIES
+
+=over
+
+=item * List::MoreUtils(3pm)
+
+=back
+
+=head1 BUGS AND LIMITATIONS
+
+There is no support for intelligent whitespaces (to also match "-" and similar)
+yet.
+
+=head1 SEE ALSO
+
+Travel::Status::DE::IRIS(3pm).
+
+=head1 AUTHOR
+
+Copyright (C) 2014 by Daniel Friesel E<lt>derf@finalrewind.orgE<gt>
+
+=head1 LICENSE
+
+This module is licensed under the same terms as Perl itself.
+
EOF