NAME

Astro::App::Satpass2::ParseTime::Code - Astro::App::Satpass2 wrapper for custom code to parse time

SYNOPSIS

No user-serviceable parts inside.

DESCRIPTION

This class wraps code to parse a time string and return the epoch.

METHODS

This class supports the following public methods over and above those documented in its superclass Astro::App::Satpass2::ParseTime.

code

my $value = $pt->code();
$pt->code( 'my_time_parser' );
$pt->code( 'Some::Package::time_parser' );
$pt->code( sub { ... } );
$pt->code( sub { ... }, 'name_of_record' );

This method acts as both accessor and mutator for the code attribute, which contains the code to do the parsing. Without arguments it is an accessor, returning the value of the attribute.

If called with arguments, it sets the value of the attribute. You can pass either the name of the subroutine that implements the parse, or a reference to it. An unqualified name is resolved in the caller's name space.

In general the accessor returns what was set. But if you pass a name of record after the code reference (as in the last example above), that name of record will be returned as the value of the attribute.

The code reference will be called with the following arguments:

the invocant

That is, it will be called as though it was a method of this class.

a reference to an options hash

If the code has the Verb() attribute (as it will if it comes from a code macro), the options will be as parsed by Getopt::Long using the value of the Verb() attribute as the option specification.

If the code does not have the Verb() attribute, the reference will be to an empty hash.

the name of the action to to perform

Supported values are discussed below. Any other values are unsupported and reserved by the author.

the arguments for the action, if any.

The arguments depend on the action, as follows:

parse

The argument is the string to parse. The code must return the epoch, or call wail() on the invocant to generate an exception.

This is the only action that must be implemented.

tz

The argument is the time zone being set. The return value is ignored, but the code must call wail() to generate an exception if it does not like the value of the time zone.

If this action has no specific implementation, the code should simply return.

use_perltime

No argument is provided. The code must return a true value if it makes use of the perltime attribute, and a false value otherwise.

If this action has no specific implementation, the code should simply return.

The code reference will be called when the time zone is set (to give the code a chance to reject it), and to request a parse.

In the first case the arguments are ( $self, tz => $zone ), where $self is a reference to this object, and $zone is the prospective new time zone. When called this way the code would reject the zone by calling $self->wail( $some_message ). The code accepts the zone by simply returning.

In the second case the arguments are ( $self, parse = $string >, where $self is as before, and $string is the string to be parsed. If the parse is successful, the code must return the epoch time. If the parse fails, the code must call wail() as above.

You do not need to specify 'code' as an argument to new(), though you can. But you must have set the code before calling inherited method parse_time_absolute().

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

Tom Wyant (wyant at cpan dot org)

COPYRIGHT AND LICENSE

Copyright (C) 2016-2023 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.