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.