From 399812135206e8279db263a4ef2bc9fc5f18c9da Mon Sep 17 00:00:00 2001 From: Birte Kristina Friesel Date: Sun, 12 Nov 2023 19:00:20 +0100 Subject: Section: Add documentation --- lib/Travel/Routing/DE/HAFAS/Connection/Section.pm | 189 ++++++++++++++++++++++ 1 file changed, 189 insertions(+) (limited to 'lib/Travel/Routing/DE') diff --git a/lib/Travel/Routing/DE/HAFAS/Connection/Section.pm b/lib/Travel/Routing/DE/HAFAS/Connection/Section.pm index 1cc716e..eb7198c 100644 --- a/lib/Travel/Routing/DE/HAFAS/Connection/Section.pm +++ b/lib/Travel/Routing/DE/HAFAS/Connection/Section.pm @@ -162,3 +162,192 @@ sub messages { # }}} 1; + +__END__ + +=head1 NAME + +Travel::Routing::DE::HAFAS::Connection::Section - A single trip between two stops + +=head1 SYNOPSIS + + # $connection is a Travel::Routing::DE::HAFAS::Connection object + for my $sec ( $connection->sections ) { + printf("%s -> %s\n%s ab %s\n%s an %s\n\n", + $sec->name, $sec->direction, + $sec->dep_datetime->strftime('%H:%M'), + $sec->dep_loc->name, + $sec->arr_datetime->strftime('%H:%M'), + $sec->arr_loc->name, + ); + } + +=head1 VERSION + +version 0.01 + +=head1 DESCRIPTION + +Travel::Routing::DE::HAFAS::Connection::Section describes a single section +between two stops, which is typically a public transit trip or a walk. It is +part of a series of sections held by +Travel::Routing::DE::HAFAS::Connection(3pm). + +=head1 METHODS + +Some accessors depend on the section type. Those are annotated with the types +in which they are valid and return undef when called in other contexts. + +=head2 ACCESSORS + +=over + +=item $section->arr_cancelled + +True if the arrival at the end of this section has been cancelled. +False otherwise. + +=item $section->arr_datetime + +DateTime(3pm) object holding the arrival time and date. Based on real-time data +if available, falls back to schedule data otherwise. + +=item $section->arr_delay + +Arrival delay in minutes. Undef if unknown. + +=item $section->arr_loc + +Travel::Routing::DE::HAFAS::Location(3pm) object describing the arrival stop. + +=item $section->arr_platform + +Arrival platform as string, not necessarily numeric. Undef if unknown. + +=item $section->dep_cancelled + +True if the departure at the start of this section has been cancelled. +False otherwise. + +=item $section->dep_datetime + +DateTime(3pm) object holding the departure time and date. Based on real-time +data if available, falls back to schedule data otherwise. + +=item $section->dep_delay + +Departure dlay in minutes. Undef if unknown. + +=item $section->dep_loc + +Travel::Routing::DE::HAFAS::Location(3pm) object describing the departure stop. + +=item $section->dep_platform + +Deprarture platform as string, not necessarily numeric. Undef if unknown. + +=item $section->direction (JNY) + +Travel direction of this trip; this is typically the text printed on the +transport vehicle itself. May differ from its terminus. + +=item $section->distance (WALK) + +Walking distance in meters. Does not take vertical elevation changes into +account. + +=item $section->duration (WALK) + +DateTime::Duration(3pm) oobject holding the walking duration. +Typically assumes a slow pace. + +=item $section->id (JNY) + +HAFAS-internal journey ID. + +=item $section->line (JNY) + +Trip or line name in a format like "Bus SB16" (Bus line SB16), "RE 42" +(RegionalExpress train 42) or "IC 2901" (InterCity train 2901, no line +information). Note that this accessor does not return line information for +IC/ICE/EC services, even if it is available. Use B for those. + +=item $section->line_no (JNY) + +Line identifier; undef if unknown. +The line identifier may be a single number such as "11" (underground train line +U 11), a single word such as "AIR" or a combination (e.g. "SB16"). May also +provide line numbers of IC/ICE services. + +=item $section->messages + +List of Travel::Status::DE::HAFAS::Message(3pm) objects associated with this +connection section. Typically contains messages related to the mode of +transport, such as construction sites, Wi-Fi availability, and the like. + +=item $section->name (JNY) + +Trip or line name in a format like "Bus SB16" (Bus line SB16) or "RE 10111" +(RegionalExpress train 10111, no line information). + +=item $section->number (JNY) + +Trip number (e.g. train number); undef if unknown. + +=item $section->rt_arr + +DateTime(3pm) object holding real-time arrival if available. +Undef otherwise. + +=item $section->rt_dep + +DateTime(3pm) object holding real-time departure if available. +Undef otherwise. + +=item $section->sched_arr + +DateTime(3pm) object holding scheduled arrival if available. +Undef otherwise. + +=item $section->schep_dep + +DateTime(3pm) object holding scheduled departure if available. +Undef otherwise. + +=item $section->transfer_duration (JNY) + +DateTime::Duration(3pm) object holding the difference between the departure of +this journey and the arrival of the previous journey in the connection -- i.e., +the amount of time available for changing platforms. Undef for the first +journey in a connuction. + +=item $section->type + +Type of this section as exposeed by the HAFAS backend. +Known types: B (a public transit journey) and B (walking). + +=back + +=head1 DIAGNOSTICS + +None. + +=head1 DEPENDENCIES + +DateTime::Duration(3pm), Travel::Routing::DE::HAFAS::Utils(3pm). + +=head1 BUGS AND LIMITATIONS + +None known. + +=head1 SEE ALSO + +Travel::Routing::DE::HAFAS(3pm), Travel::Routing::DE::HAFAS::Connection(3pm). + +=head1 AUTHOR + +Copyright (C) 2023 by Birte Kristina Friesel Ederf@finalrewind.orgE + +=head1 LICENSE + +This program is licensed under the same terms as Perl itself. -- cgit v1.2.3