From 97b69fa604570bc51b61056adb7270fc536f9fa5 Mon Sep 17 00:00:00 2001 From: Daniel Friesel Date: Sat, 22 Oct 2022 20:23:48 +0200 Subject: Journey: remove legacy date/time accessors; update documentation --- lib/Travel/Status/DE/HAFAS/Journey.pm | 178 +++++++++++++++++++++++----------- 1 file 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 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 / StraEenbahn. + =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 EBB 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 / StraEenbahn. +=back + +Note that stop locations in B may differ from the coordinates +returned in B. This is a backend issue; Travel::Status::DE::HAFAS +simply passes the returned coordinates on. =back -- cgit v1.2.3