diff options
| -rw-r--r-- | lib/Travel/Status/DE/HAFAS.pm | 99 |
1 files changed, 68 insertions, 31 deletions
diff --git a/lib/Travel/Status/DE/HAFAS.pm b/lib/Travel/Status/DE/HAFAS.pm index bdcaff8..0713876 100644 --- a/lib/Travel/Status/DE/HAFAS.pm +++ b/lib/Travel/Status/DE/HAFAS.pm @@ -727,35 +727,55 @@ version 3.01 =head1 DESCRIPTION Travel::Status::DE::HAFAS is an interface to HAFAS-based -arrival/departure monitors, for instance the one available at -L<http://reiseauskunft.bahn.de/bin/bhftafel.exe/dn>. +arrival/departure monitors using the mgate.exe interface. -It takes a station name and (optional) date and time and reports all arrivals -or departures at that station starting at the specified point in time (now if -unspecified). +It can report departures/arrivals at a specific station, or provide details +about a specific journey. It supports non-blocking operation via promises. =head1 METHODS =over -=item my $status = Travel::Status::DE::HAFAS->new(I<%opts>) +=item my $status = Travel::Status::DE::HAFAS->new(I<%opt>) -Requests the departures/arrivals as specified by I<opts> and returns a new +Requests departures/arrivals/journey as specified by I<opt> and returns a new Travel::Status::DE::HAFAS element with the results. Dies if the wrong -I<opts> were passed. +I<opt> were passed. -Supported I<opts> are: +I<opt> must contain either a B<station> or a B<journey> flag: =over =item B<station> => I<station> -The station or stop to report for, e.g. "Essen HBf" or -"Alfredusbad, Essen (Ruhr)". Mandatory. +Request station board (arrivals or departures) for I<station>, e.g. "Essen HBf" or +"Alfredusbad, Essen (Ruhr)". Results are available via C<< $status->results >>. + +=item B<journey> => B<{> B<id> => I<tripid> [, B<name> => I<line> ] B<}> + +Request details about the journey identified by I<tripid> and I<line>. +The result is available via C<< $status->result >>. + +=back + +The following optional flags may be set: + +=over + +=item B<arrivals> => I<bool> + +Request arrivals (if I<bool> is true) rather than departures (if I<bool> is +false or B<arrivals> is not specified). Only relevant in station board mode. + +=item B<cache> => I<Cache::File object> + +Store HAFAS replies in the provided cache object. This module works with +real-time data, so the object should be configured for an expiry of one to two +minutes. =item B<datetime> => I<DateTime object> -Date and time to report for. Defaults to now. +Date and time to report for. Defaults to now. Only relevant in station board mode. =item B<excluded_mots> => [I<mot1>, I<mot2>, ...] @@ -763,31 +783,19 @@ By default, all modes of transport (trains, trams, buses etc.) are returned. If this option is set, all modes appearing in I<mot1>, I<mot2>, ... will be excluded. The supported modes depend on B<service>, use B<get_services> or B<get_service> to get the supported values. - -Note that this parameter does not work if the B<url> parameter is set. +Only relevant in station board mode. =item B<exclusive_mots> => [I<mot1>, I<mot2>, ...] If this option is set, only the modes of transport appearing in I<mot1>, I<mot2>, ... will be returned. The supported modes depend on B<service>, use B<get_services> or B<get_service> to get the supported values. - -Note that this parameter does not work if the B<url> parameter is set. - -=item B<language> => I<language> - -Set language for additional information. Accepted arguments are B<d>eutsch, -B<e>nglish, B<i>talian and B<n> (dutch), depending on the used service. +Only relevant in station board mode. =item B<lwp_options> => I<\%hashref> Passed on to C<< LWP::UserAgent->new >>. Defaults to C<< { timeout => 10 } >>, -you can use an empty hashref to override it. - -=item B<mode> => B<arr>|B<dep> - -By default, Travel::Status::DE::HAFAS reports train departures -(B<dep>). Set this to B<arr> to get arrivals instead. +pass an empty hashref to call the LWP::UserAgent constructor without arguments. =item B<service> => I<service> @@ -795,9 +803,31 @@ Request results from I<service>, defaults to "DB". See B<get_services> (and C<< hafas-m --list >>) for a list of supported services. -=item B<url> => I<url> +=item B<with_polyline> => I<bool> -Request results from I<url>, defaults to the one belonging to B<service>. +Request a polyline (series of geo-coordinates) indicating the train's route. +Only relevant in journey mode. + +=back + +=item my $status = Travel::Status::DE::HAFAS->new_p(I<%opt>) + +Return a promise that resolves into a Travel::Status::DE::HAFAS instance +($status) on success and rejects with an error message ($status->errstr) on +failure. In addition to the arguments of B<new>, the following mandatory +arguments must be set. + +=over + +=item B<promise> => I<promises module> + +Promises implementation to use for internal promises as well as B<new_p> return +value. Recommended: Mojo::Promise(3pm). + +=item B<user_agent> => I<user agent> + +User agent instance to use for asynchronous requests. The object must implement +a B<post_p> function. Recommended: Mojo::UserAgent(3pm). =back @@ -814,11 +844,18 @@ describing it. If no error occurred, returns undef. =item $status->results Returns a list of arrivals/departures. Each list element is a -Travel::Status::DE::HAFAS::Journey(3pm) object. +Travel::Status::DE::HAFAS::Journey(3pm) object. Unavailable in journey mode. If no matching results were found or the parser / http request failed, returns undef. +=item $status->result + +Returns a single Travel::Status::DE::HAFAS::Journey(3pm) object that describes +the requested journey. Unavailable in station board mode. + +If no result was found or the parser / http request failed, returns undef. + =item $status->similar_stops Returns a list of hashrefs describing stops whose name is similar to the one @@ -880,7 +917,7 @@ Travel::Status::DE::HAFAS::Journey(3pm), Travel::Status::DE::HAFAS::StopFinder(3 =head1 AUTHOR -Copyright (C) 2015-2020 by Daniel Friesel E<lt>derf@finalrewind.orgE<gt> +Copyright (C) 2015-2022 by Daniel Friesel E<lt>derf@finalrewind.orgE<gt> =head1 LICENSE |