|
Packit |
95306a |
# Copyright (c) 1996-2017 Sullivan Beck. All rights reserved.
|
|
Packit |
95306a |
# This program is free software; you can redistribute it and/or modify it
|
|
Packit |
95306a |
# under the same terms as Perl itself.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=pod
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=head1 NAME
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Date::Manip::Config - Date::Manip configuration
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=head1 SYNOPSIS
|
|
Packit |
95306a |
|
|
Packit |
95306a |
This documents the configuration information which is stored in
|
|
Packit |
95306a |
each L<Date::Manip::Base> object, how to modify this information,
|
|
Packit |
95306a |
and how the information is used in the other Date::Manip modules.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=head1 DESCRIPTION
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Date::Manip is a very configurable bundle of modules. Many of it's
|
|
Packit |
95306a |
behaviors can be modified to change how date operations are done. To
|
|
Packit |
95306a |
do this, a list of configuration variables may be set which define
|
|
Packit |
95306a |
many Date::Manip behaviors.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
There are three ways to set config variables. The first two are to
|
|
Packit |
95306a |
pass them in when creating an object, or to pass them to the config
|
|
Packit |
95306a |
method after the object is created. All of the main Date::Manip
|
|
Packit |
95306a |
modules (L<Date::Manip::Base>, L<Date::Manip::TZ>, L<Date::Manip::Date>,
|
|
Packit |
95306a |
L<Date::Manip::Delta>, and L<Date::Manip::Recur>) have the config method.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
As an example, you can create and configure a
|
|
Packit |
95306a |
L<Date::Manip::Date> object using the commands:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$date = new Date::Manip::Date;
|
|
Packit |
95306a |
$date->config($var1,$val1,$var2,$val2,...);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
This can be shortened to:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$date = new Date::Manip::Date [$var1,$val1,...];
|
|
Packit |
95306a |
|
|
Packit |
95306a |
The values of the config variables are stored in the L<Date::Manip::Base>
|
|
Packit |
95306a |
object. So, if you have a L<Date::Manip::Date> object, it has a
|
|
Packit |
95306a |
L<Date::Manip::Base> object associated with it, and the configuration
|
|
Packit |
95306a |
information is stored there. The same L<Date::Manip::Base> object may be
|
|
Packit |
95306a |
used by any number of higher objects, and all will share the same
|
|
Packit |
95306a |
configuration. If multiple L<Date::Manip::Date> objects share the same
|
|
Packit |
95306a |
L<Date::Manip::Base> object, setting a configuration variable on any of
|
|
Packit |
95306a |
them affects all of the L<Date::Manip::Date> objects. If you need to work
|
|
Packit |
95306a |
with different configurations simultaneously, it is necessary to work
|
|
Packit |
95306a |
with multiple L<Date::Manip::Base> objects. This is covered in the
|
|
Packit |
95306a |
L<Date::Manip::Objects> document.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
An alternate method exists if you are using one of the functional
|
|
Packit |
95306a |
interfaces. To set a variable using the functional interface, use the
|
|
Packit |
95306a |
call:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Date_Init("$var1=$val1");
|
|
Packit |
95306a |
|
|
Packit |
95306a |
The third way to set config variables is to store them in a config
|
|
Packit |
95306a |
file. The config file is read in by passing the appropriate values to
|
|
Packit |
95306a |
the config method as described below. A config file is a good way to
|
|
Packit |
95306a |
easily change a large number of settings. They are also necessary for
|
|
Packit |
95306a |
other purposes (such as events and holidays which are covered
|
|
Packit |
95306a |
in the L<Date::Manip::Holidays> document).
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=head1 CONFIG FILES
|
|
Packit |
95306a |
|
|
Packit |
95306a |
One of the variables that can be passed to the config method is
|
|
Packit |
95306a |
"ConfigFile". The value of this variable is the path to a config
|
|
Packit |
95306a |
file.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
When any Date::Manip::* object is configured, any number of config
|
|
Packit |
95306a |
files may be read (and the config files can specify additional files
|
|
Packit |
95306a |
to read).
|
|
Packit |
95306a |
|
|
Packit |
95306a |
The starting section of a config file contains general configuration
|
|
Packit |
95306a |
variables. A list of all config variables is given below.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Following this, any number of special sections may be included in
|
|
Packit |
95306a |
the config file. The special sections are used to specify other
|
|
Packit |
95306a |
types of information, such as a list of holidays or special events.
|
|
Packit |
95306a |
These special sections are described elsewhere in the documentation.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
The syntax of the config file is very simple. Every line is of
|
|
Packit |
95306a |
the form:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
VAR = VAL
|
|
Packit |
95306a |
|
|
Packit |
95306a |
or
|
|
Packit |
95306a |
|
|
Packit |
95306a |
*SECTION
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Blank lines and lines beginning with a pound sign (#) are ignored.
|
|
Packit |
95306a |
All whitespace is optional. Variables names in the main section and
|
|
Packit |
95306a |
section names are case insensitive (though values in the main section
|
|
Packit |
95306a |
are typically case sensitive). Strings in other sections (both variables
|
|
Packit |
95306a |
and values) are case sensitive.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
The following is a sample config file:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
DateFormat = US
|
|
Packit |
95306a |
Language = English
|
|
Packit |
95306a |
|
|
Packit |
95306a |
*Holidays
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Dec 25 = Christmas
|
|
Packit |
95306a |
Jan 1 = New Year's
|
|
Packit |
95306a |
|
|
Packit |
95306a |
All config variables that may appear in the main part of a config file
|
|
Packit |
95306a |
are described in the next section. Other sections are described elsewhere.
|
|
Packit |
95306a |
The *Holidays and *Events sections are both described in the
|
|
Packit |
95306a |
L<Date::Manip::Holidays> documentation.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
A sample config file is included with the Date::Manip distribution.
|
|
Packit |
95306a |
Modify it as appropriate and copy it to some appropriate directory and
|
|
Packit |
95306a |
use the ConfigFile variable to access it. For example, if a config
|
|
Packit |
95306a |
file is stored in F</home/foo/Manip.cnf>, you can load it by:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$date->config("ConfigFile","/home/foo/Manip.cnf");
|
|
Packit |
95306a |
|
|
Packit |
95306a |
or (if using a functional interface):
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Date_Init("ConfigFile=/home/foo/Manip.cnf");
|
|
Packit |
95306a |
|
|
Packit |
95306a |
NOTE: if you use business mode calculations, you must have a config
|
|
Packit |
95306a |
file since this is the only place where you can define holidays.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
In the top section, only variables described below may be used. In
|
|
Packit |
95306a |
other sections, checking (if any) is done in the module that uses
|
|
Packit |
95306a |
the data from that section.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=head1 BASIC CONFIGURATION VARIABLES
|
|
Packit |
95306a |
|
|
Packit |
95306a |
This section describes the basic Date::Manip configuration variables
|
|
Packit |
95306a |
which can be used in a config file, or which may be passed in using
|
|
Packit |
95306a |
the appropriate functions for each module.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Variable names are case insensitive, both as arguments to the config
|
|
Packit |
95306a |
function and in the config file. The values are case sensitive except
|
|
Packit |
95306a |
where specified otherwise.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=over 4
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<Defaults>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
The value for this config variable is ignored. Whenever the Defaults
|
|
Packit |
95306a |
config variable is encountered, the defaults for all config variables
|
|
Packit |
95306a |
are restored, overriding ALL changes that have been made.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
In other words, in the following call:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$date->config("Language","Russian",
|
|
Packit |
95306a |
"Defaults","1");
|
|
Packit |
95306a |
|
|
Packit |
95306a |
the first option will end up being ignored since the Defaults config
|
|
Packit |
95306a |
variable will set the language back to it's default value which is
|
|
Packit |
95306a |
English.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
When using a functional interface, use:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Date_Init("Defaults=1");
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<ConfigFile>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
The ConfigFile variable defines a config file which will be parsed for
|
|
Packit |
95306a |
configuration information. It may be included any number of times, each
|
|
Packit |
95306a |
one including the path to a single config file. The value of this
|
|
Packit |
95306a |
variable is a full path to a file.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
An example call to the config function might be:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$date->config("ConfigFile","/tmp/file1",
|
|
Packit |
95306a |
'Language',$val);
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Config files are parsed immediately when encountered. So in this example,
|
|
Packit |
95306a |
the file F</tmp/file1> will be parsed before the next variable ('Language').
|
|
Packit |
95306a |
In addition, if a config file contains a ConfigFile variable, that file
|
|
Packit |
95306a |
will immediately be parsed before continuing with the original file.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
The path to the file may be specified in any way valid for the
|
|
Packit |
95306a |
operating system. If a file is not found, a warning will be issued,
|
|
Packit |
95306a |
but execution will continue.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Multiple config files are safe, and a section may safely be split
|
|
Packit |
95306a |
across multiple files.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
When using a functional interface, use:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Date_Init("ConfigFile=/tmp/file1");
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<Language>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Date::Manip can be used to parse dates in many different languages.
|
|
Packit |
95306a |
A list of the languages is given in the L<Date::Manip::Lang> document.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
To parse dates in a different language, just use the Language config
|
|
Packit |
95306a |
variable with the name of the language as the value. Language names
|
|
Packit |
95306a |
are case insensitive.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Additional languages may be added with the help of someone fluent in
|
|
Packit |
95306a |
English and the other language. If you are interested in providing a
|
|
Packit |
95306a |
translation for a new language, please refer to the L<Date::Manip::Lang>
|
|
Packit |
95306a |
document for instructions.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<Encoding>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Date::Manip has some support for handling date strings encoded in
|
|
Packit |
95306a |
alternate character encodings.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
By default, input strings may be tested using multiple encodings that
|
|
Packit |
95306a |
are commonly used for the specific languages, as well as using
|
|
Packit |
95306a |
standard perl escape sequences, and output is done in UTF-8.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
The input, output, or both can be overridden using the Encoding
|
|
Packit |
95306a |
variable.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Setting Encoding to the name of a single encoding (a name supported
|
|
Packit |
95306a |
by the Encoding perl module), will force all input and output to be
|
|
Packit |
95306a |
done in that encoding.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
So, setting:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Encoding = iso-8859-1
|
|
Packit |
95306a |
|
|
Packit |
95306a |
means that all input and output will be in that encoding. The
|
|
Packit |
95306a |
encoding 'perl' has the special meaning of storing the string in
|
|
Packit |
95306a |
perl escape sequences.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Encoding can also be set to the name of two encoding (separated
|
|
Packit |
95306a |
by a comma).
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Encoding = iso-8859-1,utf-16
|
|
Packit |
95306a |
|
|
Packit |
95306a |
which means that all input is in iso-8859-1 encoding, but all output
|
|
Packit |
95306a |
will be utf-16.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Encoding may also be set as follows:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Encoding = iso-8859-1,
|
|
Packit |
95306a |
|
|
Packit |
95306a |
meaning that input is in iso-8859-1 and output is in the default (i.e.
|
|
Packit |
95306a |
UTF-8) encoding.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Encoding = ,utf-16
|
|
Packit |
95306a |
|
|
Packit |
95306a |
means to check the input in all of the encodings, but all output will
|
|
Packit |
95306a |
be in utf-16 encoding.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Note that any time you change languages, it will reset the encodings,
|
|
Packit |
95306a |
so you should set this config variable AFTER setting the language.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<FirstDay>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
It is sometimes necessary to know what day of week is regarded as
|
|
Packit |
95306a |
first. By default, this is set to Monday as that conforms to ISO
|
|
Packit |
95306a |
8601, but many countries and people will prefer Sunday (and in a few
|
|
Packit |
95306a |
cases, a different day may be desired). Set the FirstDay variable to
|
|
Packit |
95306a |
be the first day of the week (1=Monday, 7=Sunday).
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<Jan1Week1>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
ISO 8601 states that the first week of the year is the one which contains
|
|
Packit |
95306a |
Jan 4 (i.e. it is the first week in which most of the days in that week
|
|
Packit |
95306a |
fall in that year). This means that the first 3 days of the year may
|
|
Packit |
95306a |
be treated as belonging to the last week of the previous year. If this
|
|
Packit |
95306a |
is set to non-nil, the ISO 8601 standard will be ignored and the first
|
|
Packit |
95306a |
week of the year contains Jan 1.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<Printable>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Some commands may produce a printable version of a date. By default,
|
|
Packit |
95306a |
the printable version of the date is of the format:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
YYYYMMDDHH:MN:SS
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Two other simple versions have been created. If the Printable variable is
|
|
Packit |
95306a |
set to 1, the format is:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
YYYYMMDDHHMNSS
|
|
Packit |
95306a |
|
|
Packit |
95306a |
If Printable is set to 2, the format is:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
YYYY-MM-DD-HH:MN:SS
|
|
Packit |
95306a |
|
|
Packit |
95306a |
This config variable is present in order to maintain backward
|
|
Packit |
95306a |
compatibility, and may actually be deprecated at some point. As such,
|
|
Packit |
95306a |
additional formats will not be added. Instead, use the printf method
|
|
Packit |
95306a |
in the L<Date::Manip::Date> module to extract information with complete
|
|
Packit |
95306a |
flexibility.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=back
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=head1 DATE PARSING CONFIGURATION VARIABLES
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=over 4
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<DateFormat>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Different countries look at the date 12/10 as Dec 10 or Oct 12. In
|
|
Packit |
95306a |
the United States, the first is most common, but this certainly
|
|
Packit |
95306a |
doesn't hold true for other countries. Setting DateFormat to "US"
|
|
Packit |
95306a |
(case insensitive) forces the first behavior (Dec 10). Setting
|
|
Packit |
95306a |
DateFormat to anything else forces the second behavior (Oct 12). The
|
|
Packit |
95306a |
"US" setting is the default (sorry about that... I live in the US).
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<YYtoYYYY>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
When parsing a date containing a 2-digit year, the year must be converted
|
|
Packit |
95306a |
to 4 digits. This config variable determines how this is done.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
By default, a 2 digit year is treated as falling in the 100 year period of
|
|
Packit |
95306a |
CURR-89 to CURR+10. So in the year 2005, a two digit year will be somewhere
|
|
Packit |
95306a |
in the range 1916 to 2015.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
YYtoYYYY may be set to any integer N to force a 2 digit year into the
|
|
Packit |
95306a |
period CURR-N to CURR+(99-N). A value of 0 forces the year to be the
|
|
Packit |
95306a |
current year or later. A value of 99 forces the year to be the
|
|
Packit |
95306a |
current year or earlier. Although the most common choice of values
|
|
Packit |
95306a |
will be somewhere between 0 and 99, there is no restriction on N that
|
|
Packit |
95306a |
forces it to be so. It can actually be any positive or negative number
|
|
Packit |
95306a |
you want to force it into any 100 year period desired.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
YYtoYYYY can also be set to "C" to force it into the current century, or
|
|
Packit |
95306a |
to "C##" to force it into a specific century. So, in 1998, "C" forces
|
|
Packit |
95306a |
2 digit years to be 1900-1999. "C18" would always force a 2 digit year to
|
|
Packit |
95306a |
be in the range 1800-1899. Note: I'm aware that the actual definitions of
|
|
Packit |
95306a |
century are 1901-2000, NOT 1900-1999, so for purists, treat this as
|
|
Packit |
95306a |
the way to supply the first two digits rather than as supplying a
|
|
Packit |
95306a |
century.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
It can also be set to the form "C####" to force it into a specific 100
|
|
Packit |
95306a |
year period. C1950 refers to 1950-2049.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<DefaultTime>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
When a date is parsed from one of the formats listed in the "Common date formats"
|
|
Packit |
95306a |
or "Less common formats" sections of the L<Date::Manip::Date> document, and no time
|
|
Packit |
95306a |
is explicitly included, the default time can be determined by the value of this
|
|
Packit |
95306a |
variable. The two possible values are:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
midnight the default time is 00:00:00
|
|
Packit |
95306a |
curr the default time is the current time
|
|
Packit |
95306a |
|
|
Packit |
95306a |
"midnight" is the default value.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
NOTE: this only applies to dates parsed with the parse method. Dates parsed
|
|
Packit |
95306a |
using the parse_date method always default to 00:00:00.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<PeriodTimeSep>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
By default, the time separator (i.e. the character that separates
|
|
Packit |
95306a |
hours from minutes and minutes from seconds) is specified in the
|
|
Packit |
95306a |
language translations and in most cases it does not include a period.
|
|
Packit |
95306a |
In English, the only defined time separator is a colon (:), so the time
|
|
Packit |
95306a |
can be written as 12:15:30 .
|
|
Packit |
95306a |
|
|
Packit |
95306a |
If you want to use a period (.) as a time separator as well, set this
|
|
Packit |
95306a |
to 1. Then you can write the time as 12.15.30 .
|
|
Packit |
95306a |
|
|
Packit |
95306a |
By default, a period is used as a date separator, so 12.15.30 would be
|
|
Packit |
95306a |
interpreted as Dec 15 1930 (or 2030), so if you use the period as a
|
|
Packit |
95306a |
date separator, it should not be used as a time separator too.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<Format_MMMYYYY>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
By default, when parsing a string like 'Jun 1925', it will be interpreted
|
|
Packit |
95306a |
as 'Jun 19, 2025' (i.e. MMM DDYY). Also, the string '1925 Jun' is not allowed.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
This variable can be set to either 'first' or 'last', and in that case,
|
|
Packit |
95306a |
both 'Jun 1925' and '1925 Jun' will be allowed, and will refer to either
|
|
Packit |
95306a |
the first or last day of June in 1925.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=back
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=head1 BUSINESS CONFIGURATION VARIABLES
|
|
Packit |
95306a |
|
|
Packit |
95306a |
These are configuration variables used to define work days and
|
|
Packit |
95306a |
holidays used in business mode calculations. Refer to the
|
|
Packit |
95306a |
L<Date::Manip::Calc> documentation for details on these calculations.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=over 4
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<WorkWeekBeg>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<WorkWeekEnd>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
The first and last days of the work week. These default to Monday and
|
|
Packit |
95306a |
Friday. Days are numbered from 1 (Monday) to 7 (Sunday). WorkWeekBeg
|
|
Packit |
95306a |
must come before WorkWeekEnd numerically so there is no way to handle
|
|
Packit |
95306a |
a work week of Sunday to Thursday using these variables.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
There is also no way to handle an odd work schedule such as 10 days
|
|
Packit |
95306a |
on, 4 days off.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
However, both of these situations can be handled using a fairly simple
|
|
Packit |
95306a |
workaround.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
To handle a work week of Sunday to Thursday, just set WorkWeekBeg=1
|
|
Packit |
95306a |
and WorkWeekEnd=7 and defined a holiday that occurs every Friday and
|
|
Packit |
95306a |
Saturday.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
To handle a 10 days on, 4 days off schedule, do something similar
|
|
Packit |
95306a |
but defined a holiday that occurs on all of the 4 days off.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Both of these can be done using recurrences. Refer to the L<Date::Manip::Recur>
|
|
Packit |
95306a |
documentation for details.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<WorkDay24Hr>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<WorkDayBeg>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<WorkDayEnd>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
If WorkDay24Hr is non-zero, a work day is treated as usually being 24
|
|
Packit |
95306a |
hours long (daylight saving time changes ARE taken into account). The
|
|
Packit |
95306a |
WorkDayBeg and WorkDayEnd variables are ignored in this case.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
By default, WorkDay24Hr is zero, and the work day is defined by the
|
|
Packit |
95306a |
WorkDayBeg and WorkDayEnd variables. These are the times when the work
|
|
Packit |
95306a |
day starts and ends respectively. WorkDayBeg must come before
|
|
Packit |
95306a |
WorkDayEnd (i.e. there is no way to handle the night shift where the
|
|
Packit |
95306a |
work day starts one day and ends another).
|
|
Packit |
95306a |
|
|
Packit |
95306a |
The time in both should be a valid time format (H, H:M, or H:M:S).
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Note that setting WorkDay24Hr to a non-zero value automatically sets
|
|
Packit |
95306a |
WorkDayBeg and WorkDayEnd to "00:00:00" and "24:00:00" respectively,
|
|
Packit |
95306a |
so to switch back to a non-24 hour day, you will need to reset both
|
|
Packit |
95306a |
of those config variables.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Similarly, setting either the WorkDayBeg or WorkDayEnd variables
|
|
Packit |
95306a |
automatically turns off WorkDay24Hr.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<TomorrowFirst>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Periodically, if a day is not a business day, we need to find the
|
|
Packit |
95306a |
nearest business day to it. By default, we'll look to "tomorrow"
|
|
Packit |
95306a |
first, but if this variable is set to 0, we'll look to "yesterday"
|
|
Packit |
95306a |
first. This is only used in the
|
|
Packit |
95306a |
C<Date::Manip::Date::nearest_business_day> method (and the
|
|
Packit |
95306a |
C<Date_NearestWorkDay> function) and is easily overridden (see
|
|
Packit |
95306a |
documentation for the nearest_business_day method).
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<EraseHolidays>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<EraseEvents>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
If these variables are used (a value must be passed in, but is
|
|
Packit |
95306a |
ignored), the current list of defined holidays or events is erased. A
|
|
Packit |
95306a |
new set will be set the next time a config file is read in.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Although these variables are supported, the best way to have multiple
|
|
Packit |
95306a |
holiday or events lists will be to create multiple L<Date::Manip::Base>
|
|
Packit |
95306a |
objects based on separate config files.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=back
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=head1 RECURRENCE CONFIGURATION VARIABLES
|
|
Packit |
95306a |
|
|
Packit |
95306a |
The following config variables help in the handling of recurrences.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=over 4
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<RecurRange>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
When a recurrence is created, it begins with a default range (start
|
|
Packit |
95306a |
and end date). The range selected depends on the value of this
|
|
Packit |
95306a |
variable, and can be set to any of the following:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
none no default range supplied
|
|
Packit |
95306a |
year the current year
|
|
Packit |
95306a |
month the current month
|
|
Packit |
95306a |
week the current week
|
|
Packit |
95306a |
day the current day
|
|
Packit |
95306a |
all Jan 2, 0001 to Dec 30, 9999
|
|
Packit |
95306a |
|
|
Packit |
95306a |
The default value is "none".
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=back
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=head1 TIME ZONE RELATED CONFIGURATION VARIABLES
|
|
Packit |
95306a |
|
|
Packit |
95306a |
The following configuration variables may alter the current
|
|
Packit |
95306a |
time zone. As such, they are only available once the L<Date::Manip::TZ>
|
|
Packit |
95306a |
module is available. An easy way to handle this is to only pass them
|
|
Packit |
95306a |
to the config method of a L<Date::Manip::TZ> object or one of the high
|
|
Packit |
95306a |
level objects (L<Date::Manip::Date>, L<Date::Manip::Delta>, or
|
|
Packit |
95306a |
L<Date::Manip::Recur>).
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Many of Date::Manip's operations rely on knowing what time it is
|
|
Packit |
95306a |
now. This consists of three things: knowing what date and time it is,
|
|
Packit |
95306a |
knowing what time zone it is, and knowing whether it is daylight
|
|
Packit |
95306a |
saving or not. All of this is necessary in order to correctly handle
|
|
Packit |
95306a |
every possible date.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
The daylight saving time information is only used for a couple hours
|
|
Packit |
95306a |
each year during daylight saving time changes (at all other times, the
|
|
Packit |
95306a |
date, time, and time zone are sufficient information), so it is
|
|
Packit |
95306a |
optional, and defaults to standard time if omitted.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
The default behavior of Date::Manip is to use the system localtime
|
|
Packit |
95306a |
function to determine the date, time, and daylight saving time
|
|
Packit |
95306a |
information, and to use various methods (see
|
|
Packit |
95306a |
L<Date::Manip::TZ/"DETERMINING THE SYSTEM TIME ZONE">) to determine what
|
|
Packit |
95306a |
time zone the computer is in.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=over 4
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<TZ>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
This variable is deprecated, but will be supported for several
|
|
Packit |
95306a |
releases. The SetDate or ForceDate variables (described next) should be
|
|
Packit |
95306a |
used instead.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
The following are equivalent:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$date->config("tz","Europe/Rome");
|
|
Packit |
95306a |
$date->config("setdate","now,Europe/Rome");
|
|
Packit |
95306a |
|
|
Packit |
95306a |
or in the functional interface:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Date_Init("tz=Europe/Rome");
|
|
Packit |
95306a |
Date_Init("setdate=now,Europe/Rome");
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<SetDate>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
The SetDate config variable is used to set the current date, time, or
|
|
Packit |
95306a |
time zone, but then allow it to change over time using the rules of
|
|
Packit |
95306a |
that time zone.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
There are several cases where this may be useful.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Often, you may want to use the system time to get the date and time, but
|
|
Packit |
95306a |
you want to work in another time zone. For this, use the call:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$date->config("setdate","now,ZONE");
|
|
Packit |
95306a |
|
|
Packit |
95306a |
or in the function interface:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Date_Init("setdate=now,ZONE");
|
|
Packit |
95306a |
|
|
Packit |
95306a |
If it is currently
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Jun 6, 2009 12:00:00 in the America/New_York time zone
|
|
Packit |
95306a |
|
|
Packit |
95306a |
and you call:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$date->config("setdate","now,Europe/Rome");
|
|
Packit |
95306a |
|
|
Packit |
95306a |
the Date::Manip will treat that exact instant as
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Jun 6, 2009 12:00:00 in the Europe/Rome time zone
|
|
Packit |
95306a |
|
|
Packit |
95306a |
At that precise moment, looking at the system time and parsing the
|
|
Packit |
95306a |
date "now" in Date::Manip will give the same date and time.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
The time will continue to advance, but it will use time change rules
|
|
Packit |
95306a |
from the Europe/Rome time zone. What that means is that if a daylight
|
|
Packit |
95306a |
saving time occurs on the computer, but NOT in the Europe/Rome
|
|
Packit |
95306a |
time zone (or vice versa), the system date and time will no longer
|
|
Packit |
95306a |
match the results of parsing the date "now" in Date::Manip.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
In general (unless the program runs for an extended period of
|
|
Packit |
95306a |
time), the system date and time WILL match the value of "now", so
|
|
Packit |
95306a |
this is a good way to simulate placing the computer in another
|
|
Packit |
95306a |
time zone.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
If the current date/time is ambiguous (i.e. it exists in both
|
|
Packit |
95306a |
standard and daylight saving time in the alternate zone), you
|
|
Packit |
95306a |
can use the call:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$date->config("setdate","now,DSTFLAG,ZONE");
|
|
Packit |
95306a |
|
|
Packit |
95306a |
to force it to be in one or the other. DSTFLAG can be "std",
|
|
Packit |
95306a |
"dst", "stdonly", or "dstonly". "std" and "dst" mean that
|
|
Packit |
95306a |
the date can be in either standard or saving time, but will
|
|
Packit |
95306a |
try standard first (for "dst") or saving time first (if "dst"),
|
|
Packit |
95306a |
and will only try the other if the date is not valid. If
|
|
Packit |
95306a |
"stdonly" or "dstonly" is used, the date will be forced to
|
|
Packit |
95306a |
be standard or saving time respectively (an error will be
|
|
Packit |
95306a |
triggered if there is no valid date in that time).
|
|
Packit |
95306a |
|
|
Packit |
95306a |
If the current date/time doesn't exist in the alternate zone,
|
|
Packit |
95306a |
an error will occur.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
The other common operation is that you might want to see results
|
|
Packit |
95306a |
as they would appear on a computer running in a different time zone.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
This can be done using the call:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$date->config("setdate","zone,ZONE");
|
|
Packit |
95306a |
$date->config("setdate","zone,DSTFLAG,ZONE");
|
|
Packit |
95306a |
|
|
Packit |
95306a |
If it is currently
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Jun 6, 2009 12:00:00 in the America/New_York time zone
|
|
Packit |
95306a |
|
|
Packit |
95306a |
and you call:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$date->config("setdate","zone,America/Chicago");
|
|
Packit |
95306a |
|
|
Packit |
95306a |
then parsing "now" at precisely that moment will return "Jun 6, 2009
|
|
Packit |
95306a |
11:00:00". This is equivalent to working in the current zone, but
|
|
Packit |
95306a |
then converting everything to the alternate zone.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Note that DSTFLAG is only used if ZONE is entered as an offset.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
The final case where the SetDate config variable is used is to alter
|
|
Packit |
95306a |
the date and time to some other value (completely independent of
|
|
Packit |
95306a |
the current date and time) and allow it to advance normally from
|
|
Packit |
95306a |
that point.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$date->config("setdate","DATE");
|
|
Packit |
95306a |
$date->config("setdate","DATE,ZONE");
|
|
Packit |
95306a |
$date->config("setdate","DATE,DSTFLAG,ZONE");
|
|
Packit |
95306a |
|
|
Packit |
95306a |
set both the date/time and zone.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
If DATE is not valid in the time zone (either the local time zone
|
|
Packit |
95306a |
or the specified one), and error occurs.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
The call:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$date->config("setdate","now");
|
|
Packit |
95306a |
|
|
Packit |
95306a |
resets everything to use the current date/time and zone and lets it
|
|
Packit |
95306a |
advance normally.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<ForceDate>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
The ForceDate config variable is similar to the SetDate variable, except
|
|
Packit |
95306a |
that once "now" is set, it is not allowed to change. Parsing the date "now"
|
|
Packit |
95306a |
will not change, regardless of how long the program runs (unless either
|
|
Packit |
95306a |
the SetDate or ForceDate variables are set to some other value).
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$date->config("forcedate","now,ZONE");
|
|
Packit |
95306a |
$date->config("forcedate","now,DSTFLAG,ZONE");
|
|
Packit |
95306a |
$date->config("forcedate","zone,ZONE");
|
|
Packit |
95306a |
$date->config("forcedate","zone,DSTFLAG,ZONE");
|
|
Packit |
95306a |
$date->config("forcedate","DATE");
|
|
Packit |
95306a |
$date->config("forcedate","DATE,ZONE");
|
|
Packit |
95306a |
$date->config("forcedate","DATE,DSTFLAG,ZONE");
|
|
Packit |
95306a |
$date->config("forcedate","now");
|
|
Packit |
95306a |
|
|
Packit |
95306a |
all set "now" in the same way as the SetDate variable. Spaces after commas are
|
|
Packit |
95306a |
ignored.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=back
|
|
Packit |
95306a |
|
|
Packit |
95306a |
ZONE can be any time zone name, alias, abbreviation, or offset, and
|
|
Packit |
95306a |
the best time zone will be determined from all given information.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
It should be noted that setting the SetDate or ForceDate variable
|
|
Packit |
95306a |
twice will always refer to the system date/time as a starting point.
|
|
Packit |
95306a |
For example, if a program is running, and calls the method:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
$date->config("forcedate","now");
|
|
Packit |
95306a |
|
|
Packit |
95306a |
at Jun 6, 2009 at 12:00, that time will be treated as now from that
|
|
Packit |
95306a |
point on. If the same call is done an hour later, "now" will then
|
|
Packit |
95306a |
be Jun 6, 2009 at 13:00 from that moment on.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Since the current date is used in the date parsing routines, no
|
|
Packit |
95306a |
parsing can be done on the DATE value in any of the calls. Instead,
|
|
Packit |
95306a |
DATE must be a date in one of the two formats:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
YYYY-MM-DD-HH:MN:SS
|
|
Packit |
95306a |
YYYYMMDDHH:MN:SS
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=head1 DEPRECATED CONFIGURATION VARIABLES
|
|
Packit |
95306a |
|
|
Packit |
95306a |
The following config variables are currently supported, but are
|
|
Packit |
95306a |
deprecated. They will be removed in a future Date::Manip release:
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=over 4
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=item B<TZ>
|
|
Packit |
95306a |
|
|
Packit |
95306a |
This is discussed above. Use SetDate or ForceDate instead.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Scheduled for removal 2016-03-01
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=back
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=head1 KNOWN BUGS
|
|
Packit |
95306a |
|
|
Packit |
95306a |
None known.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=head1 BUGS AND QUESTIONS
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Please refer to the L<Date::Manip::Problems> documentation for
|
|
Packit |
95306a |
information on submitting bug reports or questions to the author.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=head1 SEE ALSO
|
|
Packit |
95306a |
|
|
Packit |
95306a |
L<Date::Manip> - main module documentation
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=head1 LICENSE
|
|
Packit |
95306a |
|
|
Packit |
95306a |
This script is free software; you can redistribute it and/or
|
|
Packit |
95306a |
modify it under the same terms as Perl itself.
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=head1 AUTHOR
|
|
Packit |
95306a |
|
|
Packit |
95306a |
Sullivan Beck (sbeck@cpan.org)
|
|
Packit |
95306a |
|
|
Packit |
95306a |
=cut
|