.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Date::Manip::Date 3pm"
.TH Date::Manip::Date 3pm 2024-03-02 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Date::Manip::Date \- Methods for working with dates
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 2
\&   use Date::Manip::Date;
\&   $date = new Date::Manip::Date;
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This module works specifically with date objects.
.PP
Although the word date is used extensively here, it is actually
somewhat misleading.  Date::Manip works with the full calendar date
(year, month, day, and week when appropriate), time of day (hour,
minute, second), and time zone.  It doesn't work with fractional
seconds.
.SH METHODS
.IX Header "METHODS"
.IP \fBbase\fR 4
.IX Item "base"
.PD 0
.IP \fBconfig\fR 4
.IX Item "config"
.IP \fBerr\fR 4
.IX Item "err"
.IP \fBis_date\fR 4
.IX Item "is_date"
.IP \fBis_delta\fR 4
.IX Item "is_delta"
.IP \fBis_recur\fR 4
.IX Item "is_recur"
.IP \fBnew\fR 4
.IX Item "new"
.IP \fBnew_config\fR 4
.IX Item "new_config"
.IP \fBnew_date\fR 4
.IX Item "new_date"
.IP \fBnew_delta\fR 4
.IX Item "new_delta"
.IP \fBnew_recur\fR 4
.IX Item "new_recur"
.IP \fBtz\fR 4
.IX Item "tz"
.PD
Please refer to the Date::Manip::Obj documentation for these methods.
.IP \fBcalc\fR 4
.IX Item "calc"
.Vb 2
\&   $date2 = $date\->calc($delta [,$subtract]);
\&   $delta = $date\->calc($date2 [,$subtract] [,$mode]);
.Ve
.Sp
Please refer to the Date::Manip::Calc documentation for details.
.IP \fBcmp\fR 4
.IX Item "cmp"
.Vb 1
\&   $val = $date1\->cmp($date2);
.Ve
.Sp
This compares two different dates (both of which must be valid date
objects). It returns \-1, 0, or 1 similar to the cmp or <=> operators
in perl. The comparison will automatically handle time zone differences
between the two dates (i.e. they will be sorted in order as they
appear in the GMT zone).
.Sp
A warning is printed if either of the date objects does not include
a valid date.
.IP \fBcomplete\fR 4
.IX Item "complete"
.Vb 1
\&   $flag = $date\->complete([$field]);
.Ve
.Sp
This tests the date stored in the object to see if it is complete or
truncated (see below for a discussion of this).
.Sp
If no \f(CW$field\fR is passed in, it returns 1 if the date is complete, or
0 if it was truncated and default values have been supplied.
.Sp
If \f(CW$field\fR is passed in, it may be one of: m, d, h, mn, s . It will
return 1 if the value for that field was specified, or 0 if a
default was used.
.IP \fBconvert\fR 4
.IX Item "convert"
.Vb 1
\&   $err = $date\->convert([$zone]);
.Ve
.Sp
This converts the date stored in the object to a different time zone.
\&\f(CW$zone\fR can be the name of a time zone. If it is not passed in, the
date is converted to the local time zone.
.IP \fBholiday\fR 4
.IX Item "holiday"
.Vb 3
\&   $name = $date\->holiday();
\&   @name = $date\->holiday();
\&   $name = $date\->event();
.Ve
.Sp
This returns the name of the holiday if \f(CW$date\fR is a holiday. If \f(CW$date\fR
is not a holiday, undef is returned. If \f(CW$date\fR is an unnamed holiday,
an empty string is returned.
.Sp
In scalar context, holiday returns the name of one holiday that occurs
on that date (the one first defined in the config file).  In list
context, it returns all holidays on that date.
.IP \fBinput\fR 4
.IX Item "input"
.Vb 1
\&   $str = $date\->input();
.Ve
.Sp
This returns the string that was parsed to form the date.
.IP \fBis_business_day\fR 4
.IX Item "is_business_day"
.Vb 1
\&   $flag = $date\->is_business_day($checktime);
.Ve
.Sp
This returns 1 if \f(CW$date\fR is a business day.
.Sp
\&\f(CW$checktime\fR may be passed in. If it is non-zero, the time is checked to
see if the date is a business day and falls within work hours.
.IP \fBlist_holidays\fR 4
.IX Item "list_holidays"
.Vb 1
\&  @date = $date\->list_holidays([$y]);
.Ve
.Sp
This returns a list of Date::Manip::Date objects containing all dates
during a year which are holidays. The times will all be 00:00:00.
.Sp
If \f(CW$y\fR is not passed in, it will list the holidays in the same year as
the date stored in \f(CW$date\fR (if any) or in the current year otherwise.
.IP \fBlist_events\fR 4
.IX Item "list_events"
.Vb 3
\&   @list = $date\->list_events(       [$format] );
\&   @list = $date\->list_events(0      [,$format]);
\&   @list = $date\->list_events($date1 [,$format]);
.Ve
.Sp
This returns a list of events.  Events are defined in the Events section
of the config file (discussed in the Date::Manip::Holidays manual).
.Sp
In the first form, a list of all events active at the precise time
stored in \f(CW$date\fR will be returned.
.Sp
If the first argument evaluates to 0, a list of all events active at
any time during that day (Y,M,D) are returned.
.Sp
If the first argument is another date object, all events that are active
at any time between the two dates (inclusive) are returned.
.Sp
By default, the list returned is of the form:
.Sp
.Vb 4
\&   ( [START, END, NAME],
\&     [START, END, NAME],
\&     ...
\&   )
.Ve
.Sp
where START is a date object when an event starts, END is a date
object when it ends, and NAME is the name of the event. Note that
START and END are the actual start and end date of the event and may
be outside the range of dates being examined (though the event will
obviously overlap the range or it wouldn't be included in the list).
.Sp
If \f(CW$format\fR is included, it can specify an alternate format for the
output. Currently, the only supported format is named "dates" and
it returns a list in the form:
.Sp
.Vb 4
\&   ( [DATE1, NAME1a, NAME1b, ...],
\&     [DATE2, NAME2a, NAME2b, ...],
\&     ...
\&   )
.Ve
.Sp
This includes a list of all dates during the range when there is a
change in what events are active. DATE1 will always be the start of
the range being considered, and (NAME1a, NAME1b, ...) are the
list of all events that will be active at that time. At DATE2,
the list of active events changes with (NAME2a, NAME2b, ...) being
active.
.Sp
It is quite possible that a date be included which has no active
events, and in that case, the list of names will be empty.
.IP \fBnearest_business_day\fR 4
.IX Item "nearest_business_day"
.Vb 1
\&   $date\->nearest_business_day([$tomorrowfirst]);
.Ve
.Sp
This looks for the work day nearest to \f(CW$date\fR.  If \f(CW$date\fR is a work day,
it is left unmodified.  Otherwise, it will look forward or backwards
in time 1 day at a time until a work day is found.  If \f(CW$tomorrowfirst\fR
is non-zero (or if it is omitted and the config variable TomorrowFirst
is non-zero), we look to the future first.  Otherwise, we look in the
past first.  In other words, in a normal week, if \f(CW$date\fR is Wednesday,
\&\f(CW$date\fR is returned.  If \f(CW$date\fR is Saturday, Friday is returned.  If
\&\f(CW$date\fR is Sunday, Monday is returned.  If Wednesday is a holiday,
Thursday is returned if \f(CW$tomorrowfirst\fR is non-nil or Tuesday
otherwise.
.IP \fBnext_business_day\fR 4
.IX Item "next_business_day"
.PD 0
.IP \fBprev_business_day\fR 4
.IX Item "prev_business_day"
.PD
.Vb 2
\&   $date\->next_business_day($off [,$checktime]);
\&   $date\->prev_business_day($off [,$checktime]);
.Ve
.Sp
The next_business_day method sets the given date to \f(CW$off\fR (which can be
a positive integer or zero) business days in the future. The prev_business_day
method sets the date to \f(CW$off\fR business days in the past.
.Sp
First, \f(CW$date\fR is tested. If \f(CW$checktime\fR is nonzero, the date must fall
on a business date, and during business hours. If \f(CW$checktime\fR is zero,
the time check is not done, and the date must simply fall on a
business date.
.Sp
If the check fails, the date is moved to the start of the next
business day (if \f(CW$checktime\fR is nonzero) or the next business day at
the current time (if \f(CW$checktime\fR is zero). Otherwise, it is left
unmodified.
.Sp
Next, if \f(CW$off\fR is greater than 0, the day \f(CW$off\fR work days from now is
determined.
.Sp
One thing to note for the prev_business_day method is that if \f(CW$date\fR
check fails, the date is set to the next business date, exactly like
next_business_day. In other words, if \f(CW$date\fR is not a business day, the
call:
.Sp
.Vb 1
\&   $date\->prev_business_day(0 [,$checktime]);
.Ve
.Sp
moves \f(CW$date\fR forward in time instead of backward which is nonintuitive,
but you just have to think of day 0 as being the next business day if
\&\f(CW$date\fR is not a business day.
.Sp
As a result, the following two calls ALWAYS give the same result:
.Sp
.Vb 2
\&   $date\->next_business_day(0 [,$checktime]);
\&   $date\->prev_business_day(0 [,$checktime]);
.Ve
.Sp
no matter what date is stored in \f(CW$date\fR.
.IP \fBparse\fR 4
.IX Item "parse"
.Vb 1
\&   $err = $date\->parse($string [,@opts]);
.Ve
.Sp
This parses a string which should include a valid date and stores
it in the object. If the string does not include a valid date, an
error is returned. Use the err method to see the full error
message.
.Sp
A full date may include a calendar date (year, month, day), a time of
day (hour, minute, second), and time zone information. All of this can
be entered in many different formats.
.Sp
For information on valid date formats, refer to the section VALID
DATE FORMATS. For information on valid time zone information, refer
to the section VALID TIME ZONE FORMATS.
.Sp
If no time zone information is included in the date, it is treated
as being in the local time zone.
.Sp
If time zone information is included, the date will be kept in that
time zone, and all operations will be done in that time zone.  The
convert method can be used to change the time zone to the local time
zone, or to another time zone.
.Sp
Some things to note:
.Sp
All strings are case insensitive.  "December" and "DEceMBer" are
equivalent.
.Sp
When a part of the date is not given, defaults are used. This is
described below in the section "Complete vs. truncated dates and times".
.Sp
The year may be entered as 2 or 4 digits.  If entered as 2 digits, it will
be converted to a 4 digit year.  There are several ways to do this based on
the value of the YYtoYYYY config variable.  Refer to the Date::Manip::Config
documentation for more details.
.Sp
Dates are always checked to make sure they are valid.
.Sp
If any other arguments are passed in, they act as options which may
improve the speed of parsing. These include:
.Sp
.Vb 10
\&   noiso8601  Do not try to parse the
\&              date as an ISO 8601 date
\&              or time.
\&   nodow      Do not try to parse a
\&              day\-of\-week (Monday) in
\&              the string.
\&   nocommon   Do not try to parse the
\&              date using the formats
\&              in the "Common date
\&              formats" section.
\&   noother    Do not try to parse the
\&              date using the "Less common
\&              date formats" or a time
\&              using the "Other time
\&              formats".
\&   nospecial  Do not try to parse the
\&              date using the "Special
\&              date strings" formats
\&              or a time using the
\&              "Special time strings"
\&              formats, or as a
\&              combined date/time using
\&              the "Additional combined
\&              date and time" formats.
\&   nodelta    Do not treat deltas as
\&              a date relative to now.
\&   noholidays Do not parse holiday
\&              names as dates.
.Ve
.IP \fBparse_date\fR 4
.IX Item "parse_date"
.Vb 1
\&   $err = $date\->parse_date($string [,@opts]);
.Ve
.Sp
This parses a string which contains a valid date and sets the date
part of the object.
.Sp
If the object contained a valid date, the time is kept unchanged. If the
object did NOT contain a valid date, a time of 00:00:00 is used.
.Sp
\&\f(CW@opts\fR can be any of the strings described in the parse method above.
.IP \fBparse_time\fR 4
.IX Item "parse_time"
.Vb 1
\&   $err = $date\->parse_time($string [,@opts]);
.Ve
.Sp
This parses a string and sets the time portion of \f(CW$date\fR to contain it.
.Sp
If the object contained a valid date, the Y/M/D portion is left unchanged.
Otherwise, the current date is used.
.Sp
\&\f(CW@opts\fR can be 'noiso8601' or 'noother'.
.IP \fBparse_format\fR 4
.IX Item "parse_format"
.Vb 2
\&   $err          = $date\->parse_format($format,$string);
\&   ($err,%match) = $date\->parse_format($format,$string);
.Ve
.Sp
This will parse a date contained in \f(CW$string\fR based on explicit format
information contained in \f(CW$format\fR.
.Sp
If the format is invalid, \f(CW$err\fR will contain an error message.
If the format is valid, but string doesn't match, an error code
of 1 is returned.
.Sp
If called in array context, a hash will be returned containing %+.
This is primarily useful if the \f(CW$format\fR string contains some
named capture groups that you define.  This is discussed below.
.Sp
\&\f(CW$format\fR is a string containing a regular expression with some special
directives (based on the printf directives). These directives are turned
into regular expression components, and then the entire string is turned
into a regular expression which, if \f(CW$string\fR matches it, will return the
date.
.Sp
The directives available are identical to the printf directives. So,
if your \f(CW$format\fR string contains the directive '%Y', it will match a
4\-digit year.
.Sp
All of the printf directives are available here with a few caveats:
.Sp
.Vb 1
\&   %l        This directive is NOT available.
\&
\&   %b,%h,%B  These will all match a month name or abbreviation.
\&
\&   %v,%a,%A  These will all match a day name or abbreviation.
\&
\&   %z,%Z,%N  These will match any time zone string.
\&
\&   %n        Multi\-line matching is not currently supported,
\&             so this directive is not allowed.
\&
\&   %x        All format directives are converted to a regular
\&             expression and then cached (so that a format
\&             can be reused without the penalty of doing the
\&             conversion to a regular expression with each use).
\&             As a result, if you need to set the DateFormat config
\&             variable (which determines the meaning of the %x
\&             directive), it must be done before a format string
\&             containing %x is used. If the DateFormat config variable
\&             is set afterwards, the format string will reflect the
\&             old, NOT THE NEW, value of DateFormat.
.Ve
.Sp
The format string may not over-specify the date. In other words, you
may not include both a \f(CW%y\fR and \f(CW%Y\fR directive or both a \f(CW%j\fR and \f(CW%m\fR directive.
.Sp
A valid format string will specify any of the following sets of data:
.Sp
.Vb 1
\&   Required          Optional
\&
\&   M D H Mn S        Y Zone Day\-of\-week
\&   M D H Mn          Y Zone Day\-of\-week
\&   M D               Y Zone Day\-of\-week
\&   H Mn S            Zone
\&   H Mn              Zone
.Ve
.Sp
For example, if you had a date stored as:
.Sp
.Vb 1
\&   YYYY.MM\-DD
.Ve
.Sp
you could match it using the following:
.Sp
.Vb 1
\&   $date\->parse_format(\*(Aq%Y\e\e.%m\e\e\-%d\*(Aq,$string);
.Ve
.Sp
If you wanted to extract the date from an apache log line:
.Sp
.Vb 1
\&   10.11.12.13 \- \- [17/Aug/2009:12:33:30 \-0400] "GET /favicon.ico ...
.Ve
.Sp
you could use:
.Sp
.Vb 1
\&   $date\->parse_format(\*(Aq.*?\e\e[%d/%b/%Y:%T %z\e\e].*\*(Aq,$line);
.Ve
.Sp
When matching months, days, and hours, there are two directives
that could be used (for numerical versions).  For the month, you
may use \f(CW%m\fR or \f(CW%f\fR.  If your date is known to have a two-digit month,
you should use \f(CW%m\fR.  If it contains a one\- or two-digit month, you must
use \f(CW%f\fR (and it is safe to use \f(CW%f\fR for two-digit months).  Similarly,
for days, you can use \f(CW%d\fR or \f(CW%e\fR and for hours you can use \f(CW%H\fR or \f(CW%k\fR.  In
both cases, the first can only be used if you are guaranteed a 2\-digit
value.
.Sp
In your format string, you may use capture groups (or back references
to them) in the regular expression using all of the rules of normal
regular expressions. Since Date::Manip uses named capture groups
internally, it is suggested that you also use named groups.  Mixing
numbered and named groups will work... but it'll be entirely up to you
to keep track of what numbers refer to which capture groups.
.Sp
Every printf directive adds one or more named capture groups to the
regular expression.  If you use named groups in the format string,
they must not conflict with the ones used internally, or else the
date will probably not be parsed correctly.
.Sp
The following named capture groups are used internally:
.Sp
.Vb 10
\&   y
\&   m
\&   d
\&   h
\&   mn
\&   s
\&   mon_name
\&   mon_abb
\&   dow_name
\&   dow_abb
\&   dow_char
\&   dow_num
\&   doy
\&   nth
\&   ampm
\&   epochs
\&   epocho
\&   tzstring
\&   off
\&   abb
\&   zone
\&   g
\&   w
\&   l
\&   u
.Ve
.Sp
To be safe, it is suggested that any additional named capture groups
introduced by the programmer start with a capital letter.  This is
guaranteed to never conflict with any existing, or future named capture
groups.
.Sp
In order to get access to the values stored in the additional named
capture groups, the parse_format function must be called in list
context, and the %+ array will be returned as the second value.
.Sp
As an example:
.Sp
.Vb 2
\&   $string = "before 2014\-01\-25 after";
\&   ($err,%m) = $date\->parse_format(\*(Aq(?<PRE>.*?)%Y\-%m\-%d(?<POST>.*)\*(Aq,$string);
.Ve
.Sp
would return a hash (%m) with the following key/value pairs:
.Sp
.Vb 2
\&   \*(AqPRE\*(Aq  => \*(Aqbefore \*(Aq
\&   \*(AqPOST\*(Aq => \*(Aq after\*(Aq
.Ve
.IP \fBprev\fR 4
.IX Item "prev"
.PD 0
.IP \fBnext\fR 4
.IX Item "next"
.PD
The prev method changes the date to the previous (or current)
occurrence of either a day of the week, a certain time of day, or
both. The next method changes the date to the next (or current)
occurrence. The examples below illustrate the prev method, but
the next one is identical in operation.
.Sp
There are two different ways to use this method. The first is to pass
in a day of week and possibly a time:
.Sp
.Vb 1
\&   $err = $date\->prev($dow, $curr [,$time]);
.Ve
.Sp
If \f(CW$curr\fR = 0, this means to look for the previous occurrence of the day
of week, and set the time to the value passed in (or current time if
no time was passed in). The day is ALWAYS less than the current day. If
the current day is the same day of week as \f(CW$dow\fR, then the date
returned will be one week earlier.
.Sp
If \f(CW$curr\fR = 1, it means to look for the current or previous occurrence
of the day of week, and set the time to the value passed in (or 00:00:00 if
none was passed in). If the current day of week is the same as \f(CW$dow\fR, the
date will remain unchanged. Since the time is then set, the new date may
actually occur after the original date depending on the value of \f(CW$time\fR.
.Sp
If \f(CW$curr\fR = 2, it means to look for the last time (not counting now)
that the day of week at the given time occurred. The date may be the
same as the original date.
.Sp
\&\f(CW$time\fR may be a list reference of [H,MN,S], [H,MN], or [H].
.Sp
The following examples should illustrate the use of this function.
.Sp
.Vb 1
\&    Original Date = Fri Nov 22 18:15:00
\&
\&    dow      curr   time       new date
\&
\&    4 (Thu)  0/1/2  undef      Thu Nov 21 00:00:00
\&    4        0/1/2  [12,30,0]  Thu Nov 21 12:30:00
\&
\&    5 (Fri)  0/2    undef      Fri Nov 15 18:15:00
\&    5        1      undef      Fri Nov 22 18:15:00
\&
\&    5        0      [12,30,0]  Fri Nov 15 12:30:00
\&    5        1/2    [12,30,0]  Fri Nov 22 12:30:00
\&
\&    5        0/2    [19,30,0]  Fri Nov 15 19:30:00
\&    5        1      [19,30,0]  Fri Nov 22 19:30:00
.Ve
.Sp
The second way to use this method is by passing in undef for the day of
week.
.Sp
.Vb 1
\&   $err = $date\->prev(undef,$curr,$time);
.Ve
.Sp
In this case, a time is required and it must be a list reference
of 3 elements: [H, MN, S]. Any or all of the elements may be undef.
.Sp
The new date is the previous occurrence of the time.
.Sp
If you define hours, then minutes and seconds may be defined, or
default to 0 and you are looking for a previous time that the
specified time (HH:00:00) occurred (which might be as much as 24 hours
in the past).
.Sp
If hours are undefined and minutes are defined, then seconds may be
defined, or default to 0, and you are looking for the last time the
minutes/seconds (MN:SS) appeared on the digital clock, which will be
sometime in the past hour.
.Sp
Finally, if hours and minutes are undefined, seconds must be defined
(or default to zero) and the last time that that second occurred will
be returned (which will be sometime in the past minute).
.Sp
If \f(CW$curr\fR is non-zero, the current time is returned if it matches the
criteria passed in, so the returned value will be now or in the past.
If \f(CW$curr\fR is zero, the time returned will definitely be in the past.
.Sp
.Vb 1
\&    DATE = Fri Nov 22 18:15:00
\&
\&    curr  hr     min    sec      returns
\&    0/1   18     undef  undef    Nov 22 18:00:00
\&    0/1   18     30     0        Nov 21 18:30:00
\&    0     18     15     undef    Nov 21 18:15:00
\&    1     18     15     undef    Nov 22 18:15:00
\&    0     undef  15     undef    Nov 22 17:15:00
\&    1     undef  15     undef    Nov 22 18:15:00
.Ve
.IP \fBprintf\fR 4
.IX Item "printf"
.Vb 2
\&   $out = $date\->printf($in);
\&   @out = $date\->printf(@in);
.Ve
.Sp
This takes a string or list of strings which may contain any number of
special formatting directives. These directives are replaced with
information contained in the date. Everything else in the string is
returned unmodified.
.Sp
A directive always begins with '%'. They are described in the section
below in the section PRINTF DIRECTIVES.
.IP \fBsecs_since_1970_GMT\fR 4
.IX Item "secs_since_1970_GMT"
.Vb 1
\&   $secs = $date\->secs_since_1970_GMT();
.Ve
.Sp
This returns the number of seconds that have elapsed since Jan 1, 1970
00:00:00 GMT (negative if the date is earlier).
.Sp
The reverse is also allowed:
.Sp
.Vb 1
\&   $err = $date\->secs_since_1970_GMT($secs);
.Ve
.Sp
which sets the date to \f(CW$secs\fR seconds from Jan 1, 1970 00:00:00 GMT in
the local time zone.
.IP \fBset\fR 4
.IX Item "set"
.Vb 1
\&   $err = $date\->set($field,@vals [,$isdst]);
.Ve
.Sp
This explicitly sets one or more fields in a date.
.Sp
\&\f(CW$field\fR can be any of the following:
.Sp
.Vb 1
\&   $field   @vals
\&
\&   zone     [ZONE]         ZONE can be any zone or alias
\&
\&   zdate    [ZONE,]DATE    sets the zone and entire date
\&
\&   date     DATE           sets the entire date
\&
\&   time     TIME           sets the entire time
\&
\&   y        YEAR           sets one field
\&   m        MONTH
\&   d        DAY
\&   h        HOUR
\&   mn       MINUTE
\&   s        SECOND
.Ve
.Sp
Here, DATE is a list reference containing [Y,M,D,H,MN,S] and TIME is
a list reference containing [H,MN,S].
.Sp
ZONE is optional (it defaults to the local zone as defined either by
the system clock, or the SetDate or ForceDate config variables). If it
is passed in, it can be any zone name, abbreviation, or offset. An
offset can be expressed either as a valid offset string, or as a list
reference.  Refer to the join/split functions of Date::Manip::Base for
information on valid offset strings.
.Sp
An optional last argument is \f(CW$isdst\fR (which must be 0 or 1) is included
when setting a date which could be in either standard time or daylight
saving time. It is ignored in all other situations. If it is
not included, and the resulting date could be in either, it will
default to standard time.
.Sp
The \f(CW$date\fR object must contain a valid date (unless the entire date
is being set with \f(CW$field\fR set to either "zdate" or "date").
.Sp
If \f(CW$field\fR is "zone", the time zone of the date will be set. If ZONE is
not passed in, it will be set to the local time zone.  When setting the
time zone, no conversion is done! Whatever date and time is stored in
the \f(CW$date\fR object prior to this remains unchanged... except it will
be that date and time in the new time zone.
.Sp
If \f(CW$field\fR is "zdate", the entire date and time zone is set. If ZONE is
not passed in, it is set to the local time zone.
.Sp
If \f(CW$field\fR is "date", the entire date will be set, but the time zone
of the date will not be changed.
.Sp
If \f(CW$field\fR is "time", or one of the individual fields, only those
fields will be modified.
.Sp
An error is returned if an invalid argument list is passed in, or if
the resulting date is checked and found to be invalid.
.IP \fBvalue\fR 4
.IX Item "value"
.Vb 2
\&   $val = $date\->value([$type]);
\&   @val = $date\->value([$type]);
.Ve
.Sp
These return the value of the date stored in the object.
.Sp
In scalar context, a printable string in the form YYYYMMDDHH:MN:SS
is returned. In list context, a list is returned of (Y,M,D,H,MN,S).
.Sp
If \f(CW$type\fR is omitted, the date is returned in the time zone it was
parsed in.
.Sp
If \f(CW$type\fR is "local", it is returned in the local time zone (which
is either the system time zone, or the zone specified with the
SetDate or ForceDate config variables).
.Sp
If \f(CW$type\fR is "gmt", the date is returned in the GMT time zone.
.Sp
An empty string or list is returned in the case of an error (and
an error code is set).
.IP \fBweek_of_year\fR 4
.IX Item "week_of_year"
.Vb 1
\&   $wkno = $date\->week_of_year([$first]);
.Ve
.Sp
This figures out the week number for the date stored in \f(CW$date\fR.  It uses
the config variables FirstDay and Week1ofYear to determine this.  For
historical reasons, an argument \f(CW$first\fR may be passed in.  It must be
between 1 and 7 and refers to the first day of the week and overrides
whatever the FirstDay variable is set to.
.Sp
NOTE: This routine should only be called in rare cases.  Use printf
with the \f(CW%W\fR, \f(CW%U\fR, \f(CW%J\fR, \f(CW%L\fR formats instead as that will always return the
correct values for week and year.
.Sp
This routine returns a week between 0 and 53 which must then be
"fixed" to get into the ISO 8601 weeks from 1 to 53.  A date which
returns a week of 0 actually belongs to the last week of the previous
year.  A date which returns a week of 53 may belong to the first week
of the next year.
.SH "ISSUES WITH PARSING DATES"
.IX Header "ISSUES WITH PARSING DATES"
The following issues may occur when parsing dates that should be
understood to make full use of this module.
.IP "\fBComplete vs. truncated dates and times\fR" 4
.IX Item "Complete vs. truncated dates and times"
Date formats are either complete or truncated. A complete date fully
specifies the year, month, and day and a complete time fully specifies
the hour, minute, and second.
.Sp
It should be understood that in many instances, the information may be
implied rather than explicitly stated, but it is still treated as
complete.
.Sp
For example, the date "January 3" is complete because it implies the
current year.
.Sp
A truncated calendar date or time does not include information about
some of the fields. Date::Manip will never work with a partial date or
time, so defaults will be supplied.
.Sp
For example, the date "2009\-01" is missing a day field, so a default
will be used. In this case, the day will be the 1st, so this is
equivalent to "Jan 1st 2009". If only the year is given, it will
default to Jan 1.
.Sp
If the time, or any of it's components is missing, they default to
00. So the time "12:30" and "12:30:00" are equivalent.
.Sp
The "complete" method can be used to check what type of date was
parsed, and which values were specified (either explicitly or implied)
and which were provided as a default. It should be noted that there
is no way to differentiate between an explicit and implied value.
.Sp
A string with a date and/or time may consist of any of the following:
.Sp
.Vb 3
\&   a complete date and a time (complete or truncated)
\&   a truncated date with no time
\&   a time (complete or truncated) with no date
.Ve
.Sp
In other words, the date "Jan 2009 12:30" is not valid since it consists
of a time with a truncated date.
.SH "VALID TIME ZONE FORMATS"
.IX Header "VALID TIME ZONE FORMATS"
When specifying a time zone, it can be done in three different ways.
One way is to specify the actual time zone. The second is to supply
a valid time zone abbreviation. The third is to specify an offset (with
an optional abbreviation). The following dates illustrate the these
formats.
.PP
The timezone information always follows the time immediately, and may
only be included if a time is included. The following examples use
an ISO 8601 format for the date/time, but any of the other date and
time formats may be used.
.PP
The first way to specify the time zone is to specify it by complete name
(or using one of the standard aliases):
.PP
.Vb 1
\&   2001\-07\-01\-00:00:00 America/New_York
.Ve
.PP
Although this is unambiguous when it comes to determining the time zone,
the time is ambiguous in most zones for one hour of the year. When
a time change occurs during which the clock is moved back, the same
wall clock time occurs twice.
.PP
For example, in America/New_York, on Sunday, Nov 2, 2008, at 02:00 in
the morning, the clock was set back to 01:00. As a result, the date
Nov 2, 2008 at 01:30 is ambiguous. It is impossible to determine if
this refers to the 01:30 that occurred half an hour before the time
change, or the one 30 minute after the change.
.PP
In practice, if this form is used, the date will be assigned to
standard time, meaning that there will be some times (typically 1 hour
per year) which cannot be expressed this way. As such, this method is
discouraged.
.PP
The second way to specify the time zone, which is the most common, is
to use a time zone abbreviation:
.PP
.Vb 1
\&   2001\-07\-01\-00:00:00 EDT
.Ve
.PP
Unfortunately, the abbreviation does not uniquely determine the
time zone except in a few cases. In order to assign a time zone,
Date::Manip will refer to a list of all time zones which use the
abbreviation.  They will be tested, in the order given in the
Date::Manip::Zones documentation, and the first match (i.e. the one in
which the given date/time and abbreviation are valid) determines the
time zone which will be used. A great deal of effort has been made to
ensure that the most likely time zone will be obtained (i.e. the most
common time zones are tested before less common ones), so in most
cases, the desired results will be obtained.
.PP
If the default order does not yield the desired time zone, the order of
testing can be modified using the abbrev method described in the
Date::Manip::TZ documentation.
.PP
Although the time zone is ambiguous, the date is not, since only
time zones for which the date are valid will be used.
.PP
The third way to specify the time zone is by specifying an offset and
an optional abbreviation:
.PP
.Vb 5
\&   2001\-07\-01\-00:00:00 \-04
\&   2001\-07\-01\-00:00:00 \-0400
\&   2001\-07\-01\-00:00:00 \-040000
\&   2001\-07\-01\-00:00:00 \-04:00
\&   2001\-07\-01\-00:00:00 \-04:00:00
\&
\&   2001\-07\-01\-00:00:00 \-04 (EDT)
\&   2001\-07\-01\-00:00:00 \-0400 (EDT)
\&   2001\-07\-01\-00:00:00 \-040000 (EDT)
\&   2001\-07\-01\-00:00:00 \-04:00 (EDT)
\&   2001\-07\-01\-00:00:00 \-04:00:00 (EDT)
\&
\&   2001\-07\-01\-00:00:00 \-04 EDT
\&   2001\-07\-01\-00:00:00 \-0400 EDT
\&   2001\-07\-01\-00:00:00 \-040000 EDT
\&   2001\-07\-01\-00:00:00 \-04:00 EDT
\&   2001\-07\-01\-00:00:00 \-04:00:00 EDT
.Ve
.PP
As with the abbreviation, the offset is almost never sufficient to
uniquely determine the time zone (and it is not even guaranteed that
both the offset and abbreviation will, though in practice, it is
probably sufficient). In this instance, the time zone will be
determined by testing all time zones which have the given offset (and
abbreviation if it is included) until one is found which matches the
pieces of information supplied. For more information about how this
testing is done, refer to the def_zone method of the Date::Manip::TZ
documentation.
.SH "VALID DATE FORMATS"
.IX Header "VALID DATE FORMATS"
There are several categories of date formats supported by Date::Manip.
These are strings which specify only the year/month/day fields.
.PP
These formats explicitly set the date, but not the time. These formats
may be combined with a time string (as specified below) to set both
the date and time. If this is not done, the default time is determined
by the DefaultTime config variable.
.IP "\fBISO 8601 dates\fR" 4
.IX Item "ISO 8601 dates"
The preferred date formats are those specified by ISO 8601. The
specification includes valid calendar date and valid time formats.
Date::Manip will handle all of these formats, but does not require
that the dates rigidly adhere to the specification since the ultimate
goal of Date::Manip is to handle dates as they are represented in
real life and some common variations exist which are similar to, but
not identical to, those from the specification.
.Sp
A calendar date includes the following fields:
.Sp
.Vb 10
\&   CC    2\-digit representation of the century
\&   YY    2\-digit representation of the year in
\&         a century
\&   MM    2\-digit representation of a month
\&   DD    2\-digit representation of a day of month
\&   DoY   3\-digit representation of a day of year
\&         (001\-366)
\&   Www   the character "W" followed by a 2\-digit
\&         week of the year (01\-53)
\&   D     the day of the week (1\-7)
.Ve
.Sp
The following date formats are considered complete by Date::Manip. In
the following, the date Thu Mar 5 2009 is used as an example.  This is
the 64th day of the year. Thu is the 4th day of the week.  The week
starting Mon, Mar 2 is the 10th week of the year (according the the
ISO 8601 definition). Obviously, some of the formats are only valid
when used at some times. For example, the format \-\-MMDD refers to a
month and day in the current year, so the date Mar 5, 2009 can only be
specified using this format during 2009.
.Sp
.Vb 1
\&   Format      Notes   Examples
\&
\&   CCYYMMDD            20090305
\&   CCYY\-MM\-DD          2009\-03\-05
\&
\&   YYMMDD      1,2,4   090305
\&   YY\-MM\-DD            09\-03\-05
\&
\&   \-YYMMDD     3,4     \-090305
\&   \-YY\-MM\-DD           \-09\-03\-05
\&
\&   \-\-MMDD      1       \-\-0305
\&   \-\-MM\-DD             \-\-03\-05
\&
\&   \-\-\-DD       1       \-\-\-05
\&
\&
\&   CCYYDoY             2009064
\&   CCYY\-DoY            2009\-064
\&
\&   YYDoY       1,4     09064
\&   YY\-DoY              09\-064
\&
\&   \-YYDoY      3,4     \-09064
\&   \-YY\-DoY             \-09\-064
\&
\&   \-DoY        1       \-064
\&
\&
\&   CCYYWwwD            2009W104
\&   CCYY\-Www\-D          2009\-W10\-4
\&
\&   YYWwwD      1,4     09W104
\&   YY\-Www\-D            09\-W10\-4
\&
\&   \-YYWwwD     3,4     \-09W104
\&   \-YY\-Www\-D           \-09\-W10\-4
\&
\&   \-YWwwD      1       \-9W104
\&   \-Y\-Www\-D            \-9\-W10\-4
\&                       Y is the year (0\-9) in
\&                       current decade
\&
\&   \-WwwD       1       \-W104
\&   \-Www\-D              \-W10\-4
\&
\&   \-W\-D        1       \-W\-4
\&                       D is day (1\-7) in
\&                       current week
\&
\&   \-\-\-D        1       \-\-\-4
\&                       same as \-W\-D
.Ve
.Sp
The following date formats are truncated:
.Sp
.Vb 1
\&   CCYY\-MM     2       2009\-03   (2009\-03\-01)
\&
\&   CCYY                2009      (2009\-01\-01)
\&
\&   CC          2       20        (2000\-01\-01)
\&
\&   \-YYMM       4       \-0903
\&   \-YY\-MM              \-09\-03
\&
\&   \-YY         4       \-09
\&
\&   \-\-MM                \-\-03
\&
\&   CCYYWww             2009W10
\&   CCYY\-Www            2009\-W10
\&
\&   YYWww       4       09W10
\&   YY\-Www              09\-W10
\&
\&   \-YYWww      3,4     \-09W10
\&   \-YY\-Www             \-09\-W10
\&
\&   \-Www                \-W10
.Ve
.Sp
Notes:
.Sp
1  These formats are considered truncated in the standard, but since
   they do include (or imply, using the current date for defaults)
   all of the fields, and since they do not introduce any parsing
   complexities, the standard is relaxed, and they are treated as
   complete.
.Sp
2  These formats are treated differently than in Date::Manip 5.xx as
   described below.
.Sp
3  These formats are not defined in the ISO 8601 spec, but
   are added for the sake of completeness since they do not
   add any parsing incompatibilities.
.Sp
4  Formats where the century is not given are described as a year in
   the current century in the specification. Date::Manip treats this
   more generically using the YYtoYYYY config variable. This will be
   used to determine how to determine the full year.
.Sp
Date::Manip 5.xx handled ISO 8601 dates in a less rigid fashion, and
deviated from the specification in several formats. As of 6.00, the
specification is followed much more closely so that all of the date
formats included in it should produce valid dates.  This changes, in a
backwards incompatible way, the way a few strings will be interpreted
as dates.
.Sp
As of 6.00, a two-digit date will be treated as CC. Previously, it
was treated as YY.
.Sp
A six-digit date will be treated as YYMMDD. Previously, it was treated
as YYYYMM.
.Sp
Previously, dashes were treated as optional in many cases. According
to the specification, dates may be written in expanded form (with all
dashes present) or abbreviate form (with no dashes). As of 6.00, this
is the behavior, so the formats: YYMMDD and YY-MM-DD are allowed, as
per the specification, but the format YY-MMDD is NOT allowed (though
it was previously).
.Sp
The Www-D formats require a bit of explanation.  According to the
specification, the date:
.Sp
.Vb 1
\&   1996\-w02\-3
.Ve
.Sp
refers to the day with an ordinal number of 3 within the calendar week
in the 2nd week of 1996.
.Sp
In the specification, the days of the week are numbered from 1 to 7
(Monday to Sunday), and the week always begins on Monday, so day 1
(Monday) is always the first day of the week, day 2 (Tuesday) is
always the second day of the week, etc.
.Sp
In Date::Manip, the constraint that the week must start with Monday is
relaxed, allowing the week to begin with Sunday (a far more common
start of the week in calendars, at least in some parts of the world).
.Sp
This presents a problem though in that the above date could be
interpreted as Wednesday (day 3) of the 2nd week of 1996, or as the
3rd day of the 2nd week of 1996 (which would normally be Wednesday,
but would be Tuesday if the week begins on Sunday).
.Sp
As of Date::Manip 6.00, the above date will be interpreted as the 3rd
day of the 2nd week. This is a reversal from Date::Manip 5.xx, but I
believe is what the specification would require. For more information,
refer to the Date::Manip::Changes document.
.IP "\fBCommon date formats\fR" 4
.IX Item "Common date formats"
Date::Manip supports a number of common date formats. The following fields
may be included in a date:
.Sp
.Vb 7
\&  YY    2\-digit representation of the year
\&  YYYY  4\-digit representation of the year
\&  M     1\- or 2\- digit representation of the month
\&  MM    2\-digit representation of the month
\&  D     1\- or 2\- digit representation of the day
\&  DD    2\-digit representation of the day
\&  mmm   The abbreviated or full month name (i.e. Jan)
.Ve
.Sp
The following date formats are supported:
.Sp
.Vb 1
\&   Format      Notes   Examples
\&
\&   M/D         1,2,3   3/5
\&   M/D/YY      1       3/5/09
\&   M/D/YYYY    1       3/5/2009
\&
\&   YYYY/M/D            2009/3/5
\&
\&   mmm/D               Mar/5
\&   mmm/D/YY            Mar/5/09
\&   mmm/D/YYYY          Mar/5/2009
\&   D/mmm               5/Mar
\&   D/mmm/YY            5/Mar/09
\&   D/mmm/YYYY          5/Mar/2009
\&   YYYY/mmm/D          2009/Mar/5
\&
\&   mmmD                Mar5
\&   mmmDDYY     4       Mar0509
\&   mmmDDYYYY           Mar052009
\&   Dmmm                5Mar
\&   DmmmYY              5Mar09
\&   DmmmYYYY            5Mar2009
\&   YYYYmmmD            2009Mar5
\&
\&   mmmD YY             Mar5 09
\&   mmmD YYYY           Mar5 2009
\&   Dmmm YY             5Mar 09
\&   Dmmm YYYY           5Mar 2009
\&
\&   mmm/D YY            Mar/5 09
\&   mmm/D YYYY          Mar/5 2009
\&   D/mmm YY            5/Mar 09
\&   D/mmm YYYY          5/Mar 2009
\&
\&   YY   mmmD           09   Mar5
\&   YYYY mmmD           2009 Mar5
\&   YY   Dmmm           09   5Mar
\&   YYYY Dmmm           2009 5Mar
\&
\&   YY   mmm/D          09   Mar/5
\&   YYYY mmm/D          2009 Mar/5
\&   YY   D/mmm          09   5/Mar
\&   YYYY D/mmm          2009 5/Mar
\&
\&   YYYY:MM:DD          2010:01:15 (EXIF format)
\&
\&   mmmYYYY     4       Jun 2010
\&   YYYYmmm     4       2010 June
\&   mmm/YYYY    4       Jun/2010
\&   YYYY/mmm    4       2010/Jun
.Ve
.Sp
In the formats above, the slash (/) can be replace by any of the valid
separators: whitespace, slash (/), period (.), or dash (\-). The dash,
though allowed, is discouraged since it may conflict with an ISO 8601
format.  For example, the format MM/DD/YY is just fine, but MM-DD-YY
does not work since it conflicts with YY-MM-DD.  To be safe, if "\-" is
used as a separator in a non-ISO format, they should be turned into
"/" before calling the Date::Manip routines or you should use the 'noiso8601'
option with the \fBparse\fR or \fBparse_date\fR methods.
.Sp
No matter what separator is used, the same separator must be used
throughout the date. For example, MM/DD/YY is valid and MM.DD.YY is
also valid, but MM/DD.YY is NOT valid.
.Sp
Notes:
.Sp
1  With these formats, Americans tend to write month first, but many
   other countries tend to write day first.  The latter behavior can be
   obtained by setting the config variable DateFormat to something other
   than "US".
.Sp
2  The dot (.) separator may not be used in the M/D format since it
   will be interpreted as the H12,H+ format described below.
.Sp
3  The M/D format should not use the period (.) separator as that will
   incorrectly match the HH,H+ time format.
.Sp
4  Historically, I have not supported partial dates (i.e. dates that
   were not fully specified), but it has been argued that something like
   'Jun 1910' would be interpreted by almost everyone as a day in June
   of 1910 instead of June 19, 2010.  And it has been shown that in
   some applications, dates are specified in that way.  I have added the
   new config variable Format_MMMYYYY which will change this.  If this
   variable is not set, the formats allowed are:
.Sp
.Vb 1
\&      mmmDDYY
\&
\&   If it is set, the formats allowed are:
\&
\&      mmmYYYY
\&      YYYYmmm
\&
\&   The day of week may not be included with these formats.  When
\&   parsing a full date/time, if Format_MMMYYYY is set to \*(Aqfirst\*(Aq,
\&   it returns the 1st of the month at midnight.  If it is set to
\&   \*(Aqlast\*(Aq, it returns the last day at 23:59:59.  If parsing only
\&   only a date, it will be set to the first or last day of the
\&   month at midnight.
.Ve
.Sp
These formats explicitly set the date, but not the time. The default
time is determined by the DefaultTime config variable.
.IP "\fBLess common date formats\fR" 4
.IX Item "Less common date formats"
The following formats are also supported by Date::Manip:
.Sp
.Vb 4
\&   DoW
\&        The day of week of the current week
\&           Friday
\&           Friday at 12:40
\&
\&   MMM Nth [YYYY]
\&   Nth MMM [YYYY]
\&   YYYY MMM Nth
\&   YYYY Nth MMM
\&        Dec 1st 1970
\&        1st Dec 1970
\&        1970 Dec 1st
\&        1970 1st Dec
\&
\&   next/prev DoW
\&        The next or last occurrence of DoW
\&           next Friday
\&           last Friday at 12:40
\&
\&   next/last week/month/year
\&        The day one week/month/year from now
\&        or in the past
\&           next week
\&           last month at 15:00
\&
\&   last day in MMM [YYYY]
\&        The last day of the month
\&           last day in October
\&           last day in October 1996
\&
\&   last DoW in MMM [YYYY]
\&        The last DoW in the month
\&           last Tuesday in October
\&           last Tuesday in October 1996
\&
\&   last DoW in YYYY
\&        The last DoW in the year
\&           last Tuesday in 1997
\&
\&           NOTE: "last DoW" doesn\*(Aqt work in
\&           English since the word "last"
\&           is used for both this expression
\&           and for "prev DoW", which gets
\&           parsed first. "last DoW" MAY
\&           work in other languages.
\&
\&   Nth DoW in MMM [YYYY]
\&        The Nth DoW in the month
\&           3rd Tuesday in October
\&           3rd Tuesday in October 1996
\&
\&   Nth DoW [YYYY]
\&        The Nth DoW in the year
\&           22nd Sunday
\&           22nd Sunday in 1996
\&
\&   Nth day in MMM [YYYY]
\&        The Nth day of the month
\&           1st day of February
\&           1st day of February 2012
\&
\&   DoW week
\&        British: same as "in 1 week on DoW"
\&           Monday week
\&
\&   DoW week N [YYYY]
\&   Dow Nth week [YYYY]
\&        Sunday week 22
\&        Sunday 22nd week
\&           These refer to the day of week
\&           of the Nth week of the year.
\&
\&   Nth
\&        12th
\&           This refers to the Nth day of the
\&           current month.
.Ve
.Sp
Note that the formats "Sunday week 22" and "22nd Sunday" give
different behaviors.  "Sunday week 22" returns the Sunday of the 22nd
week of the year based on how week 1 is defined.  ISO 8601 defines
week one to contain Jan 4, so "Sunday week 1" might be the first or
second Sunday of the current year, or the last Sunday of the previous
year.  "22nd Sunday" gives the actual 22nd time Sunday occurs in a
given year, regardless of the definition of a week.
.IP "\fBSpecial date strings\fR" 4
.IX Item "Special date strings"
Most languages have strings which can be used to specify the date (relative
to today). In English, these include the strings:
.Sp
.Vb 3
\&   today
\&   tomorrow
\&   yesterday
.Ve
.Sp
There is also support for the British formats:
.Sp
.Vb 3
\&   today week
\&   tomorrow week
\&   yesterday week
.Ve
.Sp
which refer to one week after today/tomorrow/yesterday respectively.
.Sp
Other languages have similar strings.
.IP \fBHolidays\fR 4
.IX Item "Holidays"
You can parse holiday names as dates (including timezones).  For example:
.Sp
.Vb 5
\&   Christmas
\&   Christmas 2010
\&   Christmas 2010 at noon
\&   Christmas 2010 at noon PST
\&   Saturday Christmas 2010 at noon
.Ve
.PP
In all of the formats (except for ISO 8601 formats), the day of week
("Friday") can be entered anywhere in the date and it will be checked
for accuracy.  In other words,
.PP
.Vb 1
\&  "Tue Jul 16 1996 13:17:00"
.Ve
.PP
will work but
.PP
.Vb 1
\&  "Jul 16 1996 Wednesday 13:17:00"
.Ve
.PP
will not (because Jul 16, 1996 is Tuesday, not Wednesday).
.SH "A NOTE ABOUT FOREIGN LANGUAGE DATES"
.IX Header "A NOTE ABOUT FOREIGN LANGUAGE DATES"
Although Date::Manip has some support for parsing dates in foreign
languages, it must be noted that the formats supported are largely
based on English equivalents.
.PP
There are probably many different dates that are perfectly valid, and
in common usage, in other languages which do not have an equivalent in
the English language, and unfortunately, Date::Manip will probably not
parse these.
.PP
You are free to send these to me, and I'll see if there is a way to
add them in, but I do not guarantee anything.  Without having a
full-blown language parser (or at least the portion of the language
that is devoted to calendar and time), most of these formats will
simply not be supportable.
.SH "VALID TIME FORMATS"
.IX Header "VALID TIME FORMATS"
There are several categories of time formats supported by Date::Manip.
These are strings which specify only the hour/minute/second fields.
.IP "\fBISO 8601 times\fR" 4
.IX Item "ISO 8601 times"
A time may be also be complete or truncated.  Again, Date::Manip
treats some formats as complete even though the specification calls
them truncated.
.Sp
A time may include the following fields:
.Sp
.Vb 6
\&   HH    2\-digit representation of the hour
\&   MN    2\-digit representation of the minutes
\&   SS    2\-digit representation of the seconds
\&   H+    1+ digit representation of fractional hours
\&   M+    1+ digit representation of fractional minutes
\&   S+    1+ digit representation of fractional seconds
.Ve
.Sp
The following time formats are considered complete by Date::Manip. The time
12:30:15 will be expressed in the examples.
.Sp
.Vb 1
\&   Format      Notes   Examples
\&
\&   HHMNSS      2       123015
\&
\&   HH:MN:SS            12:30:15
\&
\&   HHMNSS,S+           123015,5
\&   HH:MN:SS,S+         12:30:15,5
\&                       Fractional seconds are ignored
\&
\&   HHMN,M+             1230,25
\&   HH:MN,M+            12:30,25
\&                       This is 12:30:00 + 0.25 minutes
\&
\&   HH,H+               12,5
\&                       This is 12:00:00 + 0.5 hours, so
\&                       this is equivalent to 12:30:00
\&
\&   \-MNSS       1       \-3015
\&   \-MN:SS              \-30:15
\&
\&   \-\-SS        1       \-\-15
\&
\&   \-MNSS,S+    1       \-3015,5
\&   \-MN:SS,S+           \-30:15,5
\&
\&   \-MN,M+      1       \-30,25
\&
\&   \-\-SS,S+     1       \-\-15,5
\&
\&   HHMN        3       1230
\&   HH:MN               12:30
.Ve
.Sp
The following time formats are truncated:
.Sp
.Vb 1
\&   HH                  12
\&
\&   \-MN                 \-30
.Ve
.Sp
Notes:
.Sp
1  These formats are considered truncated in the standard, but since
   they do include (or imply, using the current time for defaults) all of
   the fields, and since they do not introduce any parsing complexities,
   the standard is relaxed, and they are treated as complete.
.Sp
2  The HHMNSS format will not be correctly parsed since it is impossible
   to distinguish between it and YYMMDD. In order to parse an all-digit
   time, add the string ",0" to the end to force it to be interpreted
   as a time or include time zone information (either a zone name or
   abbreviation... an offset will not work in this case).
.Sp
3  The HH:MN format will be treated as complete, even though it is
   incomplete due to missing the seconds. In real life, expressing
   a time in the HH:MN format is very common, and is regarded as complete,
   and might include time zone information.
.Sp
ISO 8601 times may be followed by a time zone unless they are truncated.
Truncated times may not include a timezone.  Date::Manip relaxes the
constraints placed on the time zone format and allows any of the
methods used to specify the time zone including time zone name, abbreviation,
or offset. The time zone may be separated from the time by a space, but
it is not required.
.Sp
Another constraint that is relaxed is that the fractional part may be
specified using a period. In other words, the following are equivalent:
.Sp
.Vb 2
\&   12:30,25
\&   12:30.25
.Ve
.Sp
It should be noted (as it is in the specification) that using a
negative time zone offset may cause confusion. In addition to visually
confusing, it may not be parsed correctly. For example, the time:
.Sp
.Vb 1
\&   123005\-0300
.Ve
.Sp
may not be parsed correctly. When using an offset time zone, you
should always use the colon separators in the time:
.Sp
.Vb 1
\&   12:30:05\-0300
.Ve
.IP "\fBOther time formats\fR" 4
.IX Item "Other time formats"
A time may include any of the following fields:
.Sp
.Vb 8
\&   H24   1\- or 2\-digit representation of the hour (0\-23)
\&   H12   1\- or 2\-digit representation of the hour (1\-12)
\&   MN    2\-digit representation of the minutes
\&   SS    2\-digit representation of the seconds
\&   H+    1+ digit representation of fractional hours
\&   M+    1+ digit representation of fractional minutes
\&   S+    1+ digit representation of fractional seconds
\&   AM    A language specific AM/PM string
.Ve
.Sp
The following time formats are accepted:
.Sp
.Vb 1
\&   Format              Examples
\&
\&   H24:MN:SS           17:30:15
\&   H12:MN:SS AM        5:30:15 PM
\&   H12:MN:SS
\&
\&   H24:MN:SS,S+        17:30:15,5
\&   H12:MN:SS,S+ AM     5:30:15,5 PM
\&   H12:MN:SS,S+        Fractional seconds are ignored
\&
\&   H24:MN,M+           17:30,25
\&   H12:MN,M+ AM        5:30,25 PM
\&   H12:MN,M+           This is 17:30:00 + 0.25 minutes
\&
\&   H24,H+              17,5
\&   H12,H+ AM           5,5 PM
\&   H12,H+              This is 17:00:00 + 0.5 hours, so
\&                       this is equivalent to 17:30:00
\&
\&   H24:MN              17:30
\&   H12:MN AM           5:30 PM
\&   H12:MN
\&
\&   H12 AM              5 PM
.Ve
.Sp
The fractional part may be specified using a comma or a period.
Fractional seconds may also be separated using a colon.  A
language specific fractional separator may also be available for
some languages.
.Sp
In other words, the following are equivalent:
.Sp
.Vb 3
\&   12:30:20,25
\&   12:30:20.25
\&   12:30:20:25
.Ve
.Sp
Some languages have alternate H:MN and MN:S separators. For example,
one H:MN separator in French is 'h' (the MN:S separator is still a
colon), so the following are equivalent:
.Sp
.Vb 2
\&   12:30:00
\&   12h30:00
.Ve
.Sp
Time zone information can be included immediately following the time.
It can be separated by whitespace from the time, or it can be
immediately adjacent.
.IP "\fBSpecial time strings\fR" 4
.IX Item "Special time strings"
Different languages may have some words which can be used to specify a
certain time of day. In English, for example, the following words are
equivalent to the time listed:
.Sp
.Vb 2
\&   noon        12:00:00
\&   midnight    00:00:00
.Ve
.Sp
So, the following are equivalent:
.Sp
.Vb 2
\&   Jan 2 2009 at noon
\&   Jan 2 2009 12:00:00
.Ve
.Sp
There were two possible ways to interpret midnight. One was at the
start of the day (00:00:00) and the other was at the end of the day
(24:00:00 which would actually mean at 00:00:00 of the following day).
The first has been used to maintain backwards compatibility with
Date::Manip 5.xx .
.Sp
Other languages have similar strings.
.PP
In most languages, a word similar to "at" may precede the time (this
does NOT apply to ISO 8601 time formats). This word (which must be
separate from all other parts of the date with whitespace) is
optional, and the following are equivalent:
.PP
.Vb 2
\&   12:30
\&   at 12:30
.Ve
.PP
The times "12:00 am", "12:00 pm", and "midnight" are not well defined.
Date::Manip uses the following convention:
.PP
.Vb 2
\&  midnight = 12:00am = 00:00:00
\&  noon     = 12:00pm = 12:00:00
.Ve
.PP
and the day goes from 00:00:00 to 23:59:59.  In other words, midnight is the
beginning of a day rather than the end of one.  The time 24:00:00 is also
allowed (though it is automatically transformed to 00:00:00 of the following
day). This gives the unusual result of parsing:
.PP
.Vb 1
\&  Wed Feb 8 2006 24:00:00
.Ve
.PP
which gives the date of:
.PP
.Vb 1
\&  Thu Feb 9 2006 00:00:00
.Ve
.SH "VALID COMBINED DATE AND TIME FORMATS"
.IX Header "VALID COMBINED DATE AND TIME FORMATS"
There are several categories of strings which specify both the date and
time. These include the following:
.IP "\fBISO 8601 combined date and time\fR" 4
.IX Item "ISO 8601 combined date and time"
A combined ISO 8601 date and time is a string containing a complete
ISO 8601 date and a complete or truncated ISO 8601 time.  It may
also include a timezone, provided a complete time is included.
.Sp
Date::Manip relaxes the restrictions on how the two are combined.  The
time may be separated from the date by space, dash, or the letter T,
or the two may be joined with nothing separating them.
.Sp
When the time immediately follows the date, or when the two are
separated by a dash, the resulting string MUST be
unambiguous. Provided the date includes all of the dashes in it
(i.e. YY-MM-DD instead of YYMMDD), it is rare that there is any
ambiguity. If the date does not include dashes, the strings may be
ambiguous, and in this case, separating the date and time with a space
or the letter T is useful (and perhaps necessary) to correctly
interpret the string.
.Sp
The DoY formats should always be separated from the time by
something. They are visually confusing if they are not separated from
the time.
.Sp
Time zone information can be included immediately following a complete
time.  It may not be included if no time is given, or if a truncated
time is included. The time zone may be separated from the time with
whitespace, or it can be immediately adjacent to it (since the ISO
8601 specification allows it in some cases).
.IP "\fBNon-ISO 8601 combined date and time\fR" 4
.IX Item "Non-ISO 8601 combined date and time"
A date from any of the non-ISO 8601 formats above may be combined with
any of the non-ISO 8601 time formats above in any combination to form
a valid combined date and time.
.IP \fBDeltas\fR 4
.IX Item "Deltas"
Dates are often specified in terms of a delta from "now". For example,
"in 2 days".
.Sp
Most valid deltas can be used to specify a date, and the date is defined
as that delta added to "now". Refer to the Date::Manip::Delta documentation
for a list of valid delta formats.
.Sp
If the delta itself does not include a time part, the time may be specified
explicitly. For example:
.Sp
.Vb 2
\&   in 3 days at 12:00:00
\&   in 3 days at 12:00:00 PST
.Ve
.Sp
will take the delta part "in 3 days" and add it to the current time, then
set the time to 12:00:00.
.Sp
It is NOT allowed to include an explicit time if any time segment was
included in the delta. For example, the following is invalid:
.Sp
.Vb 1
\&   in 3 days 2 hours at 12:00:00
.Ve
.Sp
One additional format that is supported is to include only week (or higher)
components in the delta and to set the day of week. For example:
.Sp
.Vb 4
\&  Friday in 2 weeks
\&  in 2 weeks on Friday
\&  Friday 2 weeks ago
\&  2 weeks ago on Friday at 13:45
.Ve
.Sp
These first apply the delta (of weeks, months, and years) to the current
time, and then set the day to the given day-of-week in that week.
.IP "\fBSpecial date and time strings\fR" 4
.IX Item "Special date and time strings"
Most language have strings which can be used to specify the full date and
time (relative to the current date and time). In English, these include
the string:
.Sp
.Vb 1
\&   now
.Ve
.Sp
They may also have a timezone attached:
.Sp
.Vb 1
\&   now PST
.Ve
.IP "\fBAdditional combined date and time formats\fR" 4
.IX Item "Additional combined date and time formats"
The following formats are also supported:
.Sp
.Vb 5
\&   epoch SECS
\&      The number of seconds since the epoch
\&      (Jan 1, 1970 00:00:00 GMT). SECS may
\&      be negative to give time before the
\&      epoch.
.Ve
.Sp
or
.Sp
.Vb 1
\&   epoch SECS TIMEZONE
.Ve
.PP
A couple of notes:
.PP
Commas may be included in all date formats arbitrarily (except for ISO
8601 formats where they may only be included when allowed by the
specification).
.PP
The time/time zone is removed from the date before the date is parsed,
so the time may appear before or after the date, or between any two
parts of the date.
.PP
The time and the zone do not need to be adjacent, so the string:
.PP
.Vb 1
\&   Jan 21 17:13:27 2010 \-0400
.Ve
.PP
will work.  If the timezone is separate from the date, it MUST be
separated from any other portion of the date by whitespace.
.PP
Certain words such as "on", "in", "at", "of", etc. which commonly
appear in a date or time are ignored (except in ISO 8601 formats).
.SH "PRINTF DIRECTIVES"
.IX Header "PRINTF DIRECTIVES"
The following printf directives are replaced with information
from the date.  These all assume that the Use_POSIX_Printf config
variable is unset.  If it is set, refer to POSIX PRINTF DIRECTIVES
section below.
.PP
.Vb 3
\&   Year
\&       %y     year                     \- 00 to 99
\&       %Y     year                     \- 0001 to 9999
\&
\&   Month, Week
\&       %m     month of year            \- 01 to 12
\&       %f     month of year            \- " 1" to "12"
\&       %b,%h  month abbreviation       \- Jan to Dec
\&       %B     month name               \- January to December
\&
\&   Day
\&       %j     day of the year          \- 001 to 366
\&       %d     day of month             \- 01 to 31
\&       %e     day of month             \- " 1" to "31"
\&       %v     weekday abbreviation     \- " S"," M"," T", ...
\&       %a     weekday abbreviation     \- Sun to Sat
\&       %A     weekday name             \- Sunday to Saturday
\&       %w     day of week              \- 1 to 7 (1=Monday)
\&       %E     day of month with
\&              suffix                   \- 1st, 2nd, 3rd...
\&
\&   Hour
\&       %H     hour                     \- 00 to 23
\&       %k     hour                     \- " 0" to "23"
\&       %i     hour                     \- " 1" to "12"
\&       %I     hour                     \- 01 to 12
\&       %p     AM or PM
\&
\&   Minute, Second, Time zone
\&       %M     minute                   \- 00 to 59
\&       %S     second                   \- 00 to 59
\&       %Z     time zone abbreviation   \- EDT
\&       %z     time zone as GMT offset  \- +0100 (see Note 4)
\&       %N     time zone as GMT offset  \- +01:00:00
\&
\&   Epoch (see NOTE 3 below)
\&       %s     seconds from
\&              1/1/1970 GMT             \- negative if before
\&       %o     seconds from 1/1/1970
\&              in the current time
\&              zone
\&
\&   Date, Time
\&       %c     %a %b %e %H:%M:%S %Y     \- Fri Apr 28 17:23:15 1995
\&       %C,%u  %a %b %e %H:%M:%S %Z %Y  \- Fri Apr 28 17:25:57 EDT 1995
\&       %g     %a, %d %b %Y %H:%M:%S %Z \- Fri, 28 Apr 1995 17:23:15 EDT
\&       %D     %m/%d/%y                 \- 04/28/95
\&       %x     %m/%d/%y or %d/%m/%y     \- 04/28/95 or 28/04/95
\&                                         (Depends on DateFormat variable)
\&       %l     date in ls(1) format (see NOTE 1 below)
\&                %b %e %H:%M            \- Apr 28 17:23 (*)
\&                %b %e  %Y              \- Apr 28  1993 (*)
\&       %r     %I:%M:%S %p              \- 05:39:55 PM
\&       %R     %H:%M                    \- 17:40
\&       %T,%X  %H:%M:%S                 \- 17:40:58
\&       %V     %m%d%H%M%y               \- 0428174095
\&       %Q     %Y%m%d                   \- 19961025
\&       %q     %Y%m%d%H%M%S             \- 19961025174058
\&       %P     %Y%m%d%H:%M:%S           \- 1996102517:40:58
\&       %O     %Y\-%m\-%dT%H:%M:%S        \- 1996\-10\-25T17:40:58
\&       %F     %A, %B %e, %Y            \- Sunday, January  1, 1996
\&       %K     %Y\-%j                    \- 1997\-045
\&
\&   Special Year/Week formats (see NOTE 2 below)
\&       %G     year, Monday as first
\&              day of week              \- 0001 to 9999
\&       %W     week of year, Monday
\&              as first day of week     \- 01 to 53
\&       %L     year, Sunday as first
\&              day of week              \- 0001 to 9999
\&       %U     week of year, Sunday
\&              as first day of week     \- 01 to 53
\&       %J     %G\-W%W\-%w                \- 1997\-W02\-2
\&
\&   Other formats
\&       %n     insert a newline character
\&       %t     insert a tab character
\&       %%     insert a \`%\*(Aq character
\&       %+     insert a \`+\*(Aq character
\&
\&   All other characters are currently unused, but may be used in the
\&   future.  They currently insert the character following the %.
\&
\&   The following multi\-character formats also exist:
\&
\&   Extended formats
\&       %<A=NUM>   These returns the NUMth value of the %A, %a, and %v formats
\&       %<a=NUM>   respectively.  In English, that would yield:
\&       %<v=NUM>      %<A=2>   => Tuesday
\&                     %<a=2>   => Tue
\&                     %<v=2>   => T
\&                  NUM must be in the range 1\-7.
\&
\&       %<B=NUM>   These return the NUMth value of the %B and %b formats
\&       %<b=NUM>   respectively.  In English, that would yield:
\&                     %<B=2>   => February
\&                     %<b=2>   => Feb
\&                  NUM must be in the range 1\-12 (or 01\-12).
\&
\&       %<p=NUM>   These return the NUMth value of the %p format.  In
\&                  English, that would yield:
\&                     %<p=1>   => AM
\&                     %<p=2>   => PM
\&                  NUM must be in the range 1\-2.
\&
\&       %<E=NUM>   These return the NUMth value of the %E format.  In
\&                  English, that would yield:
\&                     %<E=1>   => 1st
\&                     %<E=53>  => 53rd
\&                  NUM must be in the range 1\-53.
.Ve
.PP
If a lone percent is the final character in a format, it is ignored.
.PP
The formats used in this routine were originally based on date.pl (version
3.2) by Terry McGonigal, as well as a couple taken from different versions
of the Solaris \fBdate\fR\|(1) command.  Also, several have been added which are
unique to Date::Manip.
.PP
NOTE 1:
.PP
The ls format (%l) applies to date within the past OR future 6 months!
Any date that is before the date NOW \- 6 months, or that is on or
after the date NOW + 6 months will have the year printed out.
.PP
The later time must be on or after so that there is no ambiguity. If it
is now 2000\-06\-06\-12:00:00, then the date 1999\-12\-06\-12:00:00 will be
written as "Dec 6 12:00" but the date 2000\-12\-06\-12:00:00 will be written
as "Dec 6 2000".
.PP
NOTE 2:
.PP
The \f(CW%U\fR, \f(CW%W\fR, \f(CW%L\fR, \f(CW%G\fR, and \f(CW%J\fR formats are used to support the ISO\-8601 format:
YYYY-wWW-D.  In this format, a date is written as a year, the week of the
year, and the day of the week.  Technically, the week may be considered to
start on any day of the week, but Sunday and Monday are both common
choices, so both are supported.
.PP
The \f(CW%W\fR and \f(CW%G\fR formats return the week-of-year and the year treating weeks
as starting on Monday.
.PP
The \f(CW%U\fR and \f(CW%L\fR formats return the week-of-year and the year treating weeks
as starting on Sunday.
.PP
Most of the time, the \f(CW%L\fR and \f(CW%G\fR formats returns the same value as the \f(CW%Y\fR
format, but there is a problem with days occurring in the first or last week
of the year.
.PP
The ISO\-8601 representation of Jan 1, 1993 written in the YYYY-wWW-D format
is actually 1992\-W53\-5.  In other words, Jan 1 is treated as being in the
last week of the preceding year.  Depending on the year, days in the first
week of a year may belong to the previous year, and days in the final week
of a year may belong to the next year.  The week is assigned to the year
which has most of the days.  For example, if the week starts on Sunday,
then the last week of 2003 is 2003\-12\-28 to 2004\-01\-03.  This week is
assigned to 2003 since 4 of the days in it are in 2003 and only 3 of them
are in 2004.  The first week of 2004 starts on 2004\-01\-04.
.PP
The \f(CW%U\fR and \f(CW%W\fR formats return a week-of-year number from 01 to 53. \f(CW%L\fR and
\&\f(CW%G\fR return the corresponding year, and to get this type of information,
you should always use the (%W,%G) combination or (%U,%L) combination. \f(CW%Y\fR
should not be used as it will yield incorrect results.
.PP
\&\f(CW%J\fR returns the full ISO\-8601 format (%G\-W%W\-%w).
.PP
NOTE 3:
.PP
The \f(CW%s\fR and \f(CW%o\fR formats return negative values if the date is before
the start of the epoch.  Other Unix utilities would return an error, or
a zero, so if you are going to use Date::Manip in conjunction with these,
be sure to check for a negative value.
.PP
NOTE 4:
.PP
The \f(CW%z\fR format returns the offset in the RFC 822 specified format
+0500 .  Most offsets are full hour amounts, so this is not a problem,
but some offsets are irregular (+05:17:30). In this case, the string
returned is +051730 which isn't RFC 822 compliant, but since RFC 822
ignores this situation, I had to decide between returning an incorrect
value, or breaking strict compliance, and I chose the second option.
.SH "POSIX PRINTF DIRECTIVES"
.IX Header "POSIX PRINTF DIRECTIVES"
For various reasons, a few of the printf directives in the
Date::Manip::Date::printf method do not match the standard POSIX
strftime directives.  For backward compatibility reasons, I'm not
going to change that.  However, the Use_POSIX_Printf config variable
can be set to 1 to use the POSIX formats instead of the default
formats.
.PP
When that variable is set, most of the printf formats described above
are used, but the formats are replaced with their POSIX value:
.PP
.Vb 1
\&   %C   The century number (first two digits of the year).
\&
\&   %F   This is equivalent to %Y\-%m\-%d
\&
\&   %l   The hour (12\-hour clock) padded with spaces
\&
\&   %P   Either \*(Aqam\*(Aq or \*(Aqpm\*(Aq.
\&
\&   %u   Day of week from 1\-7 with Monday being 1.
\&
\&   %G   Similar to the %G format described above, but strictly adheres
\&        to the ISO 8601 week definition where the first week of
\&        the week is Monday and the first week of the year contains
\&        Jan 4.
\&
\&   %g   Identical to %g but only has the last two digits of the year.
\&
\&   %W   Similar to the %W format described above, but with Monday
\&        being the first day of the week and the first Monday in the
\&        year being the first day of the first week.
\&
\&   %V   Similar to the %W format described above, but strictly adheres
\&        to the ISO 8601 week definition where the first week of
\&        the week is Monday and the first week of the year contains
\&        Jan 4.
\&
\&   %L   The strftime function does not have a %L directive.  I have
\&        set it anyway to be similar to the %L format above except
\&        using Sunday as the first day of the week and the first week
\&        of the year contains Jan 4 (so this is the equivalent of %G
\&        but with Sunday being the first day of the week).
\&
\&   %U   Similar to the %U format described above but with Sunday being
\&        the first day of the week and the first Sunday being the first
\&        day of the first week.
\&
\&   %J   The strftime function does not have a %J directive, but in
\&        order to support the ISO 8601 YYYY\-wWW\-D format, this is
\&        equivalent to \*(Aq%G\-W%V\-%w\*(Aq.
.Ve
.PP
Note 1: The default (i.e. non-POSIX) Date::Manip printf formats are
defined so that \f(CW%G\fR and \f(CW%W\fR use the exact same definition of week and
likewise \f(CW%L\fR and \f(CW%U\fR use the same definition of weeks.  This means that
you can use them to write a date in an ISO 8601 YYYY-wWW format.  In
the POSIX strftime definitions, \f(CW%G\fR and \f(CW%V\fR work together, but there is
no equivalent pair for Sunday being the first day of the week.
.PP
The following POSIX strftime directives are not yet supported (though
they may be in a future version of Date::Manip).  These will continue
to return the values listed above from the non-POSIX formats.
.PP
.Vb 3
\&   %c, %x, %X
\&        The strftime format give the preferred date/time representations
\&        in the current locale.
\&
\&        Currently Date::Manip does not make use of locale information
\&        so there is no locale\-specific format.
\&
\&        The default format (which is the preferred date and time
\&        format in America) is used in all locales.
\&
\&   %E, %O
\&        Modifiers to create additional directives.
\&
\&   %+   Date and time in the format of the date command
.Ve
.SH "KNOWN BUGS"
.IX Header "KNOWN BUGS"
None known.
.SH "BUGS AND QUESTIONS"
.IX Header "BUGS AND QUESTIONS"
Please refer to the Date::Manip::Problems documentation for
information on submitting bug reports or questions to the author.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Date::Manip        \- main module documentation
.SH LICENSE
.IX Header "LICENSE"
This script is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
.SH AUTHOR
.IX Header "AUTHOR"
Sullivan Beck (sbeck@cpan.org)