/ 
Astro-App-Satpass2-0.054
River stage zero No dependents
/ Astro::App::Satpass2::ParseTime

NAME

Astro::App::Satpass2::ParseTime - Parse time for Astro::App::Satpass2

SYNOPSIS

my $pt = Astro::App::Satpass2::ParseTime->new();
defined( my $epoch_time = $pt->parse( $string ) )
  or die "Unable to parse time '$string'";

NOTICE

This class and its subclasses are private to the Astro::App::Satpass2 package. The author reserves the right to add, change, or retract functionality without notice.

DETAILS

This class provides an interface to the possible time parsers. A subclass of this class provides (or wraps) a parser, and exposes that parser through a parse_time_absolute() method.

There are actually three time formats supported by this parser.

Relative times begin with a '+' or a '-', and represent the number of days, hours, minutes and seconds since (or before) the most-recently-specified absolute time. The individual components (days, hours, minutes and seconds) are separated by either colons or white space. Trailing components (and separators) may be omitted, and default to 0.

Epoch times are composed of the string 'epoch ' followed by a number, and represent that time relative to Perl's epoch. It would have been nice to just accept a number here, but it was impossible to disambiguate a Perl epoch from an ISO-8601 time without punctuation.

Scalar references are also interpreted as epoch times.

Absolute times are anything not corresponding to the above. These are the only times actually passed to "parse_time_absolute".

This class is a subclass if Astro::App::Satpass2::Copier.

METHODS

This class supports the following public methods:

new

my $pt = Astro::App::Satpass2::ParseTime->new();

This method instantiates the parser. The actual returned class will be the first that can be instantiated in the list Astro::App::Satpass2::ParseTime::Date::Manip, Astro::App::Satpass2::ParseTime::ISO8601.

You can specify optional arguments to new() as name/value pairs. The following name/value pairs are implemented:

class

This argument specifies the short name of the class to instantiate (i.e. the part of the name after 'Astro::App::Satpass2::ParseTime::'. You can specify multiple values, either by separating them with commas or as an array reference. If multiple values are specified, you get the first that can actually be instantiated.

The default is 'Date::Manip,ISO8601' (or, equivalently, [ qw{ Date::Manip ISO8601 ]).

tz

This argument specifies the default time zone.

base

$pt->base( time );    # Set base time to now
$base = $pt->base();  # Retrieve current base time

This method is both accessor and mutator for the object's base time. This time is used (indirectly) when the parse identifies a relative time.

When called without arguments, it behaves as an accessor, and returns the current base time setting.

When called with at least one argument, it behaves as a mutator, sets the base time, and returns the $pt object to allow call chaining.

Subclasses may override this method, but if they do so they must call SUPER:: with the same arguments they themselves were called with, and return whatever SUPER:: returns.

config

use YAML;
print Dump ( $pt->config( changes => 1 );

This method retrieves the configuration of the formatter as an array of array references. The first element of each array reference is a method name, and the subsequent elements are arguments to that method. Calling the given methods with the given arguments should reproduce the configuration of the formatter.

There are two named arguments:

changes

If this boolean argument is true (in the Perl sense), only changes from the default configuration are reported.

decode

If this boolean argument is true (in the Perl sense), the decode() method is used to obtain the configuration values.

Subclasses that add other ways to configure the object must override this method. The override must call SUPER::config(), and include the result in the returned data.

delegate

my $delegate = $class->delegate()

This static method returns the name of the class to be instantiated. Normally a subclass will return its own class name, but if there is more than one possible wrapper for a given parser (e.g. Date::Manip, which gets handled differently based on its version number), the wrapper should return the name of the desired class.

This method must be overridden by any subclass.

decode

$pt->decode( 'tz' );

This method wraps other methods, converting their returned values to human-readable. The arguments are the name of the method, and its arguments if any. The return values of methods not explicitly documented below are not modified.

There are currently no methods whose returns are affected by routing them through decode. This may change.

If a subclass overrides this method, the override should either perform the decoding itself, or delegate to SUPER::decode.

parse_time_absolute

$epoch_time = $pt->parse_time_absolute( $string );

This method parses an absolute time string. It returns seconds since the epoch, or undef on error.

This method must be overridden by any subclass.

perltime

$pt->perltime( 1 );            # Turn on the perltime hack
$perltime = $pt->perltime();	# Find out whether the hack is on

This method is both accessor and mutator for the object's perltime flag. This is a Boolean flag which the subclass may (or may not!) use to get the summer time straight when parsing time. If the flag is on (and the subclass supports it) the tz setting is ignored, and an attempt to specify a time zone in a time to be parsed will produce undefined results.

When called without arguments, it behaves as an accessor, and returns the current perltime flag setting.

When called with at least one argument, it behaves as a mutator, sets the perltime flag, and returns the $pt object to allow call chaining.

This specific method simply records the perltime setting.

Subclasses may override this method, but if they do so they must call SUPER:: with the same arguments they themselves were called with, and return whatever SUPER:: returns.

parse

defined( $epoch_time = $pt->parse( $string, $default ) )
  or die "'$string' can not be parsed.";

This method parses a time, returning the resultant Perl time. If $string is undef or '', $default is returned, or undef if $default is not specified. If $string fails to parse, undef is returned.

reset

$pt->reset();

This method resets the base time for relative times to the value of the base attribute. It returns the $pt object to allow for call chaining.

use_perltime

$classname->use_perltime()

This static method returns true if the class uses the perltime mechanism, and false otherwise.

This specific class simply returns false.

Subclasses may override this method, but if they do they must not call SUPER::.

tz

$pt->tz( 'EST5EDT' );          # Specify an explicit time zone
$pt->tz( undef );              # Specify the default time zone
$tz = $pt->tz();               # Find out what the time zone is

This method is both accessor and mutator for the object's time zone setting. What can go here depends on the specific subclass in use.

When called without arguments, it behaves as an accessor, and returns the current time zone setting.

When called with at least one argument, it behaves as a mutator, sets the time zone, and returns the $pt object to allow call chaining.

This specific method simply records the tz setting.

Subclasses may override this method, but if they do so they must call SUPER:: with the same arguments they themselves were called with, and return whatever SUPER:: returns. Also, overrides must interpret an undef argument as a request to set the default time zone, not as an accessor call.

SUPPORT

Support is by the author. Please file bug reports at https://rt.cpan.org/Public/Dist/Display.html?Name=Astro-App-Satpass2, https://github.com/trwyant/perl-Astro-App-Satpass2/issues, or in electronic mail to the author.

AUTHOR

Thomas R. Wyant, III wyant at cpan dot org

COPYRIGHT AND LICENSE

Copyright (C) 2010-2024 by Thomas R. Wyant, III

This program is free software; you can redistribute it and/or modify it under the same terms as Perl 5.10.0. For more details, see the full text of the licenses in the directory LICENSES.

This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.