DBRIS: Add documentation

sub new {

	my ( $obj, %conf ) = @_;

	my $service = $conf{service};

	my $ua = $conf{user_agent};

# }}}

1;

__END__

=head1 NAME

Travel::Routing::DE::DBRIS - Interface to the bahn.de itinerary service

=head1 SYNOPSIS

	use Travel::Routing::DE::DBRIS;

	# use Travel::Status::DE::DBRIS to obtain $from and $to objects

	# (must be Travel::Status::DE::DBRIS::Location instances)

	my $ris = Travel::Routing::DE::DBRIS->new(

		from => $from_location,

		to => $to_location,

	);

	if (my $err = $ris->errstr) {

		die("Request error: ${err}\n");

	}

	for my $con ( $ris->connections ) {

		for my $seg ($con->segments) {

			if ( not ($seg->is_transfer or $seg->is_walk) ) {

				printf("%s -> %s\n%s ab %s\n%s an %s\n\n",

					$seg->train_mid,

					$seg->direction,

					$seg->dep->strftime('%H:%M'),

					$seg->dep_name,

					$seg->arr->strftime('%H:%M'),

					$seg->arr_name,

				);

			}

		}

		print "\n\n";

	}

=head1 VERSION

version 0.01

=head1 DESCRIPTION

Travel::Routing::DE::DBRIS is an interface to the bahn.de itinerary service.

=head1 METHODS

=over

=item $ris = Travel::Routing::DE::DBRIS->new(I<%opt>)

Request connections as specified by I<%opt> and return a new

Travel::Routing::DE::DBRIS instance with the results. Dies if the wrong I<%opt>

were passed. The B<origin> and B<destination> keys are mandatory.

=over

=item B<origin> => I<stop> (mandatory)

A Travel::Status::DE::DBRIS::Location(3pm) instance describing the origin of

the requested itinerary.

=item B<destination> => I<stop> (mandatory)

A Travel::Status::DE::DBRIS::Location(3pm) instance describing the destination

of the requested itinerary.

=item B<cache> => I<cache>

A Cache::File(3pm) instance used for caching bahn.de requests.

=item B<datetime> => I<datetime>

Request departures on or after I<datetime> (DateTime(3pm) instance).

Default: now.

=item B<language> => I<lang>

Request text components to be provided in I<lang> (ISO 639-1 language code).

Known supported languages are: cs da de en es fr it nl pl.

Default: de.

=item B<modes_of_transit> => I<arrayref>

Only request connections using the modes of transit specified in I<arrayref>.

Default: ICE, EC_IC, IR, REGIONAL, SBAHN, BUS, SCHIFF, UBAHN, TRAM, ANRUFPFLICHTIG.

=item B<discounts> => I<arrayref>

Consider discounts specified in I<arrayref> when determining offer prices.

Supported items: bc25, bs25-first, bc50, bc50-first, bc100, bc100-first.

Default: none.

=item B<user_agent> => I<user agent>

Use I<user agent> for requests.

Default: A new LWP::UserAgent(3pm) object with env_proxy enabled and a timeout

of ten seconds.

=item B<lwp_options> => I<hashref>

Pass I<hashref> to C<< LWP::UserAgent->new >>.

Default: C<< { timeout => 10 } >>.

=back

=item $ris->errstr

Returns a string describing a HTTP or bahn.de error, if any such error occured.

Returns undef otherwise.

=item $ris->connections

Returns a list of Travel::Routing::DE::DBRIS::Connection(3pm) objects, each of

which describes a singre connction from I<origin> to I<destination>.

=back

=head1 DIAGNOSTICS

when the B<developer_mode> argument to B<new> is set to a true value,

Travel::Routing::DE::DBRIS prints raw bahn.de requests and responses to stdout.

None.

=head1 DEPENDENCIES

=over

=item * Class::Accessor(3pm)

=item * DateTime(3pm)

=item * DateTime::Format::Strptime(3pm)

=item * LWP::UserAgent(3pm)

=item * Travel::Status::DE::DBRIS(3pm)

=back

=head1 BUGS AND LIMITATIONS

This module is very much work-in-progress.

=head1 SEE ALSO

Travel::Routing::DE::DBRIS::Connection(3pm)

=head1 AUTHOR

Copyright (C) 2025 by Birte Kristina Friesel E<lt>derf@finalrewind.orgE<gt>

=head1 LICENSE

This module is licensed under the same terms as Perl itself.