diff options
Diffstat (limited to 'lib')
| -rw-r--r-- | lib/Travel/Routing/DE/HAFAS.pm | 215 |
1 files changed, 215 insertions, 0 deletions
diff --git a/lib/Travel/Routing/DE/HAFAS.pm b/lib/Travel/Routing/DE/HAFAS.pm index 6203223..8d3e416 100644 --- a/lib/Travel/Routing/DE/HAFAS.pm +++ b/lib/Travel/Routing/DE/HAFAS.pm @@ -621,3 +621,218 @@ sub get_active_service { } # }}} + +1; + +__END__ + +=head1 NAME + +Travel::Routing::DE::HAFAS - Interface to HAFAS itinerary services + +=head1 SYNOPSIS + + use Travel::Routing::DE::HAFAS; + + my $hafas = Travel::Routing::DE::HAFAS->new( + from_stop => 'Eichlinghofen H-Bahn, Dortmund', + to_stop => 'Gangelplatz, Düsseldorf', + ); + + if (my $err = $hafas->errstr) { + die("Request error: ${err}\n"); + } + + for my $con ( $hafas->connections ) { + for my $sec ($con->sections) { + if ( $sec->type eq 'JNY' ) { + printf("%s → %s\n%s ab %s\n%s an %s\n\n", + $sec->name, $sec->direction, + $sec->dep_datetime->strftime('%H:%M'), + $sec->dep_loc->name, + $sec->arr_datetime->strftime('%H:%M'), + $sec->arr_loc->name, + ); + } + } + print "\n\n"; + } + +=head1 VERSION + +version 0.01 + +=head1 DESCRIPTION + +Travel::Routing::DE::HAFAS is an interface to HAFAS itinerary services +using the mgate.exe interface. It works best with the legacy instance of +Deutsche Bahn, but supports other transit services as well. + +=head1 METHODS + +=over + +=item $hafas = Travel::Routing::DE::HAFAS->new(I<%opt>) + +Request connections as specified by I<%opt> and return a new +Travel::Routing::DE::HAFAS instance with the results. Dies if the wrong +I<%opt> were passed. I<%opt> must contain B<from_stop> and B<to_stop> and +supports the following additional flags: + +=over + +=item B<from_stop> => I<stop> (mandatory) + +Origin stop, e.g. "Essen HBf" or "Alfredusbad, Essen (Ruhr)". The stop +must be specified either by name or by EVA ID (e.g. 8000080 for Dortmund Hbf). + +=item B<to_stop> => I<stop> (mandatory) + +Destination stop, e.g. "Essen HBf" or "Alfredusbad, Essen (Ruhr)". The stop +must be specified either by name or by EVA ID (e.g. 8000080 for Dortmund Hbf). + +=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> (station) + +Date and time for itinerary request. Defaults to now. + +=item B<excluded_mots> => [I<mot1>, I<mot2>, ...] (geoSearch, station) + +By default, all modes of transport (trains, trams, buses etc.) are considered. +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. + +=item B<exclusive_mots> => [I<mot1>, I<mot2>, ...] (geoSearch, station) + +If this option is set, only the modes of transport appearing in I<mot1>, +I<mot2>, ... will be considered. The supported modes depend on B<service>, +use B<get_services> or B<get_service> to get the supported values. + +=item B<language> => I<language> + +Request text messages to be provided in I<language>. Supported languages depend +on B<service>, use B<get_services> or B<get_service> to get the supported +values. Providing an unsupported or invalid value may lead to garbage output. + +=item B<lwp_options> => I<\%hashref> + +Passed on to C<< LWP::UserAgent->new >>. Defaults to C<< { timeout => 10 } >>, +pass an empty hashref to call the LWP::UserAgent constructor without arguments. + +=item B<service> => I<service> + +Request results from I<service>, defaults to "DB". +See B<get_services> (and C<< hafas-m --list >>) for a list of supported +services. + +=back + +=item $hafas_p = Travel::Routing::DE::HAFAS->new_p(I<%opt>) + +Return a promise that resolves into a Travel::Routing::DE::HAFAS instance +($hafas) on success and rejects with an error message on failure. If the +failure occured after receiving a response from the HAFAS backend, the rejected +promise contains a Travel::Routing::DE::HAFAS instance as a second argument. +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 + +=item $hafas->errcode + +In case of an error in the HAFAS backend, returns the corresponding error code +as string. If no backend error occurred, returns undef. + +=item $hafas->errstr + +In case of an error in the HTTP request or HAFAS backend, returns a string +describing it. If no error occurred, returns undef. + +=item $hafas->connections + +Returns a list of Travel::Routing::DE::HAFAS::Connection(3pm) objects, each of +which describes a single connection from I<origin> to I<destination>. + +Returns a false value if no connections were found or the parser / http request +failed. + +=item $hafas->messages + +Returns a list of Travel::Status::DE::HAFAS::Message(3pm) objects with service +messages. Each message belongs to at least one connection, connection section, +or stop along a section's journey. + +=item $hafas->get_active_service + +Returns a hashref describing the active service when a service is active and +nothing otherwise. The hashref contains the keys B<url> (URL to the station +board service), and B<productbits> (arrayref describing the supported modes of +transport, may contain duplicates). + +=item Travel::Routing::DE::HAFAS::get_services() + +Returns an array containing all supported HAFAS services. Each element is a +hashref and contains all keys mentioned in B<get_active_service>. +It also contains a B<shortname> key, which is the service name used by +the constructor's B<service> parameter. + +=item Travel::Routing::DE::HAFAS::get_service(I<$service>) + +Returns a hashref describing the service I<$service>. Returns nothing if +I<$service> is not supported. See B<get_active_service> for the hashref layout. + +=back + +=head1 DIAGNOSTICS + +None. + +=head1 DEPENDENCIES + +=over + +=item * Class::Accessor(3pm) + +=item * DateTime(3pm) + +=item * DateTime::Format::Strptime(3pm) + +=item * LWP::UserAgent(3pm) + +=item * Travel::Status::DE::HAFAS::Message(3pm) + +=back + +=head1 BUGS AND LIMITATIONS + +The non-default services (anything other than DB) are not well tested. + +=head1 SEE ALSO + +Travel::Routing::DE::HAFAS::Connection(3pm) + +=head1 AUTHOR + +Copyright (C) 2023 by Birte Kristina Friesel E<lt>derf@finalrewind.orgE<gt> + +=head1 LICENSE + +This module is licensed under the same terms as Perl itself. |