NAME
Time::Format - Easy-to-use date/time formatting.
VERSION
This documentation describes version 0.02 of Time::Format.pm, June 10, 2003.
SYNOPSIS
use Time::Format qw(%time %strftime %manip);
print "Today is $time{'yyyy/mm/dd'}\n";
print "Yesterday was $time{'yyyy/mm/dd', time-24*60*60}\n";
print "The time is $time{'hh:mm:ss'}\n";
print "Another time is $time{'H:mm am', $another_time}\n";
print "Timestamp: $time{'yyyymmdd.hhmmss.mmm'}\n";
print "POSIXish: $strftime{'%A, %B %d, %Y', 0,0,0,12,11,95,2}\n";
print "POSIXish: $strftime{'%A, %B %d, %Y', 1054866251}\n";
print "POSIXish: $strftime{'%A, %B %d, %Y'}\n"; # current time
print "Date::Manip: $manip{'%m/%d/%Y'}\n"; # current time
print "Date::Manip: $manip{'%m/%d/%Y','last Tuesday'}\n";DESCRIPTION
This module creates global pseudovariables which format dates and times. The nice thing about having a variable-like interface instead of function calls is that the values can be used inside of strings (as well as outside of strings in ordinary expressions). Dates are frequently used within strings (log messages, output, data records, etc), so having the ability to interpolate them directly is handy.
Perl allows arbitrary expressions within curly braces of a hash, even when that hash is being interpolated into a string. See the "yesterday" example above.
The %time formatting codes are designed to be easy to remember and use, and to take up as many characters as the output time value whenever possible. For example, the four-digit year code is "yyyy".
The format strings are designed with programmers in mind. What do you need most frequently? 4-digit year, month, day, 24-based hour, minute, second -- usually with leading zeroes. These six are the easiest formats to use and remember in Time::Format: yyyy, mm, dd, hh, mm, ss. Variants on these formats follow a simple and consistent formula. This module is for everyone who is sick of trying to remember strftime(3)'s arcane codes, or of endlessly writing $t[4]++; $t[5]+=1900.
Note that mm (and related codes) are used both for months and minutes. This is a feature. %time resolves the ambiguity by examining other nearby formatting codes. If it's in the context of a year or a day, "month" is assumed. If in the context of an hour or a minute, "minute" is assumed.
The format strings are not meant to encompass every date/time need ever conceived. But hey, how often do you need the day of the year (strftime's %j) or the week number (strftime's %W)?
For capabilities that %time does not provide, %strftime provides an interface to POSIX's strftime, and %manip provides an interface to the Date::Manip module's UnixDate function.
VARIABLES
- time
-
$time{$format} $time{$format,$unixtime};Formats a unix time number according to the specified format. If the time expression is omitted, the current time is used. The format string may contain any of the following:
yyyy 4-digit year yy 2-digit year mm 2-digit month, 01-12 m 1- or 2-digit month, 1-12 ?m month with leading space if < 10 Month full month name, mixed-case MONTH full month name, uppercase month full month name, lowercase Mon 3-letter month abbreviation, mixed-case MON mon ditto, uppercase and lowercase versions dd day number, 01-31 d day number, 1-31 ?d day with leading space if < 10 Weekday weekday name, mixed-case WEEKDAY weekday name, uppercase weekday weekday name, lowercase Day 3-letter weekday name, mixed-case DAY day ditto, uppercase and lowercase versions hh hour, 00-23 h hour, 0-23 ?h hour, 0-23 with leading space if < 10 HH hour, 01-12 H hour, 1-12 ?H hour, 1-12 with leading space if < 10 mm minute, 00-59 m minute, 0-59 ?m minute, 0-59 with leading space if < 10 ss second, 00-60 s second, 0-60 ?s second, 0-60 with leading space if < 10 mmm millisecond, 000-999 uuuuuu microsecond, 000000-999999 am a.m. The string "am" or "pm" (second form with periods) pm p.m. same as "am" or "a.m." AM A.M. same as "am" or "a.m." but uppercase PM P.M. same as "AM" or "A.M."Millisecond and microsecond require Time::HiRes, otherwise they'll always be zero.
Anything in the format string other than the above patterns is left intact.
For the most part, each of the above formatting codes takes up as much space as the output string it generates. The exceptions are the codes whose output is variable length:
Weekday,Month, and the single-character codes.Note that the "
mm", "m", and "?m" formats are ambiguous.%timetries to guess whether you meant "month" or "minute" based on nearby characters in the format string. Thus, a format of "yyyy/mm/dd hh:mm:ss" is parsed as "year month day, hour minute second". To remove the ambiguity, you can use the following codes:2mon month, 01-31 1mon month, 1-31 ?mon month, 1-31 with leading space if < 10 2min minute, 00-59 1min minute, 0-59 ?min minute, 0-59 with leading space if < 10 - strftime
-
$strftime{$format, $sec,$min,$hour, $mday,$mon,$year, $wday,$yday,$isdst} $strftime{$format, $unixtime} $strftime{$format}For those who prefer strftime(3)'s weird % formats, or who need POSIX compliance.
- manip
-
$manip{$format}; $manip{$format,$when};Provides an interface to the Date::Manip module's
UnixDatefunction. This function is rather slow, but can parse a very wide variety of date input. See the Date::Manip module for details about the formats accepted.If you want to use the
%timecodes, but need the input flexibility of%manip, you can use Date::Manip's%sformat and nest the calls:print "$time{'yyyymmdd',$manip{'%s','last sunday'}}";
EXAMPLES
$time{'Weekday Month d, yyyy'} Thursday June 5, 2003
$time{'Day Mon d, yyyy'} Thu Jun 5, 2003
$time{'dd/mm/yyyy'} 05/06/2003
$time{yymmdd} 030605
$time{'H:mm:ss am'} 1:02:14 pm
$time{'hh:mm:ss.uuuuuu'} 13:02:14.171447
$time{'yyyy/2mon/dd hh:2min:ss.mmm'} 2003/06/05 13:02:14.171
$time{'yyyy/mm/dd hh:mm:ss.mmm'} 2003/06/05 13:02:14.171
$strftime{'%A %B %e, %Y'} Thursday June 5, 2003
$manip{'%m/%d/%Y'} 06/05/2003
$manip{'%m/%d/%Y','yesterday'} 06/04/2003
$manip{'%m/%d/%Y','first monday in November 2000'} 11/06/2000EXPORTS
The following symbols are available for import into your namespace. No symbols are exported by default.
%time
%strftime
%manipThe :all tag will import all of these into your namespace. Example:
use Time::Format ':all';REQUIREMENTS
Carp (included with Perl)
Exporter (included with Perl)
POSIX, if you choose to use %strftime
Time::HiRes, if you want the C<mmm> and C<uuuuuu> time formats to work
Date::Manip, if you choose to use %manipAUTHOR / COPYRIGHT
Eric J. Roode, roode@cpan.org
Copyright (c) 2003 by Eric J. Roode. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
If you have suggestions for improvement, please drop me a line. If you make improvements to this software, I ask that you please send me a copy of your changes. Thanks.