1Date::Manip::Config(3)User Contributed Perl DocumentationDate::Manip::Config(3)
2
6 Date::Manip::Config - Date::Manip configuration
7
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
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 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 As an example, you can create and configure a Date::Manip::Date object
26 using the commands:
27 $date = new Date::Manip::Date;
29 $date->config($var1,$val1,$var2,$val2,...);
30 This can be shortened to:
32 $date = new Date::Manip::Date [$var1,$val1,...];
34 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 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 Date_Init("$var1=$val1");
52 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
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 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 The starting section of a config file contains general configuration
69 variables. A list of all config variables is given below.
70 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 The syntax of the config file is very simple. Every line is of the
77 form:
78 VAR = VAL
80 or
82 *SECTION
84 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 The following is a sample config file:
92 DateFormat = US
94 Language = English
95 *Holidays
97 Dec 25 = Christmas
99 Jan 1 = New Year's
100 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 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 $date->config("ConfigFile","/home/foo/Manip.cnf");
112 or (if using a functional interface):
114 Date_Init("ConfigFile=/home/foo/Manip.cnf");
116 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 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
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 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 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 In other words, in the following call:
140 $date->config("Language","Russian",
142 "Defaults","1");
143 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 When using a functional interface, use:
149 Date_Init("Defaults=1");
151 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 An example call to the config function might be:
159 $date->config("ConfigFile","/tmp/file1",
161 'Language',$val);
162 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 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 Multiple config files are safe, and a section may safely be split
174 across multiple files.
175 When using a functional interface, use:
177 Date_Init("ConfigFile=/tmp/file1");
179 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 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 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 Encoding
194 Date::Manip has some support for handling date strings encoded in
195 alternate character encodings.
196 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 The input, output, or both can be overridden using the Encoding
202 variable.
203 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 So, setting:
209 Encoding = iso-8859-1
211 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 Encoding can also be set to the name of two encoding (separated by
217 a comma).
218 Encoding = iso-8859-1,utf-16
220 which means that all input is in iso-8859-1 encoding, but all
222 output will be utf-16.
223 Encoding may also be set as follows:
225 Encoding = iso-8859-1,
227 meaning that input is in iso-8859-1 and output is in the default
229 (i.e. UTF-8) encoding.
230 Encoding = ,utf-16
232 means to check the input in all of the encodings, but all output
234 will be in utf-16 encoding.
235 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 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 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 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 YYYYMMDDHH:MN:SS
260 Two other simple versions have been created. If the Printable
262 variable is set to 1, the format is:
263 YYYYMMDDHHMNSS
265 If Printable is set to 2, the format is:
267 YYYY-MM-DD-HH:MN:SS
269 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
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 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 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 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 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 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 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 midnight the default time is 00:00:00
323 curr the default time is the current time
324 "midnight" is the default value.
326 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 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 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 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 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 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
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 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 There is also no way to handle an odd work schedule such as 10 days
368 on, 4 days off.
369 However, both of these situations can be handled using a fairly
371 simple workaround.
372 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 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 Both of these can be done using recurrences. Refer to the
381 Date::Manip::Recur documentation for details.
382 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 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 The time in both should be a valid time format (H, H:M, or H:M:S).
398 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 Similarly, setting either the WorkDayBeg or WorkDayEnd variables
405 automatically turns off WorkDay24Hr.
406 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 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 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
427 The following config variables help in the handling of recurrences.
428 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 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 The default value is "none".
442 MaxRecurAttempts
444 Occasionally, a recurrence is invalid (though it cannot be easily
445 determined in advance).
446 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 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 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 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 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 The following are equivalent:
480 $date->config("tz","Europe/Rome");
482 $date->config("setdate","now,Europe/Rome");
483 or in the functional interface:
485 Date_Init("tz=Europe/Rome");
487 Date_Init("setdate=now,Europe/Rome");
488 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 There are several cases where this may be useful.
495 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 $date->config("setdate","now,ZONE");
501 or in the function interface:
503 Date_Init("setdate=now,ZONE");
505 If it is currently
507 Jun 6, 2009 12:00:00 in the America/New_York time zone
509 and you call:
511 $date->config("setdate","now,Europe/Rome");
513 the Date::Manip will treat that exact instant as
515 Jun 6, 2009 12:00:00 in the Europe/Rome time zone
517 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 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 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 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 $date->config("setdate","now,DSTFLAG,ZONE");
538 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 If the current date/time doesn't exist in the alternate zone, an
548 error will occur.
549 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 This can be done using the call:
554 $date->config("setdate","zone,ZONE");
556 $date->config("setdate","zone,DSTFLAG,ZONE");
557 If it is currently
559 Jun 6, 2009 12:00:00 in the America/New_York time zone
561 and you call:
563 $date->config("setdate","zone,America/Chicago");
565 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 Note that DSTFLAG is only used if ZONE is entered as an offset.
571 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 $date->config("setdate","DATE");
578 $date->config("setdate","DATE,ZONE");
579 $date->config("setdate","DATE,DSTFLAG,ZONE");
580 set both the date/time and zone.
582 If DATE is not valid in the time zone (either the local time zone
584 or the specified one), and error occurs.
585 The call:
587 $date->config("setdate","now");
589 resets everything to use the current date/time and zone and lets it
591 advance normally.
592 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 $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 all set "now" in the same way as the SetDate variable. Spaces
610 after commas are ignored.
611 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 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 $date->config("forcedate","now");
620 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 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 YYYY-MM-DD-HH:MN:SS
630 YYYYMMDDHH:MN:SS
631
633 The following config variables are currently supported, but are
634 deprecated. They will be removed in a future Date::Manip release:
635 TZ This is discussed above. Use SetDate or ForceDate instead.
637 Scheduled for removal 2016-03-01
639
641 None known.
642
644 Please refer to the Date::Manip::Problems documentation for information
645 on submitting bug reports or questions to the author.
646
648 Date::Manip - main module documentation
649
651 This script is free software; you can redistribute it and/or modify it
652 under the same terms as Perl itself.
653
655 Sullivan Beck (sbeck@cpan.org)
656perl v5.36.0 2023-03-08 Date::Manip::Config(3)