1Date::Manip::Config(3)User Contributed Perl DocumentationDate::Manip::Config(3)
2
3
4

NAME

6       Date::Manip::Config - Date::Manip configuration
7

SYNOPSIS

9       This documents the configuration information which is stored in each
10       Date::Manip::Base object, how to modify this information, and how the
11       information is used in the other Date::Manip modules.
12

DESCRIPTION

14       Date::Manip is a very configurable bundle of modules. Many of it's
15       behaviors can be modified to change how date operations are done.  To
16       do this, a list of configuration variables may be set which define many
17       Date::Manip behaviors.
18
19       There are three ways to set config variables. The first two are to pass
20       them in when creating an object, or to pass them to the config method
21       after the object is created. All of the main Date::Manip modules
22       (Date::Manip::Base, Date::Manip::TZ, Date::Manip::Date,
23       Date::Manip::Delta, and Date::Manip::Recur) have the config method.
24
25       As an example, you can create and configure a Date::Manip::Date object
26       using the commands:
27
28          $date = new Date::Manip::Date;
29          $date->config($var1,$val1,$var2,$val2,...);
30
31       This can be shortened to:
32
33          $date = new Date::Manip::Date [$var1,$val1,...];
34
35       The values of the config variables are stored in the Date::Manip::Base
36       object. So, if you have a Date::Manip::Date object, it has a
37       Date::Manip::Base object associated with it, and the configuration
38       information is stored there. The same Date::Manip::Base object may be
39       used by any number of higher objects, and all will share the same
40       configuration. If multiple Date::Manip::Date objects share the same
41       Date::Manip::Base object, setting a configuration variable on any of
42       them affects all of the Date::Manip::Date objects. If you need to work
43       with different configurations simultaneously, it is necessary to work
44       with multiple Date::Manip::Base objects. This is covered in the
45       Date::Manip::Objects document.
46
47       An alternate method exists if you are using one of the functional
48       interfaces.  To set a variable using the functional interface, use the
49       call:
50
51          Date_Init("$var1=$val1");
52
53       The third way to set config variables is to store them in a config
54       file. The config file is read in by passing the appropriate values to
55       the config method as described below.  A config file is a good way to
56       easily change a large number of settings. They are also necessary for
57       other purposes (such as events and holidays which are covered in the
58       Date::Manip::Holidays document).
59

CONFIG FILES

61       One of the variables that can be passed to the config method is
62       "ConfigFile". The value of this variable is the path to a config file.
63
64       When any Date::Manip::* object is configured, any number of config
65       files may be read (and the config files can specify additional files to
66       read).
67
68       The starting section of a config file contains general configuration
69       variables. A list of all config variables is given below.
70
71       Following this, any number of special sections may be included in the
72       config file. The special sections are used to specify other types of
73       information, such as a list of holidays or special events.  These
74       special sections are described elsewhere in the documentation.
75
76       The syntax of the config file is very simple. Every line is of the
77       form:
78
79          VAR = VAL
80
81       or
82
83          *SECTION
84
85       Blank lines and lines beginning with a pound sign (#) are ignored.  All
86       whitespace is optional. Variables names in the main section and section
87       names are case insensitive (though values in the main section are
88       typically case sensitive). Strings in other sections (both variables
89       and values) are case sensitive.
90
91       The following is a sample config file:
92
93          DateFormat = US
94          Language   = English
95
96          *Holidays
97
98          Dec 25 =  Christmas
99          Jan 1  =  New Year's
100
101       All config variables that may appear in the main part of a config file
102       are described in the next section. Other sections are described
103       elsewhere.  The *Holidays and *Events sections are both described in
104       the Date::Manip::Holidays documentation.
105
106       A sample config file is included with the Date::Manip distribution.
107       Modify it as appropriate and copy it to some appropriate directory and
108       use the ConfigFile variable to access it. For example, if a config file
109       is stored in /home/foo/Manip.cnf, you can load it by:
110
111          $date->config("ConfigFile","/home/foo/Manip.cnf");
112
113       or (if using a functional interface):
114
115          Date_Init("ConfigFile=/home/foo/Manip.cnf");
116
117       NOTE: if you use business mode calculations, you must have a config
118       file since this is the only place where you can define holidays.
119
120       In the top section, only variables described below may be used. In
121       other sections, checking (if any) is done in the module that uses the
122       data from that section.
123

BASIC CONFIGURATION VARIABLES

125       This section describes the basic Date::Manip configuration variables
126       which can be used in a config file, or which may be passed in using the
127       appropriate functions for each module.
128
129       Variable names are case insensitive, both as arguments to the config
130       function and in the config file. The values are case sensitive except
131       where specified otherwise.
132
133       Defaults
134           The value for this config variable is ignored. Whenever the
135           Defaults config variable is encountered, the defaults for all
136           config variables are restored, overriding ALL changes that have
137           been made.
138
139           In other words, in the following call:
140
141              $date->config("Language","Russian",
142                            "Defaults","1");
143
144           the first option will end up being ignored since the Defaults
145           config variable will set the language back to it's default value
146           which is English.
147
148           When using a functional interface, use:
149
150              Date_Init("Defaults=1");
151
152       ConfigFile
153           The ConfigFile variable defines a config file which will be parsed
154           for configuration information. It may be included any number of
155           times, each one including the path to a single config file. The
156           value of this variable is a full path to a file.
157
158           An example call to the config function might be:
159
160              $date->config("ConfigFile","/tmp/file1",
161                            'Language',$val);
162
163           Config files are parsed immediately when encountered. So in this
164           example, the file /tmp/file1 will be parsed before the next
165           variable ('Language').  In addition, if a config file contains a
166           ConfigFile variable, that file will immediately be parsed before
167           continuing with the original file.
168
169           The path to the file may be specified in any way valid for the
170           operating system. If a file is not found, a warning will be issued,
171           but execution will continue.
172
173           Multiple config files are safe, and a section may safely be split
174           across multiple files.
175
176           When using a functional interface, use:
177
178              Date_Init("ConfigFile=/tmp/file1");
179
180       Language
181           Date::Manip can be used to parse dates in many different languages.
182           A list of the languages is given in the Date::Manip::Lang document.
183
184           To parse dates in a different language, just use the Language
185           config variable with the name of the language as the value.
186           Language names are case insensitive.
187
188           Additional languages may be added with the help of someone fluent
189           in English and the other language.  If you are interested in
190           providing a translation for a new language, please refer to the
191           Date::Manip::Lang document for instructions.
192
193       Encoding
194           Date::Manip has some support for handling date strings encoded in
195           alternate character encodings.
196
197           By default, input strings may be tested using multiple encodings
198           that are commonly used for the specific languages, as well as using
199           standard perl escape sequences, and output is done in UTF-8.
200
201           The input, output, or both can be overridden using the Encoding
202           variable.
203
204           Setting Encoding to the name of a single encoding (a name supported
205           by the Encoding perl module), will force all input and output to be
206           done in that encoding.
207
208           So, setting:
209
210              Encoding = iso-8859-1
211
212           means that all input and output will be in that encoding. The
213           encoding 'perl' has the special meaning of storing the string in
214           perl escape sequences.
215
216           Encoding can also be set to the name of two encoding (separated by
217           a comma).
218
219              Encoding = iso-8859-1,utf-16
220
221           which means that all input is in iso-8859-1 encoding, but all
222           output will be utf-16.
223
224           Encoding may also be set as follows:
225
226              Encoding = iso-8859-1,
227
228           meaning that input is in iso-8859-1 and output is in the default
229           (i.e.  UTF-8) encoding.
230
231              Encoding = ,utf-16
232
233           means to check the input in all of the encodings, but all output
234           will be in utf-16 encoding.
235
236           Note that any time you change languages, it will reset the
237           encodings, so you should set this config variable AFTER setting the
238           language.
239
240       FirstDay
241           It is sometimes necessary to know what day of week is regarded as
242           first.  By default, this is set to Monday as that conforms to ISO
243           8601, but many countries and people will prefer Sunday (and in a
244           few cases, a different day may be desired).  Set the FirstDay
245           variable to be the first day of the week (1=Monday, 7=Sunday).
246
247       Jan1Week1
248           ISO 8601 states that the first week of the year is the one which
249           contains Jan 4 (i.e. it is the first week in which most of the days
250           in that week fall in that year).  This means that the first 3 days
251           of the year may be treated as belonging to the last week of the
252           previous year.  If this is set to non-nil, the ISO 8601 standard
253           will be ignored and the first week of the year contains Jan 1.
254
255       Printable
256           Some commands may produce a printable version of a date. By
257           default, the printable version of the date is of the format:
258
259              YYYYMMDDHH:MN:SS
260
261           Two other simple versions have been created. If the Printable
262           variable is set to 1, the format is:
263
264              YYYYMMDDHHMNSS
265
266           If Printable is set to 2, the format is:
267
268              YYYY-MM-DD-HH:MN:SS
269
270           This config variable is present in order to maintain backward
271           compatibility, and may actually be deprecated at some point. As
272           such, additional formats will not be added. Instead, use the printf
273           method in the Date::Manip::Date module to extract information with
274           complete flexibility.
275

DATE PARSING CONFIGURATION VARIABLES

277       DateFormat
278           Different countries look at the date 12/10 as Dec 10 or Oct 12.  In
279           the United States, the first is most common, but this certainly
280           doesn't hold true for other countries.  Setting DateFormat to "US"
281           (case insensitive) forces the first behavior (Dec 10).  Setting
282           DateFormat to anything else forces the second behavior (Oct 12).
283           The "US" setting is the default (sorry about that...  I live in the
284           US).
285
286       YYtoYYYY
287           When parsing a date containing a 2-digit year, the year must be
288           converted to 4 digits. This config variable determines how this is
289           done.
290
291           By default, a 2 digit year is treated as falling in the 100 year
292           period of CURR-89 to CURR+10. So in the year 2005, a two digit year
293           will be somewhere in the range 1916 to 2015.
294
295           YYtoYYYY may be set to any integer N to force a 2 digit year into
296           the period CURR-N to CURR+(99-N).  A value of 0 forces the year to
297           be the current year or later.  A value of 99 forces the year to be
298           the current year or earlier.  Although the most common choice of
299           values will be somewhere between 0 and 99, there is no restriction
300           on N that forces it to be so. It can actually be any positive or
301           negative number you want to force it into any 100 year period
302           desired.
303
304           YYtoYYYY can also be set to "C" to force it into the current
305           century, or to "C##" to force it into a specific century.  So, in
306           1998, "C" forces 2 digit years to be 1900-1999.  "C18" would always
307           force a 2 digit year to be in the range 1800-1899. Note: I'm aware
308           that the actual definitions of century are 1901-2000, NOT
309           1900-1999, so for purists, treat this as the way to supply the
310           first two digits rather than as supplying a century.
311
312           It can also be set to the form "C####" to force it into a specific
313           100 year period.  C1950 refers to 1950-2049.
314
315       DefaultTime
316           When a date is parsed from one of the formats listed in the "Common
317           date formats" or "Less common formats" sections of the
318           Date::Manip::Date document, and no time is explicitly included, the
319           default time can be determined by the value of this variable. The
320           two possible values are:
321
322              midnight   the default time is 00:00:00
323              curr       the default time is the current time
324
325           "midnight" is the default value.
326
327           NOTE: this only applies to dates parsed with the parse method.
328           Dates parsed using the parse_date method always default to
329           00:00:00.
330
331       PeriodTimeSep
332           By default, the time separator (i.e. the character that separates
333           hours from minutes and minutes from seconds) is specified in the
334           language translations and in most cases it does not include a
335           period.  In English, the only defined time separator is a colon
336           (:), so the time can be written as 12:15:30 .
337
338           If you want to use a period (.) as a time separator as well, set
339           this to 1.  Then you can write the time as 12.15.30 .
340
341           By default, a period is used as a date separator, so 12.15.30 would
342           be interpreted as Dec 15 1930 (or 2030), so if you use the period
343           as a date separator, it should not be used as a time separator too.
344
345       Format_MMMYYYY
346           By default, when parsing a string like 'Jun 1925', it will be
347           interpreted as 'Jun 19, 2025' (i.e. MMM DDYY).  Also, the string
348           '1925 Jun' is not allowed.
349
350           This variable can be set to either 'first' or 'last', and in that
351           case, both 'Jun 1925' and '1925 Jun' will be allowed, and will
352           refer to either the first or last day of June in 1925.
353

BUSINESS CONFIGURATION VARIABLES

355       These are configuration variables used to define work days and holidays
356       used in business mode calculations. Refer to the Date::Manip::Calc
357       documentation for details on these calculations.
358
359       WorkWeekBeg
360       WorkWeekEnd
361           The first and last days of the work week.  These default to Monday
362           and Friday.  Days are numbered from 1 (Monday) to 7 (Sunday).
363           WorkWeekBeg must come before WorkWeekEnd numerically so there is no
364           way to handle a work week of Sunday to Thursday using these
365           variables.
366
367           There is also no way to handle an odd work schedule such as 10 days
368           on, 4 days off.
369
370           However, both of these situations can be handled using a fairly
371           simple workaround.
372
373           To handle a work week of Sunday to Thursday, just set WorkWeekBeg=1
374           and WorkWeekEnd=7 and defined a holiday that occurs every Friday
375           and Saturday.
376
377           To handle a 10 days on, 4 days off schedule, do something similar
378           but defined a holiday that occurs on all of the 4 days off.
379
380           Both of these can be done using recurrences. Refer to the
381           Date::Manip::Recur documentation for details.
382
383       WorkDay24Hr
384       WorkDayBeg
385       WorkDayEnd
386           If WorkDay24Hr is non-zero, a work day is treated as usually being
387           24 hours long (daylight saving time changes ARE taken into
388           account).  The WorkDayBeg and WorkDayEnd variables are ignored in
389           this case.
390
391           By default, WorkDay24Hr is zero, and the work day is defined by the
392           WorkDayBeg and WorkDayEnd variables. These are the times when the
393           work day starts and ends respectively. WorkDayBeg must come before
394           WorkDayEnd (i.e. there is no way to handle the night shift where
395           the work day starts one day and ends another).
396
397           The time in both should be a valid time format (H, H:M, or H:M:S).
398
399           Note that setting WorkDay24Hr to a non-zero value automatically
400           sets WorkDayBeg and WorkDayEnd to "00:00:00" and "24:00:00"
401           respectively, so to switch back to a non-24 hour day, you will need
402           to reset both of those config variables.
403
404           Similarly, setting either the WorkDayBeg or WorkDayEnd variables
405           automatically turns off WorkDay24Hr.
406
407       TomorrowFirst
408           Periodically, if a day is not a business day, we need to find the
409           nearest business day to it.  By default, we'll look to "tomorrow"
410           first, but if this variable is set to 0, we'll look to "yesterday"
411           first.  This is only used in the
412           "Date::Manip::Date::nearest_business_day" method (and the
413           "Date_NearestWorkDay" function) and is easily overridden (see
414           documentation for the nearest_business_day method).
415
416       EraseHolidays
417       EraseEvents
418           If these variables are used (a value must be passed in, but is
419           ignored), the current list of defined holidays or events is erased.
420           A new set will be set the next time a config file is read in.
421
422           Although these variables are supported, the best way to have
423           multiple holiday or events lists will be to create multiple
424           Date::Manip::Base objects based on separate config files.
425

RECURRENCE CONFIGURATION VARIABLES

427       The following config variables help in the handling of recurrences.
428
429       RecurRange
430           When a recurrence is created, it begins with a default range (start
431           and end date). The range selected depends on the value of this
432           variable, and can be set to any of the following:
433
434              none     no default range supplied
435              year     the current year
436              month    the current month
437              week     the current week
438              day      the current day
439              all      Jan 2, 0001 to Dec 30, 9999
440
441           The default value is "none".
442
443       MaxRecurAttempts
444           Occasionally, a recurrence is invalid (though it cannot be easily
445           determined in advance).
446
447           When searching for dates that match the recurrence, this is the
448           maximum number of attempts that will be done.  If none are found,
449           the recurrence will be assumed to be invalid.
450
452       The following configuration variables may alter the current time zone.
453       As such, they are only available once the Date::Manip::TZ module is
454       available. An easy way to handle this is to only pass them to the
455       config method of a Date::Manip::TZ object or one of the high level
456       objects (Date::Manip::Date, Date::Manip::Delta, or Date::Manip::Recur).
457
458       Many of Date::Manip's operations rely on knowing what time it is now.
459       This consists of three things: knowing what date and time it is,
460       knowing what time zone it is, and knowing whether it is daylight saving
461       or not. All of this is necessary in order to correctly handle every
462       possible date.
463
464       The daylight saving time information is only used for a couple hours
465       each year during daylight saving time changes (at all other times, the
466       date, time, and time zone are sufficient information), so it is
467       optional, and defaults to standard time if omitted.
468
469       The default behavior of Date::Manip is to use the system localtime
470       function to determine the date, time, and daylight saving time
471       information, and to use various methods (see "DETERMINING THE SYSTEM
472       TIME ZONE" in Date::Manip::TZ) to determine what time zone the computer
473       is in.
474
475       TZ  This variable is deprecated, but will be supported for several
476           releases. The SetDate or ForceDate variables (described next)
477           should be used instead.
478
479           The following are equivalent:
480
481               $date->config("tz","Europe/Rome");
482               $date->config("setdate","now,Europe/Rome");
483
484           or in the functional interface:
485
486               Date_Init("tz=Europe/Rome");
487               Date_Init("setdate=now,Europe/Rome");
488
489       SetDate
490           The SetDate config variable is used to set the current date, time,
491           or time zone, but then allow it to change over time using the rules
492           of that time zone.
493
494           There are several cases where this may be useful.
495
496           Often, you may want to use the system time to get the date and
497           time, but you want to work in another time zone. For this, use the
498           call:
499
500              $date->config("setdate","now,ZONE");
501
502           or in the function interface:
503
504              Date_Init("setdate=now,ZONE");
505
506           If it is currently
507
508              Jun 6, 2009 12:00:00 in the America/New_York time zone
509
510           and you call:
511
512              $date->config("setdate","now,Europe/Rome");
513
514           the Date::Manip will treat that exact instant as
515
516              Jun 6, 2009 12:00:00 in the Europe/Rome time zone
517
518           At that precise moment, looking at the system time and parsing the
519           date "now" in Date::Manip will give the same date and time.
520
521           The time will continue to advance, but it will use time change
522           rules from the Europe/Rome time zone. What that means is that if a
523           daylight saving time occurs on the computer, but NOT in the
524           Europe/Rome time zone (or vice versa), the system date and time
525           will no longer match the results of parsing the date "now" in
526           Date::Manip.
527
528           In general (unless the program runs for an extended period of
529           time), the system date and time WILL match the value of "now", so
530           this is a good way to simulate placing the computer in another time
531           zone.
532
533           If the current date/time is ambiguous (i.e. it exists in both
534           standard and daylight saving time in the alternate zone), you can
535           use the call:
536
537              $date->config("setdate","now,DSTFLAG,ZONE");
538
539           to force it to be in one or the other. DSTFLAG can be "std", "dst",
540           "stdonly", or "dstonly". "std" and "dst" mean that the date can be
541           in either standard or saving time, but will try standard first (for
542           "dst") or saving time first (if "dst"), and will only try the other
543           if the date is not valid. If "stdonly" or "dstonly" is used, the
544           date will be forced to be standard or saving time respectively (an
545           error will be triggered if there is no valid date in that time).
546
547           If the current date/time doesn't exist in the alternate zone, an
548           error will occur.
549
550           The other common operation is that you might want to see results as
551           they would appear on a computer running in a different time zone.
552
553           This can be done using the call:
554
555              $date->config("setdate","zone,ZONE");
556              $date->config("setdate","zone,DSTFLAG,ZONE");
557
558           If it is currently
559
560              Jun 6, 2009 12:00:00 in the America/New_York time zone
561
562           and you call:
563
564              $date->config("setdate","zone,America/Chicago");
565
566           then parsing "now" at precisely that moment will return "Jun 6,
567           2009 11:00:00".  This is equivalent to working in the current zone,
568           but then converting everything to the alternate zone.
569
570           Note that DSTFLAG is only used if ZONE is entered as an offset.
571
572           The final case where the SetDate config variable is used is to
573           alter the date and time to some other value (completely independent
574           of the current date and time) and allow it to advance normally from
575           that point.
576
577              $date->config("setdate","DATE");
578              $date->config("setdate","DATE,ZONE");
579              $date->config("setdate","DATE,DSTFLAG,ZONE");
580
581           set both the date/time and zone.
582
583           If DATE is not valid in the time zone (either the local time zone
584           or the specified one), and error occurs.
585
586           The call:
587
588              $date->config("setdate","now");
589
590           resets everything to use the current date/time and zone and lets it
591           advance normally.
592
593       ForceDate
594           The ForceDate config variable is similar to the SetDate variable,
595           except that once "now" is set, it is not allowed to change. Parsing
596           the date "now" will not change, regardless of how long the program
597           runs (unless either the SetDate or ForceDate variables are set to
598           some other value).
599
600              $date->config("forcedate","now,ZONE");
601              $date->config("forcedate","now,DSTFLAG,ZONE");
602              $date->config("forcedate","zone,ZONE");
603              $date->config("forcedate","zone,DSTFLAG,ZONE");
604              $date->config("forcedate","DATE");
605              $date->config("forcedate","DATE,ZONE");
606              $date->config("forcedate","DATE,DSTFLAG,ZONE");
607              $date->config("forcedate","now");
608
609           all set "now" in the same way as the SetDate variable.  Spaces
610           after commas are ignored.
611
612       ZONE can be any time zone name, alias, abbreviation, or offset, and the
613       best time zone will be determined from all given information.
614
615       It should be noted that setting the SetDate or ForceDate variable twice
616       will always refer to the system date/time as a starting point.  For
617       example, if a program is running, and calls the method:
618
619          $date->config("forcedate","now");
620
621       at Jun 6, 2009 at 12:00, that time will be treated as now from that
622       point on. If the same call is done an hour later, "now" will then be
623       Jun 6, 2009 at 13:00 from that moment on.
624
625       Since the current date is used in the date parsing routines, no parsing
626       can be done on the DATE value in any of the calls.  Instead, DATE must
627       be a date in one of the two formats:
628
629          YYYY-MM-DD-HH:MN:SS
630          YYYYMMDDHH:MN:SS
631

DEPRECATED CONFIGURATION VARIABLES

633       The following config variables are currently supported, but are
634       deprecated.  They will be removed in a future Date::Manip release:
635
636       TZ  This is discussed above. Use SetDate or ForceDate instead.
637
638           Scheduled for removal 2016-03-01
639

KNOWN BUGS

641       None known.
642

BUGS AND QUESTIONS

644       Please refer to the Date::Manip::Problems documentation for information
645       on submitting bug reports or questions to the author.
646

SEE ALSO

648       Date::Manip        - main module documentation
649

LICENSE

651       This script is free software; you can redistribute it and/or modify it
652       under the same terms as Perl itself.
653

AUTHOR

655       Sullivan Beck (sbeck@cpan.org)
656
657
658
659perl v5.32.0                      2020-12-15            Date::Manip::Config(3)
Impressum