From e09d537040b29ae318d859d84d6ec7036439b0de Mon Sep 17 00:00:00 2001 From: Daniel Friesel Date: Thu, 9 Jan 2014 23:27:07 +0100 Subject: IRIS/Stations: Add documentation --- scripts/acronyms.pl | 95 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 95 insertions(+) (limited to 'scripts') 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 UniversitEt" (EDUV). + +B 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 Ederf@finalrewind.orgE + +=head1 LICENSE + +This module is licensed under the same terms as Perl itself. + EOF -- cgit v1.2.3