From a6cb8288db8b5976c8598f65ec2c3f5ebde2ac3d Mon Sep 17 00:00:00 2001 From: Daniel Friesel Date: Mon, 17 Oct 2022 22:12:55 +0200 Subject: HAFAS: update documentation --- lib/Travel/Status/DE/HAFAS.pm | 99 +++++++++++++++++++++++++++++-------------- 1 file 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. +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 and returns a new +Requests departures/arrivals/journey as specified by I and returns a new Travel::Status::DE::HAFAS element with the results. Dies if the wrong -I were passed. +I were passed. -Supported I are: +I must contain either a B or a B flag: =over =item B => I -The station or stop to report for, e.g. "Essen HBf" or -"Alfredusbad, Essen (Ruhr)". Mandatory. +Request station board (arrivals or departures) for I, e.g. "Essen HBf" or +"Alfredusbad, Essen (Ruhr)". Results are available via C<< $status->results >>. + +=item B => B<{> B => I [, B => I ] B<}> + +Request details about the journey identified by I and I. +The result is available via C<< $status->result >>. + +=back + +The following optional flags may be set: + +=over + +=item B => I + +Request arrivals (if I is true) rather than departures (if I is +false or B is not specified). Only relevant in station board mode. + +=item B => I + +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 => I -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 => [I, I, ...] @@ -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, I, ... will be excluded. The supported modes depend on B, use B or B to get the supported values. - -Note that this parameter does not work if the B parameter is set. +Only relevant in station board mode. =item B => [I, I, ...] If this option is set, only the modes of transport appearing in I, I, ... will be returned. The supported modes depend on B, use B or B to get the supported values. - -Note that this parameter does not work if the B parameter is set. - -=item B => I - -Set language for additional information. Accepted arguments are Beutsch, -Bnglish, Btalian and B (dutch), depending on the used service. +Only relevant in station board mode. =item B => 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 => B|B - -By default, Travel::Status::DE::HAFAS reports train departures -(B). Set this to B to get arrivals instead. +pass an empty hashref to call the LWP::UserAgent constructor without arguments. =item B => I @@ -795,9 +803,31 @@ Request results from I, defaults to "DB". See B (and C<< hafas-m --list >>) for a list of supported services. -=item B => I +=item B => I -Request results from I, defaults to the one belonging to B. +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, the following mandatory +arguments must be set. + +=over + +=item B => I + +Promises implementation to use for internal promises as well as B return +value. Recommended: Mojo::Promise(3pm). + +=item B => I + +User agent instance to use for asynchronous requests. The object must implement +a B 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 Ederf@finalrewind.orgE +Copyright (C) 2015-2022 by Daniel Friesel Ederf@finalrewind.orgE =head1 LICENSE -- cgit v1.2.3