diff options
| -rwxr-xr-x | bin/dbris-m | 121 | ||||
| -rw-r--r-- | lib/Travel/Status/DE/DBRIS.pm | 171 |
2 files changed, 291 insertions, 1 deletions
diff --git a/bin/dbris-m b/bin/dbris-m index 26def34..d4de7e7 100755 --- a/bin/dbris-m +++ b/bin/dbris-m @@ -40,7 +40,7 @@ GetOptions( if ($use_cache) { my $cache_path = ( $ENV{XDG_CACHE_HOME} // "$ENV{HOME}/.cache" ) - . '/Travel-Status-DE-HAFAS'; + . '/Travel-Status-DE-DBRIS'; eval { require Cache::File; $cache = Cache::File->new( @@ -190,3 +190,122 @@ elsif ( $opt{locationSearch} ) { } } } + +__END__ + +=head1 NAME + +dbris-m - Interface to bahn.de / bahnhof.de RIS::*-based departure monitors + +=head1 SYNOPSIS + +B<dbris-m> I<station> + +B<dbris-m> B<?>I<query>|I<lat>B<:>I<lon> + +=head1 VERSION + +version 0.01 + +=head1 DESCRIPTION + +dbris-m is an interface to the public transport services operated by +Deutsche Bahn on bahn.de and bahnhof.de. + +It can serve as an arrival/departure monitor, request details about a specific +trip/journey, and look up public transport stops by name or geolocation. +The operating mode depends on the contents of its non-option argument. + +=head2 Departure Monitor (I<station>) + +Show departures at I<station>. I<station> may be given as a station name or +station ID. For each departure, B<dbris-m> shows + +=over + +=item * estimated departure time, + +=item * delay, if known, + +=item * trip name, number, or line, + +=item * direction / destination, and + +=item * platform, if known. + +=back + +=head2 Location Search (B<?>I<query>|I<lat>B<:>I<lon>) + +List stations that match I<query> or that are located in the vicinity of +I<lat>B<:>I<lon> geocoordinates with station ID and name. + +=head1 OPTIONS + +Values in brackets indicate options that only apply to the corresponding +operating mode(s). + +=over + +=item B<--json> + +Print result(s) as JSON and exit. This is a dump of internal data structures +and not guaranteed to remain stable between minor versions. Please use the +Travel::Status::DE::DBRIS(3pm) module if you need a proper API. + +=item B<--no-cache> + +If the Cache::File module is available, server replies are cached in +F<~/.cache/Travel-Status-DE-DBRIS> (or a path relative to C<$XDG_CACHE_HOME>, +if set) for 90 seconds. Use this option to disable caching. You can also use +B<--cache> to re-enable it. + +=item B<--raw-json> + +Print unprocessed API response as JSON and exit. +Useful for debugging and development purposes. + +=item B<-V>, B<--version> + +Show version information and exit. + +=back + +=head1 EXIT STATUS + +0 upon success, 1 upon internal error, 2 upon backend error. + +=head1 CONFIGURATION + +None. + +=head1 DEPENDENCIES + +=over + +=item * Class::Accessor(3pm) + +=item * DateTime(3pm) + +=item * LWP::UserAgent(3pm) + +=back + +=head1 BUGS AND LIMITATIONS + +=over + +=item * This module is very much work-in-progress + +=item * At the moment, there is no way of getting journey IDs from the +departure monitor, and thus no way to get departure details. + +=back + +=head1 AUTHOR + +Copyright (C) 2024 by Birte Kristina Friesel E<lt>derf@finalrewind.orgE<gt> + +=head1 LICENSE + +This program is licensed under the same terms as Perl itself. diff --git a/lib/Travel/Status/DE/DBRIS.pm b/lib/Travel/Status/DE/DBRIS.pm index d9dc0d5..4deba94 100644 --- a/lib/Travel/Status/DE/DBRIS.pm +++ b/lib/Travel/Status/DE/DBRIS.pm @@ -289,3 +289,174 @@ sub result { # }}} 1; + +__END__ + +=head1 NAME + +Travel::Status::DE::DBRIS - Interface to bahn.de / bahnhof.de departure monitors + +=head1 SYNOPSIS + +Blocking variant: + + use Travel::Status::DE::DBRIS; + + my $status = Travel::Status::DE::DBRIS->new(station => 8000098); + for my $r ($status->results) { + printf( + "%s +%-3d %10s -> %s\n", + $r->dep->strftime('%H:%M'), + $r->delay, + $r->line, + $r->dest_name + ); + } + +Non-blocking variant; + + use Mojo::Promise; + use Mojo::UserAgent; + use Travel::Status::DE::DBRIS; + + Travel::Status::DE::DBRIS->new_p( + station => 8000098, + promise => 'Mojo::Promise', + user_agent => Mojo::UserAgent->new + )->then(sub { + my ($status) = @_; + for my $r ($status->results) { + printf( + "%s +%-3d %10s -> %s\n", + $r->dep->strftime('%H:%M'), + $r->delay, + $r->line, + $r->dest_name + ); + } + })->wait; + +=head1 VERSION + +version 0.01 + +=head1 DESCRIPTION + +Travel::Status::DE::DBRIS is an unofficial interface to bahn.de and bahnhof.de +APIs. + +=head1 METHODS + +=over + +=item my $status = Travel::Status::DE::DBRIS->new(I<%opt>) + +Requests item(s) as specified by I<opt> and returns a new +Travel::Status::DE::DBRIS element with the results. Dies if the wrong +I<opt> were passed. + +I<opt> must contain either a B<station>, B<geoSearch>, or B<locationSearch> flag: + +=over + +=item B<station> => I<station> + +Request station board (departures) for I<station>, e.g. 8000080 for Dortmund +Hbf. Results are available via C<< $status->results >>. + +=item B<geoSearch> => B<{> B<latitude> => I<latitude>, B<longitude> => I<longitude> B<}> + +Search for stations near I<latitude>, I<longitude>. +Results are available via C<< $status->results >>. + +=item B<locationSearch> => I<query> + +Search for stations whose name is equal or similar to I<query>. Results are +available via C<< $status->results >> and include the station ID needed for +station board requests. + +=back + +The following optional flags may be set. +Values in brackets indicate flags that are only relevant in certain request +modes, e.g. geoSearch or station. + +=over + +=item B<cache> => I<$obj> + +A Cache::File(3pm) object used to cache realtime data requests. It should be +configured for an expiry of one to two minutes. + +=item B<lwp_options> => I<\%hashref> + +Passed on to C<< LWP::UserAgent->new >>. Defaults to C<< { timeout => 10 } >>, +you can use an empty hashref to unset the default. + +=back + +=item my $promise = Travel::Status::DE::DBRIS->new_p(I<%opt>) + +Return a promise yielding a Travel::Status::DE::DBRIS instance (C<< $status >>) +on success, or an error message (same as C<< $status->errstr >>) on failure. + +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 support +promises (i.e., it must implement a C<< get_p >> function). Recommended: +Mojo::UserAgent(3pm). + +=back + +=item $status->errstr + +In case of a fatal HTTP request or backend error, returns a string describing +it. Returns undef otherwise. + +=item $status->results + +Returns a list of Travel::Status::DE::DBRIS::Location(3pm) or Travel::Status::DE::DBRIS::Journey(3pm) objects, depending on the arguments passed to B<new>. + +=back + +=head1 DIAGNOSTICS + +None. + +=head1 DEPENDENCIES + +=over + +=item * DateTime(3pm) + +=item * List::Util(3pm) + +=item * LWP::UserAgent(3pm) + +=back + +=head1 BUGS AND LIMITATIONS + +This module is very much work-in-progress. + +=head1 REPOSITORY + +L<https://github.com/derf/Travel-Status-DE-DBRIS> + +=head1 AUTHOR + +Copyright (C) 2024 by Birte Kristina Friesel E<lt>derf@finalrewind.orgE<gt> + +=head1 LICENSE + +This module is licensed under the same terms as Perl itself. |