HAFAS: add documentation

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.