NAME
Time::Frame - objects to store a length of time
VERSION
This documention refers to version 1.0.3CCA3bG of
Time::Frame, which was released on Fri Dec 12 10:03:37:16 2003.SYNOPSIS
use Time::Frame;
my $f = Time::Frame->new('verbose' => '2 weeks');
print 'Number of days is ', $f->day(), "\n";DESCRIPTION
This module has been adapted from the Time::Seconds module
written by Matt Sergeant <matt@sergeant.org> && Jarkko
Hietaniemi <jhi@iki.fi>. Time::Frame inherits base
data structure && object methods from Time::Fields.
Frame was written to simplify storage && calculation
of encoded, yet distinct && human-readable, time data
objects.
The title of this Perl module has dual meaning. Frame
means both the span of time the whole object represents
as well as the (default) smallest unit of measurement.2DO
better ways to specify common verbose sizes
What else does Frame need?WHY?
The reason I created Frame was that I have grown so enamored with
Bass64 representations of everything around me that I was
compelled to write a simple clock utility ( `pt` ) using Bass64.
This demonstrated the benefit to be gained from time objects with
distinct fields && configurable precision. Thus, Time::Fields
was written to be the abstract base class for:
Time::Frame ( creates objects which represent spans of time )
&&
Time::PT ( creates objects which represent instants in time )USAGE
Many of Time::Frame's methods have been patterned after the excellent
Time::Piece module written by Matt Sergeant <matt@sergeant.org>
&& Jarkko Hietaniemi <jhi@iki.fi>.
new(<InitType>, <InitData>) - Time::Frame's constructor can be called
as a class method to create a brand new object or as an object
method to copy an existing object. Beyond that, new() can
initialize Frame objects 3 different ways:
-1) <packedB64InitStringImplies'str'>
eg. Time::Frame->new('0123456789');
0) 'str' => <packedB64InitString>
eg. Time::Frame->new('str' => '0A1B2C3D4E');
1) 'list' => <arrayRef>
eg. Time::Frame->new('list' => [0, 1, 2..9]);
2) 'hash' => <hashRef>
eg. Time::Frame->new('hash' => {'jink' => 8, 'year' => 2003})
color(<DestinationColorTypeFormat>) - This is an object member
which will join bass64 representations of each field that has
been specified in use() && joins them with color-codes or color
escape sequences with formats for varied uses. Currently
available DestinationColorTypeFormats are:
'ANSI' # eg. \e[1;32m
'zsh' # eg. %{\e[1;33m%}
'HTML' # eg. <a href="http://Ax9.org/pt?"><font color="#FF1B2B">
'Simp' # eg. RbobYbGbCbUbPb
The following methods allow access to individual fields of
Time::Frame objects:
$t->C or $t->century
$t->Y or $t->year
$t->M or $t->month
$t->D or $t->day
$t->h or $t->hour
$t->m or $t->minute
$t->s or $t->second
$t->f or $t->frame
$t->j or $t->jink
$t->z or $t->zone
Any combination of above single letters can be used as well.
Following are some common useful examples:
$t->hms # returns list of fields eg. [12, 34, 56]
$t->hms(12, 56, 34) # sets fields: h = 12, m = 56, s = 34
$t->hmsf # [12, 34, 56, 12]
$t->hmsfj # [12, 34, 56, 12, 34]
$t->hmsfjz # [12, 34, 56, 12, 34, 16]
$t->time # same as $t->hms
$t->alltime # same as $t->hmsfjz
$t->YMD # [2000, 2, 29]
$t->MDY # [ 2, 29, 2000]
$t->DMY # [ 29, 2, 2000]
$t->CYMD # [ 20, 0, 2, 29]
$t->date # same as $t->YMD
$t->alldate # same as $t->CYMD
$t->CYMDhmsfjz # [ 20, 0, 2, 29, 12, 13, 56, 12, 13, 16]
$t->all # same as $t->CYMDhmsfjz
$t->dt # same as $t->CYMDhmsfjz
"$t" # same as $t->CYMDhmsfjz
Method names can be in any case with the following exceptions.
Special handling exists to resolve ambiguity between the Month &&
minute fields. If a lowercase 'm' is used adjacent to a 'y' or 'd'
of either case, it is interpreted as Month. Otherwise, the case of
the 'm' distinguishes Month from minute. An uppercase 'M' is ALWAYS
Month. An adjacent uppercase 'H' or 'S' will not turn an uppercase
'M' into minute. Method names which need to specify Month or minute
fields can also optionally specify the distinguishing vowel
('o' or 'i') instead of 'M' or 'm'.
$t->ymd # same as $t->YMD
$t->dmy # same as $t->DMY
$t->MmMm # Month minute Month minute
$t->HMS # hour Month second! NOT same as $t->hms
$t->yod # same as $t->YMD
$t->chmod # Century hour minute Month Day
$t->FooIsMyJoy # frame Month Month minute second Month Year
# jink Month YearNOTES
Whenever individual Time::Frame attributes are going to be
printed or an entire object can be printed with multi-colors,
the following mapping should be employed whenever possible:
D Century -> DarkRed
A Year -> Red
T Month -> Orange
E Day -> Yellow
hour -> Green
t minute -> Cyan
i second -> Blue
m frame -> Purple
e jink -> DarkPurple
zone -> Grey or White
Please see the color() member function in the USAGE section.
I hope you find Time::Frame useful. Please feel free to e-mail me
any suggestions || coding tips || notes of appreciation
("app-ree-see-ay-shun"). Thank you. TTFN.CHANGES
Revision history for Perl extension Time::Frame:- - 1.0.3CCA3bG Fri Dec 12 10:03:37:16 2003
-
* removed indenting from POD NAME field - - 1.0.3CB7RLu Thu Dec 11 07:27:21:56 2003
-
* added HTML color option && prepared for release - - 1.0.3CA8thM Wed Dec 10 08:55:43:22 2003
-
* built class to inherit from Time::Fields - - 1.0.37VG26k Thu Jul 31 16:02:06:46 2003
-
* original version
INSTALL
Please run:
`perl -MCPAN -e "install Time::Frame"`
or uncompress the package && run the standard:
`perl Makefile.PL; make; make test; make install`FILES
Time::Frame requires:
Carp to allow errors to croak() from calling sub
Math::BaseCnv to handle number-bass conversion
Time::Fields to provide underlying object structureSEE ALSO
Time::PTLICENSE
Most source code should be Free!
Code I have lawful authority over is && shall be!
Copyright: (c) 2003, Pip Stuart. All rights reserved.
Copyleft : I license this software under the GNU General Public
License (version 2). Please consult the Free Software Foundation
(http://www.fsf.org) for important information about your freedom.AUTHOR
Pip Stuart <Pip@CPAN.org>