summaryrefslogtreecommitdiff
path: root/lib/Travel
diff options
context:
space:
mode:
authorDaniel Friesel <derf@finalrewind.org>2022-10-22 20:23:48 +0200
committerDaniel Friesel <derf@finalrewind.org>2022-10-22 20:23:48 +0200
commit97b69fa604570bc51b61056adb7270fc536f9fa5 (patch)
tree41719fa4141c071c55b6c30903db81dc59e7a358 /lib/Travel
parente2445f36615980742259c5e54c93b8c272a144c0 (diff)
Journey: remove legacy date/time accessors; update documentation
Diffstat (limited to 'lib/Travel')
-rw-r--r--lib/Travel/Status/DE/HAFAS/Journey.pm178
1 files changed, 123 insertions, 55 deletions
diff --git a/lib/Travel/Status/DE/HAFAS/Journey.pm b/lib/Travel/Status/DE/HAFAS/Journey.pm
index 73de563..03aee01 100644
--- a/lib/Travel/Status/DE/HAFAS/Journey.pm
+++ b/lib/Travel/Status/DE/HAFAS/Journey.pm
@@ -1,5 +1,7 @@
package Travel::Status::DE::HAFAS::Journey;
+# vim:foldmethod=marker
+
use strict;
use warnings;
use 5.014;
@@ -11,10 +13,13 @@ use parent 'Class::Accessor';
our $VERSION = '3.01';
Travel::Status::DE::HAFAS::Journey->mk_ro_accessors(
- qw(sched_date date sched_datetime datetime info is_cancelled operator delay
- sched_time time train route route_end origin destination)
+ qw(datetime sched_datetime rt_datetime is_cancelled operator delay
+ platform sched_platform rt_platform
+ train route_end route_start origin destination direction)
);
+# {{{ Constructor
+
sub new {
my ( $obj, %opt ) = @_;
@@ -147,8 +152,9 @@ sub new {
bless( $ref, $obj );
if ( $journey->{stbStop} ) {
- $ref->{platform} = $journey->{stbStop}{dPlatfS};
- $ref->{new_platform} = $journey->{stbStop}{dPlatfR};
+ $ref->{sched_platform} = $journey->{stbStop}{dPlatfS};
+ $ref->{rt_platform} = $journey->{stbStop}{dPlatfR};
+ $ref->{platform} = $ref->{rt_platform} // $ref->{sched_platform};
my $time_s
= $journey->{stbStop}{ $hafas->{arrivals} ? 'aTimeS' : 'dTimeS' };
@@ -178,11 +184,6 @@ sub new {
else {
$ref->{datetime} = $ref->{sched_datetime};
}
-
- $ref->{date} = $ref->{datetime}->strftime('%d.%m.%Y');
- $ref->{time} = $ref->{datetime}->strftime('%H:%M');
- $ref->{sched_date} = $ref->{sched_datetime}->strftime('%d.%m.%Y');
- $ref->{sched_time} = $ref->{sched_datetime}->strftime('%H:%M');
}
if ( $opt{polyline} ) {
$ref->{polyline} = $opt{polyline};
@@ -191,6 +192,10 @@ sub new {
return $ref;
}
+# }}}
+
+# {{{ Accessors
+
sub line {
my ($self) = @_;
@@ -200,13 +205,13 @@ sub line {
sub is_changed_platform {
my ($self) = @_;
- if ( defined $self->{new_platform} and defined $self->{platform} ) {
- if ( $self->{new_platform} ne $self->{platform} ) {
+ if ( defined $self->{rt_platform} and defined $self->{sched_platform} ) {
+ if ( $self->{rt_platform} ne $self->{sched_platform} ) {
return 1;
}
return 0;
}
- if ( defined $self->{net_platform} ) {
+ if ( defined $self->{rt_platform} ) {
return 1;
}
@@ -222,12 +227,6 @@ sub messages {
return;
}
-sub platform {
- my ($self) = @_;
-
- return $self->{new_platform} // $self->{platform};
-}
-
sub polyline {
my ($self) = @_;
@@ -304,6 +303,8 @@ sub train_no {
return $self->line_no;
}
+# }}}
+
1;
__END__
@@ -311,14 +312,14 @@ __END__
=head1 NAME
Travel::Status::DE::HAFAS::Journey - Information about a single
-arrival/departure received by Travel::Status::DE::HAFAS
+journey received by Travel::Status::DE::HAFAS
=head1 SYNOPSIS
for my $departure ($status->results) {
printf(
"At %s: %s to %s from platform %s\n",
- $departure->time,
+ $departure->datetime->strftime('%H:%M'),
$departure->line,
$departure->destination,
$departure->platform,
@@ -329,7 +330,7 @@ arrival/departure received by Travel::Status::DE::HAFAS
for my $arrival ($status->results) {
printf(
"At %s: %s from %s on platform %s\n",
- $arrival->time,
+ $arrival->datetime->strftime('%H:%M'),
$arrival->line,
$arrival->origin,
$arrival->platform,
@@ -342,9 +343,12 @@ version 3.01
=head1 DESCRIPTION
-Travel::Status::DE::HAFAS::Journey describes a single arrival/departure
-as obtained by Travel::Status::DE::HAFAS. It contains information about
-the platform, time, route and more.
+Travel::Status::DE::HAFAS::Journey describes a single journey. It is either
+a station-specific arrival/departure obtained by a stationboard query, or a
+train journey that does not belong to a specific station.
+
+stationboard-specific accessors are annotated with "(station only)" and return
+undef for non-station results.
=head1 METHODS
@@ -352,32 +356,49 @@ the platform, time, route and more.
=over
-=item $result->date
+=item $result->rt_datetime (station only)
+
+DateTime object indicating the actual arrival/departure date and time.
+undef if no real-time data is available.
+
+=item $result->sched_datetime (station only)
-Arrival/Departure date in "dd.mm.yyyy" format.
+DateTime object indicating the scheduled arrival/departure date and time.
+undef if no schedule data is available.
-=item $result->datetime
+=item $result->datetime (station only)
-DateTime object holding the arrival/departure date and time.
+DateTime object indicating the arrival/departure date and time.
+Real-time data if available, schedule data otherwise.
+undef if neither is available.
-=item $result->delay
+=item $result->delay (station only)
Returns the delay in minutes, or undef if it is unknown.
Also returns undef if the arrival/departure has been cancelled.
-=item $result->info
+=item $result->is_cancelled
-Returns additional information, for instance the most recent delay reason.
-undef if no (useful) information is available.
+True if the journey was cancelled, false otherwise.
-=item $result->is_cancelled
+=item $result->rt_platform (station only)
+
+Actual arrival/departure platform.
+undef if no real-time data is available.
+
+=item $result->sched_platform (station only)
+
+Scheduled arrival/departure platform.
+undef if no scheduled platform is available.
+
+=item $result->platform (station only)
-True if the arrival/departure was cancelled, false otherwise.
+Arrival/Departure platform. Real-time data if available, schedule data
+otherwise. May be undef.
-=item $result->is_changed_platform
+=item $result->is_changed_platform (station only)
-True if the platform (as returned by the B<platform> accessor) is not the
-scheduled one. Note that the scheduled platform is unknown in this case.
+True if the real-time platform is known and it is not the scheduled one.
=item $result->messages
@@ -393,6 +414,11 @@ Returns the line name, either in a format like "Bus SB16" (Bus line SB16)
or "RE 10111" (RegionalExpress train 10111, no line information).
May contain extraneous whitespace characters.
+=item $result->type
+
+Returns the type of this result, e.g. "S" for S-Bahn, "RE" for Regional Express
+or "STR" for tram / StraE<szlig>enbahn.
+
=item $result->line_no
=item $result->train_no
@@ -404,46 +430,88 @@ use single-letter characters or words (e.g. "AIR") as line numbers.
=item $result->operator
-Returns the operator responsible for this arrival/departure. Returns undef
+Returns the operator responsible for this journey. Returns undef
if the backend does not provide an operator.
Note that E<Ouml>BB is the only known backend providing this information.
-=item $result->platform
+=item $result->route
+
+Returns a list of hashes; each hash describes a single journey stop.
+In stationboard mode, it only contains arrivals prior to the requested station
+or departures after the requested station. In journey mode, it contains the
+entire route. Each hash contains the following keys:
-Returns the arrival/departure platform.
-Realtime data if available, schedule data otherwise.
+=over
+
+=item * name (name
+
+=item * eva (EVA ID)
+
+=item * lon (longitude)
+
+=item * lat (latitude)
+
+=item * rt_arr (DateTime object for actual arrival)
+
+=item * sched_arr (DateTime object for scheduled arrival)
+
+=item * arr (DateTime object for actual or scheduled arrival)
+
+=item * arr_delay (arrival delay in minutes)
+
+=item = rt_dep (DateTime object for actual departure)
+
+=item * sched_dep (DateTime object for scheduled departure)
+
+=item * dep (DateTIme object for actual or scheduled departure)
+
+=item * dep_delay (departure delay in minutes)
+
+=item * delay (departure or arrival delay in minutes)
+
+=back
+
+Individual entries may be undef.
=item $result->route_end
+Name of the last route station. In arrival mode, this is where the train
+started; in all other cases, it is the terminus.
+
=item $result->destination
+Alias for route_end; only set when requesting departures in station mode.
+
=item $result->origin
-Returns the last element of the route. Depending on how you set up
-Travel::Status::DE::HAFAS (arrival or departure listing), this is
-either the result's destination or its origin station.
+Alias for route_end; only set when requesting arrivals in station mode.
-=item $result->sched_date
+=item $result->direction
-Scheduled arrival/departure date in "dd.mm.yyyy" format.
+Train direction; this is typically the text printed on the train itself.
+May be different from destination / route_end and may change along the route.
-=item $result->sched_datetime
+=item $result->polyline (journey only)
-DateTime object holding the scheduled arrival/departure date and time.
+List of geocoordinates that describe the train's route. Each list entry is
+a hash with the following keys.
-=item $result->sched_time
+=over
-Scheduled arrival/departure time in "hh:mm" format.
+=item * lon (longitude)
-=item $result->time
+=item * lat (latitude)
-Arrival/Departure time in "hh:mm" format.
+=item * name (name of stop at this location, if any. undef otherwise)
-=item $result->type
+=item * eva (EVA ID of stop at this location, if any. undef otherwise)
-Returns the type of this result, e.g. "S" for S-Bahn, "RE" for Regional Express
-or "STR" for tram / StraE<szlig>enbahn.
+=back
+
+Note that stop locations in B<polyline> may differ from the coordinates
+returned in B<route>. This is a backend issue; Travel::Status::DE::HAFAS
+simply passes the returned coordinates on.
=back