HAFAS: add documentation

}

# }}}

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.