Time::PT - objects to store an instant in time
This documentation refers to version 1.2.565EHOV of Time::PT, which was released on Sun Jun 5 14:17:24:31 2005.
use Time::PT; my $f = Time::PT->new(); print "PipTime is: $f\n"; print 'The Day-of-Week today is: ', $f->dow(), "\n";
By default, Time::PT stores time descriptions precise to 60ths- of-a-second (0.016667 seconds). The groundwork has been laid for sub-millisecond precision to be included later.
This module has been adapted from the Time::Piece module written by Matt Sergeant <matt@sergeant.org> && Jarkko Hietaniemi <jhi@iki.fi>. Time::PT inherits base data structure && object methods from Time::Fields. PT was written to simplify storage && calculation of encoded, yet distinct && human-readable, time data objects.
This module (Time::PT) does not replace the standard localtime && gmtime functions like Time::Piece but Time::PT objects behave almost identically to Time::Piece objects otherwise (since it was adapted from... I said that already =) ).
The reason I created PT was that I have grown so enamored with Base64 representations of everything around me that I was compelled to write a simple clock utility ( `pt` ) using Base64. 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 )
I've made up some silly sentences as mnemonic devices to help me remember every 4th uppercase Base64 character:
Can 12 Noon MonthOfYear will be less or equal to 'C'. Goats 16 4 PM Keep 20 8 PM Oats 24 Midnight HourOfDay will be less than 'O'. Some 28 Where? 32 DayOfMonth will be less than 'W'. Cool COW (Month Hour Day thresholds) Guys Girls Keep Keep On On Off Sayin' Sayin' Sippin' Sea Wassup WeeDoggies Water Water
Many of Time::PT's methods have been patterned after the excellent Time::Piece module written by Matt Sergeant <matt@sergeant.org> && Jarkko Hietaniemi <jhi@iki.fi>.
Time::PT'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 PT objects 3 different ways:
* <packedB64InitStringImplies'str'> eg. Time::PT->new('3C79jo0'); * 'str' => <packedB64InitString> eg. Time::PT->new('str' => '0A1B2C3D4E'); * 'list' => <arrayRef> eg. Time::PT->new('list' => [0, 1, 2..9]); * 'hash' => <hashRef> eg. Time::PT->new('hash' => {'jink' => 8, 'year' => 2003})
This is an object member which will join Base64 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"> '4NT' # eg. color 09 & 'Simp' # eg. RbobYbGbCbUbPb
This function is the legacy procedural version of my command-line PipTime utility. It will be removed in the near future when the object methods fully replace all the old behavior && have been tested sufficiently.
This function && the following ptcc() are the only functions exported when Time::PT is used.
Returns the Simp color code string appropriate for pt (PipTime) data.
Format Returned color code string 'k' the background will change along with the foreground for standard time-of day elements (ie. hms on a dark blue background) 'f' color codes for the expanded pt format (eg. color codes corresponding to Sun Jan 4 12:41:48:13 2004)
This function && the previous legacy pt() are the only functions exported when Time::PT is used.
The following methods allow access to individual fields of Time::PT 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
Please see Time::Fields for further description of field accessor methods.
After importing this module, when you use localtime or gmtime in a scalar context, you DO NOT get a special Time::PT object like you would when using Time::Piece. This module relies on a new() constructor instead. The following methods are available on Time::PT objects though && remain as similar to Time::Piece functionality as makes sense.
$t->frm # also as $t->frame && $t->subsecond $t->sec # also available as $t->second $t->min # also available as $t->minute $t->hour # 24 hour $t->mday # also available as $t->day_of_month $t->mon # 1 = January $t->_mon # 0 = January $t->monname # Feb $t->month # same as $t->mon # *NOTE* The above definition ( of $t->month() ) is # different from the Time::Piece interface which defines # month() the same as monname() instead of mon(). $t->fullmonth # February $t->year # based at 0 (year 0 AD is, of course 1 BC) $t->_year # year minus 1900 $t->yy # 2 digit year $t->wday # 1 = Sunday $t->_wday # 0 = Sunday $t->day_of_week # 0 = Sunday $t->wdayname # Tue $t->day # same as mday # *NOTE* Similar to month(), I've defined day() # differently from Time::Piece which makes it the same # as wdayname() instead of mday(). $t->fullday # Tuesday $t->yday # also available as $t->day_of_year, 0 = Jan 01 $t->isdst # also available as $t->daylight_savings
The following functions return a list of the named fields. The return value can be joined with any desirable delimiter like:
join(':', $t->hms); join($t->time_separator, $t->hms);
but the functions also can take a list of parameters to update the corresponding named fields like:
$t->YMD( 2003, 12, 8 ) # assigns new date of December 8th, 2003 to $t
Following are some useful functions && comments of sample return values:
$t->hms # [12, 34, 56] $t->hmsf # [12, 34, 56, 12] $t->time # same as $t->hmsf $t->ymd # [2000, 2, 29] $t->date # same as $t->ymd $t->mdy # [ 2, 29, 2000] $t->dmy # [29, 2, 2000] $t->datetime # 2000-02-29T12:34:56 (ISO 8601) $t->expand # Tue Feb 29 12:34:56:12 2000 $t->cdate # same as $t->expand $t->compress # 02TCYuC "$t" # same as $t->compress $t->is_leap_year # true if it is $t->month_last_day # 28-31 $t->time_separator($s) # set the default separator (default ":") $t->date_separator($s) # set the default separator (default "-") $t->day_list(@days) # set the default weekdays $t->mon_list(@days) # set the default months
Both wdayname() && monname() can accept the same list parameter as day_list() && mon_list() respectively for temporary help with simple localization.
my @days = ( 'Yom Rishone', 'Yom Shayni', 'Yom Shlishi', 'Yom Revi\'i', 'Yom Khahmishi', 'Yom Hashishi', 'Shabbat' ); my $hebrew_day = pt->wdayname(@days); # pt->monname() can be used similarly
To update the global lists, use:
Time::PT::day_list(@days); && Time::PT::mon_list(@months);
PT object strings (both in normal initialization && printing) grow left-to-right starting from the Year to specify whatever precision you need while Frame objects grow right-to-left from the frame field.
It's possible to use simple addition and subtraction of objects:
use Time::Frame; my $cur_pt = Time::PT->new();# Dhmsf my $one_week = Time::Frame->new('70000'); my $one_week_ago = $cur_pt - $one_week;
If a calculation is done with a raw string parameter instead of an instantiated object, the most likely appropriate object constructor is called on it. These init strings must adhere to the implied 'str' format for auto-creating objects; I aim to support a much wider array of operations && to make this module smoothly interoperate with both Time::Piece && Time::Seconds someday but not yet.
my $cur_pt = Time::PT->new(); my $half_hour_from_now = $cur_pt + 'U00';
The following are valid (where $t0 and $t1 are Time::PT objects && $f is a Time::Frame object):
$t0 - $t1; # returns Time::Frame object $t0 - '63'; # returns Time::PT object $t0 + $f; # returns Time::PT object
All normal numerical && string comparisons should work reasonably on Time::PT objects:
"<", ">", "<=", ">=", "<=>", "==" && "!=" "lt", "gt", "le", "ge", "cmp", "eq" and "ne"
The ISO 8601 standard defines the date format to be YYYY-MM-DD, and the time format to be hh:mm:ss (24 hour clock), and if combined, they should be concatenated with date first and with a capital 'T' in front of the time.
The ISO 8601 standard specifies that weeks begin on Monday and the first week of the year is the one that includes both January 4th and the first Thursday of the year. In other words, if the first Monday of January is the 2nd, 3rd, or 4th, the preceding days are part of the final week of the prior year. Week numbers range from 1 to 53.
Whenever individual Time::PT 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.
There's some weird behavior for PipTimes created with a zero month or day field since both are 1-based. I aim to fix all these bugs but be warned that this issue may be causing math errors for a bit.
I hope you find Time::PT useful. Please feel free to e-mail me any suggestions || coding tips || notes of appreciation ("app-ree-see-ay-shun"). Thank you. TTFN.
Revision history for Perl extension Time::PT:
* updated test.pl to work properly with Build.PL as well as Makefile.PL
* updated License, minor version, && precision description
* added 4NT option to color codes in Fields && color() members in Frame && PT
* updated POD links && CHANGES chronology
* moved pt, fpt, && lspt into bin/ for packaging as EXE_FILES
* added Time::Frame::total_frames method
* moved Curses::Simp::ptCC into Time::PT::ptcc for PipTime-specific Simp Color Codes
* created Time::Fields::_field_colors (centralized base class color codes) && updated Frame && PT _color_fields
* added HOW? POD section for mnemonics
* changed PREREQ to not have lib files from this pkg
* fixed typo && hardcoded path in VERSION_FROM of gen'd Makefile.PL
* combined Fields, Frame, && PT into one pkg
* removed indenting from POD NAME section
* updated test.pl to use normal comments
* added HTML color option && prepared for release
* built class to inherit from Time::Fields && mimic Time::Piece
* original version
Please run:
`perl -MCPAN -e "install Time::PT"`
or uncompress the package && run the standard:
`perl Makefile.PL; make; make test; make install`
Time::PT requires:
Carp to allow errors to croak() from calling sub
Math::BaseCnv to handle simple number-base conversion
Time::DayOfWeek also stores global day && month names
Time::DaysInMonth
Time::Fields to provide underlying object structure
Time::Frame to represent spans of time
Time::PT uses (if available):
Time::HiRes to provide subsecond time precision
Time::Local to turn epoch seconds back into a real date
Time::Zone not utilized yet
Time::Frame
Most source code should be Free! Code I have lawful authority over is && shall be! Copyright: (c) 2002-2005, Pip Stuart. Copyleft : This software is licensed under the GNU General Public License (version 2). Please consult the Free Software Foundation (http://FSF.Org) for important information about your freedom.
Pip Stuart <Pip@CPAN.Org>
To install Time::PT, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Time::PT
CPAN shell
perl -MCPAN -e shell install Time::PT
For more information on module installation, please visit the detailed CPAN module installation guide.