NAME

Astro::App::Satpass2::FormatTime - Format time for output.

SYNOPSIS

 use Astro::App::Satpass2::FormatTime;
 my $ft = Astro::App::Satpass2::FormatTime->new();
 print 'The time is ', $ft->format_datetime( '%H:%M:%S', time );

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 abstracts time formatting for Astro::App::Satpass2.

METHODS

This class supports the following public methods in addition to those inherited from Astro::App::Satpass2::Copier.

new

 my $ft = Astro::App::Satpass2::FormatTime->new();

This method instantiates a time formatter object.

gmt

 $ft->gmt ( 1 );
 print 'The gmt attribute is ', $ft->gmt() ? "true\n" : "false\n";

This method is both accessor and mutator for the gmt attribute. This boolean attribute provides a default for the gmt argument of format_datetime().

If called with an argument, the argument becomes the new value of the gmt attribute. The object is returned to allow call chaining.

If called without an argument, the current value of the gmt attribute is returned.

format_datetime

 print 'Time now: ', $ft->format_datetime( '%H:%M:%S', time, 0 ), "\n";

This attribute uses the format passed in the first argument to format the Perl time passed in the second argument. The third argument, if defined, overrides the gmt attribute, forcing the time to be GMT if true, or local if false.

The string representing the formatted time is returned.

This method must be overridden by the subclass. The override may use the value of the tz attribute to format the local time in the given zone, provided the value of tz is defined and not ''. The override may accept times in formats other than Perl epoch, but it need not document or support these.

format_datetime_width

 my $wid = $ft->format_datetime_width( '%H:%M:%S' );

This method computes the maximum width required to display a time in the given format. This is done by assuming only the month, day, and meridian might affect the width, and then trying each and returning the width of the widest.

__format_datetime_width_adjust_object

 my $ref = $self->__format_datetime_width_adjust_object( undef, year => 2100 );

This method must be overridden by the subclass. It exists to support format_datetime_width(), and should not be called directly. It is not itself supported, in the sense that the author reserves the right to change or revoke it without notice. Though since this whole mess is unsupported in that sense, this statement is redundant.

This method takes as its arguments a time in any format supported by the format_datetime() method, the name of a component (year, month, day, hour, minute, or second), and a value for that component. The time is returned with the given component set to the given value. If the time is undef, a new time representing 01-Jan-2100 00:00:00 is constructed, adjusted, and returned.

round_time

 $ft->round_time( 60 );
 print 'Time rounded to ', $ft->round_time(), ' seconds';

This method is both accessor and mutator for the time rounding specification maintained on behalf of the subclass. If the subclass overrides this, it must call SUPER::round_time with the same arguments.

If called with an argument, the argument becomes the new rounding specification, in seconds. The argument must be an integer number of seconds, the special-cased strings 'second', 'minute' or 'hour' (which specify 1, 60 and 3600 respectively), or undef to turn off rounding. Be aware that if rounding is turned off the time formatter may truncate the time.

If called without an argument, the current value of the round_time attribute is returned. This will always be an integer.

The default value is 1.

__round_time_value

 $time = $ft->__round_time_value( $time );

This method exists to support the rounding of time values by subclasses, and should not be called directly. It is not itself supported, in the sense that the author reserves the right to change or revoke it without notice.

This method takes as its argument an epoch time, and returns it rounded to the precision specified by $ft->round_time().

tz

 $ft->tz( 'mst7mdt' );
 print 'Current zone: ', $ft->tz(), "\n";

This method is both accessor and mutator for the time zone, maintained on behalf of the subclass. If the subclass overrides this, it must call SUPER::tz with the same arguments.

If called with an argument, the argument becomes the new zone, with either '' or undef representing the default zone. The object is returned to allow call chaining.

If called without an argument, the current value of the tz attribute is returned.

SUPPORT

Support is by the author. Please file bug reports at http://rt.cpan.org, or in electronic mail to the author.

AUTHOR

Thomas R. Wyant, III wyant at cpan dot org

COPYRIGHT AND LICENSE

Copyright (C) 2010-2014 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.

cpanm Astro::App::Satpass2

perl -MCPAN -e shell
install Astro::App::Satpass2