Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Astro::App::Satpass2::UsereContributed Perl Astro::App::Satpass2::ParseTime(3)

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-2021 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.

perl v5.32.1			  2021-11-04Astro::App::Satpass2::ParseTime(3)

NAME | SYNOPSIS | NOTICE | DETAILS | METHODS | SUPPORT | AUTHOR | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Astro::App::Satpass2::ParseTime&sektion=3&manpath=FreeBSD+13.1-RELEASE+and+Ports>

home | help