From d33460918190bef8259b19f5793d4fce0e7fe485 Mon Sep 17 00:00:00 2001
From: Daniel Friesel <derf@finalrewind.org>
Date: Thu, 23 Jun 2011 16:16:41 +0200
Subject: [PATCH] Documentation
---
bin/mris | 2 +-
lib/Travel/Status/DE/DeutscheBahn.pm | 77 +++++++++++++++++
.../Status/DE/DeutscheBahn/Departure.pm | 82 ++++++++++++++++++-
3 files changed, 159 insertions(+), 2 deletions(-)
diff --git a/bin/mris b/bin/mris
index c6e34c7..95e1c6e 100755
--- a/bin/mris
+++ b/bin/mris
@@ -47,7 +47,7 @@ for my $d ( $status->departures() ) {
printf(
"%5s %-10s %-80s %-20s %-2d %s\n",
- $d->time, $d->train, join( q{ }, @via_show ),
+ $d->time, $d->train, join( q{ }, @via_show ),
$d->destination, $d->platform, $d->info
);
}
diff --git a/lib/Travel/Status/DE/DeutscheBahn.pm b/lib/Travel/Status/DE/DeutscheBahn.pm
index 499f540..748184c 100644
--- a/lib/Travel/Status/DE/DeutscheBahn.pm
+++ b/lib/Travel/Status/DE/DeutscheBahn.pm
@@ -53,6 +53,21 @@ sub new {
return bless( $ref, $obj );
}
+sub new_from_html {
+ my ( $obj, $html ) = @_;
+
+ my $ref = { html => $html, };
+
+ $ref->{tree} = XML::LibXML->load_html(
+ string => $ref->{html},
+ recover => 2,
+ suppress_errors => 1,
+ suppress_warnings => 1,
+ );
+
+ return bless( $ref, $obj );
+}
+
sub departures {
my ($self) = @_;
@@ -137,30 +152,92 @@ departure monitor
=head1 SYNOPSIS
+ use Travel::Status::DE::DeutscheBahn;
+
+ my $status = Travel::Status::DE::DeutscheBahn->new(
+ station => 'Essen Hbf',
+ );
+
+ for my $departure ($status->departures) {
+ printf(
+ "At %s: %s to %s from platform %s\n",
+ $departure->time,
+ $departure->train,
+ $departure->destination,
+ $departure->platform,
+ );
+ }
+
=head1 VERSION
version 0.0
=head1 DESCRIPTION
+Travel::Status::DE::DeutscheBahn is an interface to the DeutscheBahn
+arrival/departure monitor available at
+L<http://mobile.bahn.de/bin/mobil/bhftafel.exe/dn?rt=1>.
+
+It takes a station name and (optional) date and time and reports all
+departures at that station starting at the specified point in time (now if
+unspecified). By default, it will list the next 20 departures.
+
=head1 METHODS
=over
+=item my $status = Travel::Status::DE::DeutscheBahn->new(I<%opts>)
+
+Returns a new Travel::Status::DE::DeutscheBahn element. Supported I<opts> are:
+
+=over
+
+=item B<station> => I<station>
+
+The train station to report for, e.g. "Essen HBf". Mandatory.
+
+=item B<date> => I<dd>.I<mm>.I<yyyy>
+
+Date to report for. Defaults to the current day.
+
+=item B<time> => I<hh>:I<mm>
+
+Time to report for. Defaults to now.
+
+=back
+
+=item $status->departures()
+
+Returns a list of departures (20 by default). Each list element is a
+Travel::Status::DE::DeutscheBahn::Departure(3pm) object.
+
=back
=head1 DIAGNOSTICS
+None.
+
=head1 DEPENDENCIES
=over
+=item * Class::Accessor(3pm)
+
+=item * LWP::UserAgent(3pm)
+
+=item * XML::LibXML(3pm)
+
=back
=head1 BUGS AND LIMITATIONS
+The web interface also offers arrival monitoring. This is not yet supported
+in this module.
+
=head1 SEE ALSO
+mris(1), Travel::Status::DE::DeutscheBahn::Departure(3pm).
+
=head1 AUTHOR
Copyright (C) 2011 by Daniel Friesel E<lt>derf@finalrewind.orgE<gt>
diff --git a/lib/Travel/Status/DE/DeutscheBahn/Departure.pm b/lib/Travel/Status/DE/DeutscheBahn/Departure.pm
index 9ca1aa9..d4487ac 100644
--- a/lib/Travel/Status/DE/DeutscheBahn/Departure.pm
+++ b/lib/Travel/Status/DE/DeutscheBahn/Departure.pm
@@ -36,30 +36,110 @@ departure received by Travel::Status::DE::DeutscheBahn
=head1 SYNOPSIS
+ for my $departure ($status->departures) {
+ printf(
+ "At %s: %s to %s from platform %s\n",
+ $departure->time,
+ $departure->train,
+ $departure->destination,
+ $departure->platform,
+ );
+ }
+
=head1 VERSION
-version
+version 0.0
=head1 DESCRIPTION
+Travel::Status::DE::DeutscheBahn::Departure describes a single departure as
+obtained by Travel::Status::DE::DeutscheBahn. It contains information about
+the platform, departure time, destination and more.
+
+=head1 ACCESSORS
+
+=over
+
+=item $departure->destination
+
+Returns the name of the destination station, e.g. "Dortmund Hbf".
+
+=item $departure->info
+
+Returns additional information, usually wether the train is on time or
+delayed.
+
+=item $departure->platform
+
+Returns the platform from which the train will depart.
+
+=item $departure->route
+
+Returns a list of station names the train will pass between the selected
+station and its destination.
+
+=item $departure->time
+
+Returns the departure time as string in "hh:mm" format.
+
+=item $departure->train
+
+Returns the line / train name, either in a format like "S 1" (S-Bahn line 1)
+or "RE 10111" (RegionalExpress train 10111, no line information).
+
+=back
+
=head1 METHODS
=over
+=item $departure = Travel::Status::DE::DeutscheBahn::Departure->new(I<%data>)
+
+Returns a new Travel::Status::DE::DeutscheBahn::Departure object.
+You usually do not need to call this.
+
+Required I<data>:
+
+=over
+
+=item B<time> => I<hh:mm>
+
+=item B<train> => I<string>
+
+=item B<route_raw> => I<string>
+
+=item B<route> => I<arrayref>
+
+=item B<destination> => I<string>
+
+=item B<platform> => I<string>
+
+=item B<info> => I<string>
+
+=back
+
=back
=head1 DIAGNOSTICS
+None.
+
=head1 DEPENDENCIES
=over
+=item Class::Accessor(3pm)
+
=back
=head1 BUGS AND LIMITATIONS
+Unknown.
+
=head1 SEE ALSO
+Travel::Status::DE::DeutscheBahn(3pm).
+
=head1 AUTHOR
Copyright (C) 2011 by Daniel Friesel E<lt>derf@finalrewind.orgE<gt>
--
GitLab