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 The third way to set config variables is to store them in a config
48 file. The config file is read in by passing the appropriate values to
49 the config method as described below. A config file is a good way to
50 easily change a large number of settings. They are also necessary for
51 other purposes (such as events and holidays which are covered in the
52 Date::Manip::Holidays document).
53
55 One of the variables that can be passed to the config method is
56 "ConfigFile". The value of this variable is the path to a config file.
57 A description of the file format and contents is described below.
58 When any Date::Manip::* object is configured, any number of config
60 files may be read (and the config files can specify additional files to
61 read).
62 The starting section of a config file contains general configuration
64 variables. A list of all config variables is given below.
65 Following this, any number of special sections may be included in the
67 config file. The special sections are used to specify other types of
68 information, such as a list of holidays or special events. These
69 special sections are described elsewhere in the documentation.
70 The syntax of the config file is very simple. Every line is of the
72 form:
73 VAR = VAL
75 or
77 *SECTION
79 Blank lines and lines beginning with a pound sign (#) are ignored. All
81 whitespace is optional. Variables names in the main section and section
82 names are case insensitive (though values in the main section are
83 typically case sensitive). Strings in other sections (both variables
84 and values) are case sensitive.
85 The following is a sample config file:
87 DateFormat = US
89 Language = English
90 *Holidays
92 Dec 25 = Christmas
94 Jan 1 = New Year's
95 All config variables that may appear in the main part of a config file
97 are described in the next section. Other sections are described
98 elsewhere. The *Holidays and *Events sections are both described in
99 the Date::Manip::Holidays documentation.
100 A sample config file is included with the Date::Manip distribution.
102 Modify it as appropriate and copy it to some appropriate directory and
103 use the ConfigFile variable to access it. For example, if a config file
104 is stored in /home/foo/Manip.cnf, you can load it by:
105 $date->config("ConfigFile","/home/foo/Manip.cnf");
107 NOTE: if you use business mode calculations, you must have a config
109 file since this is the only place where you can define holidays.
110 In the top section, only variables described below may be used. In
112 other sections, checking (if any) is done in the module that uses the
113 data from that section.
114
116 This section describes the basic Date::Manip configuration variables
117 which can be used in a config file, or which may be passed in using the
118 appropriate functions for each module.
119 Variable names are case insensitive, both as arguments to the config
121 function and in the config file. The values are case sensitive except
122 where specified otherwise.
123 Defaults
125 The value for this config variable is ignored. Whenever the
126 Defaults config variable is encountered, the defaults for all
127 config variables are restored, overriding ALL changes that have
128 been made.
129 In other words, in the following call:
131 $date->config("Language","Russian",
133 "Defaults","1");
134 the first option will end up being ignored since the Defaults
136 config variable will set the language back to it's default value
137 which is English.
138 ConfigFile
140 The ConfigFile variable defines a config file which will be parsed
141 for configuration information. It may be included any number of
142 times, each one including the path to a single config file. The
143 value of this variable is a full path to a file.
144 An example call to the config function might be:
146 $date->config("ConfigFile","/tmp/file1",
148 "ConfigFile","/tmp/file2");
149 Config files are parsed immediately. So if the file '/tmp/file1'
151 contains the following lines:
152 ConfigFile = /tmp/file3
154 ConfigFile = /tmp/file4
155 the following sequence of events occur:
157 First, /tmp/file1 is opened. All options from it are parsed until
159 you get to the first ConfigFile line.
160 At that point, /tmp/file3 is parsed and all config variables stored
162 (and they override any previously stored from /tmp/file1).
163 Next, you continue with /tmp/file1 until the second ConfigFile line
165 is seen at which point /tmp/file4 is parsed.
166 Finally, any remaining lines in /tmp/file1 are parsed. Then
168 /tmp/file2 is parsed.
169 The path to the file may be specified in any way valid for the
171 operating system. If a file is not found, a warning will be issued,
172 but execution will continue.
173 Language
175 Date::Manip can be used to parse dates in many different languages.
176 Currently, it contains translations for the following languages
177 (the version in which they added is included for historical
178 interest):
179 English (default)
181 French (5.02)
182 Swedish (5.05)
183 German (5.31)
184 Dutch (5.32) aka Nederlands
185 Polish (5.32)
186 Spanish (5.33)
187 Portuguese (5.34)
188 Romanian (5.35)
189 Italian (5.35)
190 Russian (5.41)
191 Turkish (5.41)
192 Danish (5.41)
193 Catalan (5.43)
194 Norwegian (6.21)
195 To parse dates in a different language, just use the Language
197 config variable with the name of the language as the value.
198 Language names are case insensitive.
199 Additional languages may be added with the help of someone fluent
201 in English and the other language. If you are interested in
202 providing a translation for a new language, please refer to the
203 Date::Manip::Lang document for instructions.
204 Encoding
206 Date::Manip has some support for handling date strings encoded in
207 alternate character encodings.
208 By default, input strings may be tested using multiple encodings
210 that are commonly used for the specific languages, as well as using
211 standard perl escape sequences, and output is done in UTF-8.
212 The input, output, or both can be overridden using the Encoding
214 variable.
215 Setting Encoding to the name of a single encoding (a name supported
217 by the Encoding perl module), will force all input and output to be
218 done in that encoding.
219 So, setting:
221 Encoding = iso-8859-1
223 means that all input and output will be in that encoding. The
225 encoding 'perl' has the special meaning of storing the string in
226 perl escape sequences.
227 Encoding can also be set to the name of two encoding (separated by
229 a comma).
230 Encoding = iso-8859-1,utf-16
232 which means that all input is in iso-8859-1 encoding, but all
234 output will be utf-16.
235 Encoding may also be set as follows:
237 Encoding = iso-8859-1,
239 meaning that input is in iso-8859-1 and output is in the default
241 (i.e. UTF-8) encoding.
242 Encoding = ,utf-16
244 means to check the input in all of the encodings, but all output
246 will be in utf-16 encoding.
247 Note that any time you change languages, it will reset the
249 encodings, so you should set this config variable AFTER setting the
250 language.
251 DateFormat
253 Different countries look at the date 12/10 as Dec 10 or Oct 12. In
254 the United States, the first is most common, but this certainly
255 doesn't hold true for other countries. Setting DateFormat to "US"
256 (case insensitive) forces the first behavior (Dec 10). Setting
257 DateFormat to anything else forces the second behavior (Oct 12).
258 The "US" setting is the default (sorry about that... I live in the
259 US :-).
260 YYtoYYYY
262 When parsing a date containing a 2-digit year, the year must be
263 converted to 4 digits. This config variable determines how this is
264 done.
265 By default, a 2 digit year is treated as falling in the 100 year
267 period of CURR-89 to CURR+10. So in the year 2005, a two digit year
268 will be somewhere in the range 1916 to 2015.
269 YYtoYYYY may be set to any integer N to force a 2 digit year into
271 the period CURR-N to CURR+(99-N). A value of 0 forces the year to
272 be the current year or later. A value of 99 forces the year to be
273 the current year or earlier. Although the most common choice of
274 values will be somewhere between 0 and 99, there is no restriction
275 on N that forces it to be so. It can actually be any positive or
276 negative number you want to force it into any 100 year period
277 desired.
278 YYtoYYYY can also be set to "C" to force it into the current
280 century, or to "C##" to force it into a specific century. So, in
281 1998, "C" forces 2 digit years to be 1900-1999. "C18" would always
282 force a 2 digit year to be in the range 1800-1899. Note: I'm aware
283 that the actual definitions of century are 1901-2000, NOT
284 1900-1999, so for purists, treat this as the way to supply the
285 first two digits rather than as supplying a century.
286 It can also be set to the form "C####" to force it into a specific
288 100 year period. C1950 refers to 1950-2049.
289 FirstDay
291 It is sometimes necessary to know what day of week is regarded as
292 first. By default, this is set to Monday as that conforms to ISO
293 8601, but many countries and people will prefer Sunday (and in a
294 few cases, a different day may be desired). Set the FirstDay
295 variable to be the first day of the week (1=Monday, 7=Sunday).
296 Jan1Week1
298 ISO 8601 states that the first week of the year is the one which
299 contains Jan 4 (i.e. it is the first week in which most of the days
300 in that week fall in that year). This means that the first 3 days
301 of the year may be treated as belonging to the last week of the
302 previous year. If this is set to non-nil, the ISO 8601 standard
303 will be ignored and the first week of the year contains Jan 1.
304 Printable
306 Some commands may produce a printable version of a date. By
307 default, the printable version of the date is of the format:
308 YYYYMMDDHH:MN:SS
310 Two other simple versions have been created. If the Printable
312 variable is set to 1, the format is:
313 YYYYMMDDHHMNSS
315 If Printable is set to 2, the format is:
317 YYYY-MM-DD-HH:MN:SS
319 This config variable is present in order to maintain backward
321 compatibility, and may actually be deprecated at some point. As
322 such, additional formats will not be added. Instead, use the printf
323 method in the Date::Manip::Date module to extract information with
324 complete flexibility.
325 DefaultTime
327 When a date is parsed from one of the formats listed in the "Common
328 date formats" or "Less common formats" sections of the
329 Date::Manip::Date document, and no time is explicitly included, the
330 default time can be determined by the value of this variable. The
331 two possible values are:
332 midnight the default time is 00:00:00
334 curr the default time is the current time
335 "midnight" is the default value.
337 NOTE: this only applies to dates parsed with the parse method.
339 Dates parsed using the parse_date method always default to
340 00:00:00.
341
343 These are configuration variables used to define work days and holidays
344 used in business mode calculations. Refer to the Date::Manip::Calc
345 documentation for details on these calculations.
346 WorkWeekBeg
348 WorkWeekEnd
349 The first and last days of the work week. These default to Monday
350 and Friday. Days are numbered from 1 (Monday) to 7 (Sunday).
351 WorkWeekBeg must come before WorkWeekEnd numerically so there is no
352 way to handle a work week of Sunday to Thursday using these
353 variables.
354 There is also no way to handle an odd work schedule such as 10 days
356 on, 4 days off.
357 However, both of these situations can be handled using a fairly
359 simple workaround.
360 To handle a work week of Sunday to Thursday, just set WorkWeekBeg=1
362 and WorkWeekEnd=7 and defined a holiday that occurs every Friday
363 and Saturday.
364 To handle a 10 days on, 4 days off schedule, do something similar
366 but defined a holiday that occurs on all of the 4 days off.
367 Both of these can be done using recurrences. Refer to the
369 Date::Manip::Recur documentation for details.
370 WorkDay24Hr
372 WorkDayBeg
373 WorkDayEnd
374 If WorkDay24Hr is non-zero, a work day is treated as being 24 hours
375 long. The WorkDayBeg and WorkDayEnd variables are ignored in this
376 case.
377 By default, WorkDay24Hr is zero, and the work day is defined by the
379 WorkDayBeg and WorkDayEnd variables. These are the times when the
380 work day starts and ends respectively. WorkDayBeg must come before
381 WorkDayEnd (i.e. there is no way to handle the night shift where
382 the work day starts one day and ends another).
383 The time in both should be a valid time format (H, H:M, or H:M:S).
385 Note that setting WorkDay24Hr to a non-zero value automatically
387 sets WorkDayBeg and WorkDayEnd to "00:00:00" and "24:00:00"
388 respectively, so to switch back to a non-24 hour day, you will need
389 to reset both of those config variables.
390 Similarly, setting either the WorkDayBeg or WorkDayEnd variables
392 automatically turns off WorkDay24Hr.
393 TomorrowFirst
395 Periodically, if a day is not a business day, we need to find the
396 nearest business day to it. By default, we'll look to "tomorrow"
397 first, but if this variable is set to 0, we'll look to "yesterday"
398 first. This is only used in the
399 Date::Manip::Date::nearest_business_day method (and the
400 Date_NearestWorkDay function) and is easily overridden (see
401 documentation for the nearest_business_day method).
402 EraseHolidays
404 EraseEvents
405 If these variables are used (a value must be passed in, but is
406 ignored), the current list of defined holidays or events is erased.
407 A new set will be set the next time a config file is read in.
408 Although these variables are supported, the best way to have
410 multiple holiday or events lists will be to create multiple
411 Date::Manip::Base objects based on separate config files.
412
414 The following config variables help in the handling of recurrences.
415 RecurRange
417 When a recurrence is created, it begins with a default range (start
418 and end date). The range selected depends on the value of this
419 variable, and can be set to any of the following:
420 none no default range supplied
422 year the current year
423 month the current month
424 week the current week
425 day the current day
426 all Jan 2, 0001 to Dec 30, 9999
427 The default value is "none".
429
431 The following configuration variables may alter the current time zone.
432 As such, they are only available once the Date::Manip::TZ module is
433 available. An easy way to handle this is to only pass them to the
434 config method of a Date::Manip::TZ object or one of the high level
435 objects (Date::Manip::Date, Date::Manip::Delta, or Date::Manip::Recur).
436 Many of Date::Manip's operations rely on knowing what time it is now.
438 This consists of three things: knowing what date and time it is,
439 knowing what time zone it is, and knowing whether it is daylight saving
440 or not. All of this is necessary in order to correctly handle every
441 possible date.
442 The daylight saving time is only used for a couple hours each year
444 during daylight saving time changes (at all other times, the date,
445 time, and time zone are sufficient information), so it is optional, and
446 defaults to standard time if omitted.
447 The default behavior of Date::Manip is to use the system localtime
449 function to determine the date, time, and daylight saving time
450 information, and to use various methods (see DETERMINING THE SYSTEM
451 TIME ZONE in the Date::Manip::TZ documentation) to determine what time
452 zone the computer is in.
453 TZ This variable is deprecated, but will be supported for several
455 releases. The SetDate or ForceDate variables (described next)
456 should be used instead.
457 The following are equivalent:
459 $date->config("tz","Europe/Rome");
461 $date->config("setdate","now,Europe/Rome");
462 SetDate
464 The SetDate config variable is used to set the current date, time,
465 or time zone, but then allow it to change over time using the rules
466 of that time zone.
467 There are several cases where this may be useful.
469 Often, you may want to use the system time to get the date and
471 time, but you want to work in another time zone. For this, use the
472 call:
473 $date->config("setdate","now,ZONE");
475 If it is currently
477 Jun 6, 2009 12:00:00 in the America/New_York time zone
479 and you call:
481 $date->config("setdate","Europe/Rome");
483 the Date::Manip will treat that exact instant as
485 Jun 6, 2009 12:00:00 in the Europe/Rome time zone
487 At that precise moment, looking at the system time and parsing the
489 date "now" in Date::Manip will give the same date and time.
490 The time will continue to advance, but it will use time change
492 rules from the Europe/Rome time zone. What that means is that if a
493 daylight saving time occurs on the computer, but NOT in the
494 Europe/Rome time zone (or vice versa), the system date and time
495 will no longer match the results of parsing the date "now" in
496 Date::Manip.
497 In general (unless the program runs for an extended period of
499 time), the system date and time WILL match the value of "now", so
500 this is a good way to simulate placing the computer in another time
501 zone.
502 If the current date/time is ambiguous (i.e. it exists in both
504 standard and daylight saving time in the alternate zone), you can
505 use the call:
506 $date->config("setdate","now,DSTFLAG,ZONE");
508 to force it to be in one or the other. DSTFLAG can be "std", "dst",
510 "stdonly", or "dstonly". "std" and "dst" mean that the date can be
511 in either standard or saving time, but will try standard first (for
512 "dst") or saving time first (if "dst"), and will only try the other
513 if the date is not valid. If "stdonly" or "dstonly" is used, the
514 date will be forced to be standard or saving time respectively (an
515 error will be triggered if there is no valid date in that time).
516 If the current date/time doesn't exist in the alternate zone, an
518 error will occur.
519 The other common operation is that you might want to see results as
521 they would appear on a computer running in a different time zone.
522 This can be done using the call:
524 $date->config("setdate","zone,ZONE");
526 $date->config("setdate","zone,DSTFLAG,ZONE");
527 If it is currently
529 Jun 6, 2009 12:00:00 in the America/New_York time zone
531 and you call:
533 $date->config("setdate","zone,America/Chicago");
535 then parsing "now" at precisely that moment will return "Jun 6,
537 2009 11:00:00". This is equivalent to working in the current zone,
538 but then converting everything to the alternate zone.
539 Note that DSTFLAG is only used if ZONE is entered as an offset.
541 The final case where the SetDate config variable is used is to
543 alter the date and time to some other value (completely independent
544 of the current date and time) and allow it to advance normally from
545 that point.
546 $date->config("setdate","DATE");
548 $date->config("setdate","DATE,ZONE");
549 $date->config("setdate","DATE,DSTFLAG,ZONE");
550 set both the date/time and zone.
552 If DATE is not valid in the time zone (either the local time zone
554 or the specified one), and error occurs.
555 The call:
557 $date->config("setdate","now");
559 resets everything to use the current date/time and zone and lets it
561 advance normally.
562 ForceDate
564 The ForceDate config variable is similar to the SetDate variable,
565 except that once "now" is set, it is not allowed to change. Parsing
566 the date "now" will not change, regardless of how long the program
567 runs (unless either the SetDate or ForceDate variables are set to
568 some other value).
569 $date->config("forcedate","now,ZONE");
571 $date->config("forcedate","now,DSTFLAG,ZONE");
572 $date->config("forcedate","zone,ZONE");
573 $date->config("forcedate","zone,DSTFLAG,ZONE");
574 $date->config("forcedate","DATE");
575 $date->config("forcedate","DATE,ZONE");
576 $date->config("forcedate","DATE,DSTFLAG,ZONE");
577 $date->config("forcedate","now");
578 all set "now" in the same way as the SetDate variable. Spaces
580 after commas are ignored.
581 ZONE can be any time zone name, alias, abbreviation, or offset, and the
583 best time zone will be determined from all given information.
584 It should be noted that setting the SetDate or ForceDate variable twice
586 will always refer to the system date/time as a starting point. For
587 example, if a program is running, and calls the method:
588 $date->config("forcedate","now");
590 at Jun 6, 2009 at 12:00, that time will be treated as now from that
592 point on. If the same call is done an hour later, "now" will then be
593 Jun 6, 2009 at 13:00 from that moment on.
594 Since the current date is used in the date parsing routines, no parsing
596 can be done on the DATE value in any of the calls. Instead, DATE must
597 be a date in one of the two formats:
598 YYYY-MM-DD-HH:MN:SS
600 YYYYMMDDHH:MN:SS
601
603 The following config variables are currently supported, but are
604 deprecated. They will be removed in a future Date::Manip release:
605 GlobalCnf
607 IgnoreGlobalCnf
608 PersonalCnf
609 PersonalCnfPath
610 PathSep
611 These variables are currently supported, but will be removed. These
612 have been replaced in favor of ConfigFile.
613 GlobalCnf (which is ignored in a config file, and is only useful in
615 the Date_Init call) sets the full path to a global config file.
616 IgnoreGlobalCnf is ignored completely at this point.
618 PersonalCnf is the name of a personal (or local) config file which
620 will be read in after the global config file. The file will be
621 searched for in a list of directories specified by PersonalCnfPath.
622 The list of directories is delimited by the value of PathSep.
623 In the future, the distinction between a global and personal config
625 file will be removed, and there will be no searching across a path
626 of directories. Instead, full paths will be specified using the
627 ConfigFile variable.
628 Internal
630 This is an alias for Printable. Internal was used previously
631 because the actual format of the date stored by Date::Manip would
632 actually change based on this value. Now, the internal form will
633 never change... just the printable version of it. The variable name
634 has been changed to reflect that change.
635 DeltaSigns
637 This is ignored. Use the Date::Manip::Delta::printf format to
638 format deltas as desired.
639 UpdateCurrTZ
641 This is ignored. With real time zone support, daylight saving time
642 changes are handled automatically and correctly.
643 ConvTZ
645 This is ignored. Calculations automatically handle multiple time
646 zones, so this is no longer necessary.
647 TZ This is discussed above. Use SetDate or ForceDate instead.
649 IntCharSet
651 If set to 0, use the US character set (7-bit ASCII) to return
652 strings such as the month name. If set to 1, use the appropriate
653 international character set. For example, If you want your French
654 representation of December to have the accent over the first "e",
655 you'll want to set this to 1.
656 RecurNumFudgeDays
658 This is no longer used since recurrences were reworked in 6.20.
659
661 None known.
662
664 Please refer to the Date::Manip::Problems documentation for information
665 on submitting bug reports or questions to the author.
666
668 Date::Manip - main module documentation
669
671 This script is free software; you can redistribute it and/or modify it
672 under the same terms as Perl itself.
673
675 Sullivan Beck (sbeck@cpan.org)
676perl v5.10.1 2011-12-07 Date::Manip::Config(3)