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.
22 All modules which are designed to be used directly (i.e.
24 Date::Manip::Base, Date::Manip::TZ, Date::Manip::Date,
25 Date::Manip::Delta, and Date::Manip::Recur) have a config method in
26 them which is used to set configuration variables. Alternately, config
27 variables can be passed to the new method when creating new objects.
28 The values of the config variables are stored in the Date::Manip::Base
29 object. So, if you have a Date::Manip::Date object, it has a
30 Date::Manip::Base object associated with it, and the configuration
31 information is stored there. The same Date::Manip::Base object may be
32 used by any number of higher objects, and all will share the same
33 configuration.
34 As an example, you can create and configure a Date::Manip::Date object
36 using the commands:
37 $date = new Date::Manip::Date;
39 $date->config($var1,$val1,$var2,$val2,...);
40 This can be shortened to:
42 $date = new Date::Manip::Date [$var1,$val1,...];
44 The third way to set config variables is to store them in a config
46 file. The config file is read in by passing the appropriate values to
47 the config method as described below. A config file is a good way to
48 easily change a large number of settings. They are also necessary for
49 other purposes (such as events and holidays which are covered elsewhere
50 in the documentation).
51
53 One of the variables that can be passed to the config method is
54 "ConfigFile". The value of this variable is the path to a config file.
55 A description of the file format and contents is described below.
56 When any Date::Manip::* object is configured, any number of config
58 files may be read (and the config files can specify additional files to
59 read).
60 The starting section of a config file contains general configuration
62 variables. A list of all config variables is given below.
63 Following this, any number of special sections may be included in the
65 config file. The special sections are used to specify other types of
66 information, such as a list of holidays or special events. These
67 special sections are described elsewhere in the documentation.
68 The syntax of the config file is very simple. Every line is of the
70 form:
71 VAR = VAL
73 or
75 *SECTION
77 Blank lines and lines beginning with a pound sign (#) are ignored. All
79 whitespace is optional. Variables names in the main section and section
80 names are case insensitive (though values in the main section are
81 typically case sensitive). Strings in other sections (both variables
82 and values) are case sensitive.
83 The following is a sample config file:
85 DateFormat = US
87 Language = English
88 *Holidays
90 Dec 25 = Christmas
92 Jan 1 = New Year's
93 All config variables that may appear in the main part of a config file
95 are described in the next section. Other sections are described
96 elsewhere. The *Holidays and *Events sections are both described in
97 the Date::Manip::Holidyas documentation.
98 A sample config file is included with the Date::Manip distribution.
100 Modify it as appropriate and copy it to some appropriate directory and
101 use the ConfigFile variable to access it. For example, if a config file
102 is stored in /home/foo/Manip.cnf, you can load it by:
103 $date->config("ConfigFile","/home/foo/Manip.cnf");
105 NOTE: if you use business mode calculations, you must have a config
107 file since this is the only place where you can define holidays.
108 In the top section, only variables described below may be used. In
110 other sections, checking (if any) is done in the module that uses the
111 data from that section.
112
114 This section describes the basic Date::Manip configuration variables
115 which can be used in a config file, or which may be passed in using the
116 appropriate functions for each module.
117 Variable names are case insensitive, both as arguments to the config
119 function and in the config file. The values are case sensitive except
120 where specified otherwise.
121 Defaults
123 The value for this config variable is ignored. Whenever the
124 Defaults config variable is encountered, the defaults for all
125 config variables are restored, overriding ALL changes that have
126 been made.
127 In other words, in the following call:
129 $date->config("Language","Russian",
131 "Defaults","1");
132 the first option will end up being ignored since the Defaults
134 config variable will set the language back to it's default value
135 which is English.
136 ConfigFile
138 The ConfigFile variable defines a config file which will be parsed
139 for configuration information. It may be included any number of
140 times, each one including the path to a single config file. The
141 value of this variable is a full path to a file.
142 An example call to the config function might be:
144 $date->config("ConfigFile","/tmp/file1",
146 "ConfigFile","/tmp/file2");
147 An example of a config file might be a file containing the
149 following lines:
150 ConfigFile = /tmp/file3
152 ConfigFile = /tmp/file4
153 When parsing config variables (either from the config function or
155 from a file), every option is handled immediately, and in the order
156 it is read in. For example, if you call $date->config as listed in
157 the example call above, and if /tmp/file1 contains the two lines in
158 the config file example, then option parsing is done as such:
159 First, /tmp/file1 is opened. All options from it are parsed until
161 you get to the first ConfigFile line.
162 At that point, /tmp/file3 is parsed and all config variables stored
164 (and they override any previously stored from /tmp/file1).
165 Next, you continue with /tmp/file1 until the second ConfigFile line
167 is seen at which point /tmp/file4 is parsed.
168 Finally, any remaining lines in /tmp/file1 are parsed. Then
170 /tmp/file2 is parsed.
171 The path to the file may be specified in any way valid for the
173 operating system. If a file is not found, a warning will be issued,
174 but execution will continue.
175 Language
177 Date::Manip can be used to parse dates in many different languages.
178 Currently, it contains translations for the following languages
179 (the version in which they added is included for historical
180 interest):
181 English (default)
183 French (5.02)
184 Swedish (5.05)
185 German (5.31)
186 Dutch (5.32) aka Nederlands
187 Polish (5.32)
188 Spanish (5.33)
189 Portuguese (5.34)
190 Romanian (5.35)
191 Italian (5.35)
192 Russian (5.41)
193 Turkish (5.41)
194 Danish (5.41)
195 Catalan (5.43)
196 To parse dates in a different language, just use the Language
198 config variable with the name of the language as the value.
199 Language names are case insensitive.
200 Additional languages may be added with the help of someone fluent
202 in English and the other language. If you are interested in
203 providing a translation for a new language, email me (see the
204 AUTHOR section in the main Date::Manip documentation) and I'll send
205 you a list of things that I need.
206 DateFormat
208 Different countries look at the date 12/10 as Dec 10 or Oct 12. In
209 the United States, the first is most common, but this certainly
210 doesn't hold true for other countries. Setting DateFormat to "US"
211 (case insensitive) forces the first behavior (Dec 10). Setting
212 DateFormat to anything else forces the second behavior (Oct 12).
213 The "US" setting is the default (sorry about that... I live in the
214 US :-).
215 YYtoYYYY
217 When parsing a date containing a 2-digit year, the year must be
218 converted to 4 digits. This config variable determines how this is
219 done.
220 By default, a 2 digit year is treated as falling in the 100 year
222 period of CURR-89 to CURR+10. So in the year 2005, a two digit year
223 will be somewhere in the range 1916 to 2015.
224 YYtoYYYY may be set to any integer N to force a 2 digit year into
226 the period CURR-N to CURR+(99-N). A value of 0 forces the year to
227 be the current year or later. A value of 99 forces the year to be
228 the current year or earlier. Although the most common choice of
229 values will be somewhere between 0 and 99, there is no restriction
230 on N that forces it to be so. It can actually be any positive or
231 negative number you want to force it into any 100 year period
232 desired.
233 YYtoYYYY can also be set to "C" to force it into the current
235 century, or to "C##" to force it into a specific century. So, in
236 1998, "C" forces 2 digit years to be 1900-1999. "C18" would always
237 force a 2 digit year to be in the range 1800-1899. Note: I'm aware
238 that the actual definitions of century are 1901-2000, NOT
239 1900-1999, so for purists, treat this as the way to supply the
240 first two digits rather than as supplying a century.
241 It can also be set to the form "C####" to force it into a specific
243 100 year period. C1950 refers to 1950-2049.
244 FirstDay
246 It is sometimes necessary to know what day of week is regarded as
247 first. By default, this is set to Monday, but many countries and
248 people will prefer Sunday (and in a few cases, a different day may
249 be desired). Set the FirstDay variable to be the first day of the
250 week (1=Monday, 7=Sunday) Monday should be chosen to to comply with
251 ISO 8601.
252 Jan1Week1
254 ISO 8601 states that the first week of the year is the one which
255 contains Jan 4 (i.e. it is the first week in which most of the days
256 in that week fall in that year). This means that the first 3 days
257 of the year may be treated as belonging to the last week of the
258 previous year. If this is set to non-nil, the ISO 8601 standard
259 will be ignored and the first week of the year contains Jan 1.
260 Printable
262 Some commands may produce a printable version of a date. By
263 default, the printable version of the date is of the format:
264 YYYYMMDDHH:MN:SS
266 Two other simple versions have been created. If the Printable
268 variable is set to 1, the format is:
269 YYYYMMDDHHMNSS
271 If Printable is set to 2, the format is:
273 YYYY-MM-DD-HH:MN:SS
275 This config variable is present in order to maintain backward
277 compatibility, and may actually be deprecated at some point. As
278 such, additional formats will not be added. Instead, use the printf
279 method in the Date::Manip::Date module to extract information with
280 complete flexibility.
281 IntCharSet
283 If set to 0, use the US character set (7-bit ASCII) to return
284 strings such as the month name. If set to 1, use the appropriate
285 international character set. For example, If you want your French
286 representation of December to have the accent over the first "e",
287 you'll want to set this to 1.
288 DefaultTime
290 When a date is parsed from one of the formats listed in the "Common
291 date formats" or "Less common formats" sections of the
292 Date::Manip::Date document, and no time is explicitly included, the
293 default time can be determined by the value of this variable. The
294 two possible values are:
295 midnight the default time is 00:00:00
297 curr the default time is the current time
298 "midnight" is the default value.
300 NOTE: this only applies to dates parsed with the parse method.
302 Dates parsed using the parse_date method always default to
303 00:00:00.
304
306 These are configuration variables used to define work days and holidays
307 used in business mode calculations. Refer to the Date::Manip::Calc
308 documentation for details on these calculations.
309 WorkWeekBeg
311 WorkWeekEnd
312 The first and last days of the work week. These default to Monday
313 and Friday. Days are numbered from 1 (Monday) to 7 (Sunday).
314 WorkWeekBeg must come before WorkWeekEnd numerically so there is no
315 way to handle a work week of Sunday to Thursday using these
316 variables.
317 There is also no way to handle an odd work schedule such as 10 days
319 on, 4 days off.
320 However, both of these situations can be handled using a fairly
322 simple workaround.
323 To handle a work week of Sunday to Thursday, just set WorkWeekBeg=1
325 and WorkWeekEnd=7 and defined a holiday that occurs every Friday
326 and Saturday.
327 To handle a 10 days on, 4 days off schedule, do something similar
329 but defined a holiday that occurs on all of the 4 days off.
330 Both of these can be done using recurrences. Refer to the
332 Date::Manip::Recur documentation for details.
333 WorkDay24Hr
335 WorkDayBeg
336 WorkDayEnd
337 If WorkDay24Hr is non-zero, a work day is treated as being 24 hours
338 long. The WorkDayBeg and WorkDayEnd variables are ignored in this
339 case.
340 By default, WorkDay24Hr is zero, and the work day is defined by the
342 WorkDayBeg and WorkDayEnd variables. These are the times when the
343 work day starts and ends respectively. WorkDayBeg must come before
344 WorkDayEnd (i.e. there is no way to handle the night shift where
345 the work day starts one day and ends another).
346 The time in both should be a valid time format (H, H:M, or H:M:S).
348 Note that setting WorkDay24Hr to a non-zero value automatically
350 sets WorkDayBeg and WorkDayEnd to "00:00:00" and "24:00:00"
351 respectively, so to switch back to a non-24 hour day, you will need
352 to reset both of those config variables.
353 Similarly, setting either the WorkDayBeg or WorkDayEnd variables
355 automatically turns off WorkDay24Hr.
356 TomorrowFirst
358 Periodically, if a day is not a business day, we need to find the
359 nearest business day to it. By default, we'll look to "tomorrow"
360 first, but if this variable is set to 0, we'll look to "yesterday"
361 first. This is only used in the
362 Date::Manip::Date::nearest_business_day method (and the
363 Date_NearestWorkDay function) and is easily overridden (see
364 documentation for the nearest_business_day method).
365 EraseHolidays
367 EraseEvents
368 If these variables are used (a value must be passed in, but is
369 ignored), the current list of defined holidays or events is erased.
370 A new set will be set the next time a config file is read in.
371 Although these variables are supported, the best way to have
373 multiple holiday or events lists will be to create multiple
374 Date::Manip::Base objects based on separate config files.
375
377 The following config variables help in the handling of recurrences.
378 RecurRange
380 When a recurrence is created, it begins with a default range (start
381 and end date). The range selected depends on the value of this
382 variable, and can be set to any of the following:
383 none no default range supplied
385 year the current year
386 month the current month
387 week the current week
388 day the current day
389 all Jan 2, 0001 to Dec 30, 9999
390 The default value is "none".
392 RecurNumFudgeDays
394 See the Date::Manip::Recur manual (the section on MODIFIERS) for
395 information on this variable.
396
398 The following configuration variables may alter the current time zone.
399 As such, they are only available once the Date::Manip::TZ module is
400 available. An easy way to handle this is to only pass them to the
401 config method of a Date::Manip::TZ object or one of the high level
402 objects (Date::Manip::Date, Date::Manip::Delta, or Date::Manip::Recur).
403 Many of Date::Manip's operations rely on knowing what time it is now.
405 This consists of three things: knowing what date and time it is,
406 knowing what time zone it is, and knowing whether it is daylight
407 savings or not. All of this is necessary in order to correctly handle
408 every possible date.
409 The daylight savings time is only used for a couple hours each year
411 during daylight saving time changes (at all other times, the date,
412 time, and time zone are sufficient information), so it is optional, and
413 defaults to standard time if omitted.
414 The default behavior of Date::Manip is to use the system localtime
416 function to determine the date, time, and daylight savings time
417 information, and to use various methods (see DETERMINING THE SYSTEM
418 TIME ZONE in the Date::Manip::TZ documentation) to determine what time
419 zone the computer is in.
420 TZ This variable is deprecated, but will be supported for several
422 releases. The SetDate or ForceDate variables (described next)
423 should be used instead.
424 The following are equivalent:
426 $date->config("tz","Europe/Rome");
428 $date->config("setdate","now,Europe/Rome");
429 SetDate
431 The SetDate config variable is used to set the current date, time,
432 or time zone, but then allow it to change over time using the rules
433 of that time zone.
434 There are several cases where this may be useful.
436 Often, you may want to use the system time to get the date and
438 time, but you want to work in another time zone. For this, use the
439 call:
440 $date->config("setdate","now,ZONE");
442 If it is currently
444 Jun 6, 2009 12:00:00 in the America/New_York time zone
446 and you call:
448 $date->config("setdate","Europe/Rome");
450 the Date::Manip will treat that exact instant as
452 Jun 6, 2009 12:00:00 in the Europe/Rome time zone
454 At that precise moment, looking at the system time and parsing the
456 date "now" in Date::Manip will give the same date and time.
457 The time will continue to advance, but it will use time change
459 rules from the Europe/Rome time zone. What that means is that if a
460 daylight savings time occurs on the computer, but NOT in the
461 Europe/Rome time zone (or vice versa), the system date and time
462 will no longer match the results of parsing the date "now" in
463 Date::Manip.
464 In general (unless the program runs for an extended period of
466 time), the system date and time WILL match the value of "now", so
467 this is a good way to simulate placing the computer in another time
468 zone.
469 If the current date/time is ambiguous (i.e. it exists in both
471 standard and daylight saving time in the alternate zone), you can
472 use the call:
473 $date->config("setdate","now,DSTFLAG,ZONE");
475 to force it to be in one or the other. DSTFLAG can be "std", "dst",
477 "stdonly", or "dstonly". "std" and "dst" mean that the date can be
478 in either standard or saving time, but will try standard first (for
479 "dst") or saving time first (if "dst"), and will only try the other
480 if the date is not valid. If "stdonly" or "dstonly" is used, the
481 date will be forced to be standard or saving time respectively (an
482 error will be triggered if there is no valid date in that time).
483 If the current date/time doesn't exist in the alternate zone, an
485 error will occur.
486 The other common operation is that you might want to see results as
488 they would appear on a computer running in a different time zone.
489 This can be done using the call:
491 $date->config("setdate","zone,ZONE");
493 $date->config("setdate","zone,DSTFLAG,ZONE");
494 If it is currently
496 Jun 6, 2009 12:00:00 in the America/New_York time zone
498 and you call:
500 $date->config("setdate","zone,America/Chicago");
502 then parsing "now" at precisely that moment will return "Jun 6,
504 2009 11:00:00". This is equivalent to working in the current zone,
505 but then converting everything to the alternate zone.
506 Note that DSTFLAG is only used if ZONE is entered as an offset.
508 The final case where the SetDate config variable is used is to
510 alter the date and time to some other value (completely independent
511 of the current date and time) and allow it to advance normally from
512 that point.
513 $date->config("setdate","DATE");
515 $date->config("setdate","DATE,ZONE");
516 $date->config("setdate","DATE,DSTFLAG,ZONE");
517 set both the date/time and zone.
519 If DATE is not valid in the time zone (either the local time zone
521 or the specified one), and error occurs.
522 The call:
524 $date->config("setdate","now");
526 resets everything to use the current date/time and zone and lets it
528 advance normally.
529 ForceDate
531 The ForceDate config variable is similar to the SetDate variable,
532 except that once "now" is set, it is not allowed to change. Parsing
533 the date "now" will not change, regardless of how long the program
534 runs (unless either the SetDate or ForceDate variables are set to
535 some other value).
536 $date->config("forcedate","now,ZONE");
538 $date->config("forcedate","now,DSTFLAG,ZONE");
539 $date->config("forcedate","zone,ZONE");
540 $date->config("forcedate","zone,DSTFLAG,ZONE");
541 $date->config("forcedate","DATE");
542 $date->config("forcedate","DATE,ZONE");
543 $date->config("forcedate","DATE,DSTFLAG,ZONE");
544 $date->config("forcedate","now");
545 all set "now" in the same way as the SetDate variable.
547 ZONE can be any time zone name, alias, abbreviation, or offset, and the
549 best time zone will be determined from all given information.
550 It should be noted that setting the SetDate or ForceDate variable twice
552 will always refer to the system date/time as a starting point. For
553 example, if a program is running, and calls the method:
554 $date->config("forcedate","now");
556 at Jun 6, 2009 at 12:00, that time will be treated as now from that
558 point on. If the same call is done an hour later, "now" will then be
559 Jun 6, 2009 at 13:00 from that moment on.
560 Since the current date is used in the date parsing routines, no parsing
562 can be done on the DATE value in any of the calls. Instead, DATE must
563 be a date in one of the two formats:
564 YYYY-MM-DD-HH:MN:SS
566 YYYYMMDDHH:MN:SS
567
569 The following config variables are currently supported, but are
570 deprecated. They will be removed in a future Date::Manip release:
571 GlobalCnf
573 IgnoreGlobalCnf
574 PersonalCnf
575 PersonalCnfPath
576 PathSep
577 These variables are currently supported, but will be removed. These
578 have been replaced in favor of ConfigFile.
579 GlobalCnf (which is ignored in a config file, and is only useful in
581 the Date_Init call) sets the full path to a global config file.
582 IgnoreGlobalCnf is ignored completely at this point.
584 PersonalCnf is the name of a personal (or local) config file which
586 will be read in after the global config file. The file will be
587 searched for in a list of directories specified by PersonalCnfPath.
588 The list of directories is delimited by the value of PathSep.
589 In the future, the distinction between a global and personal config
591 file will be removed, and there will be no searching across a path
592 of directories. Instead, full paths will be specified using the
593 ConfigFile variable.
594 Internal
596 This is an alias for Printable. Internal was used previously
597 because the actual format of the date stored by Date::Manip would
598 actually change based on this value. Now, the internal form will
599 never change... just the printable version of it. The variable name
600 has been changed to reflect that change.
601 DeltaSigns
603 This is ignored. Use the Date::Manip::Delta::printf format to
604 format deltas as desired.
605 UpdateCurrTZ
607 This is ignored. With real time zone support, daylight savings time
608 changes are handled automatically and correctly.
609 ConvTZ
611 This is ignored. Calculations automatically handle multiple time
612 zones, so this is no longer necessary.
613 TZ This is discussed above. Use SetDate or ForceDate instead.
615
617 None known.
618
620 Please refer to the Date::Manip::Problems documentation for information
621 on submitting bug reports or questions to the author.
622
624 Date::Manip - main module documentation
625
627 This script is free software; you can redistribute it and/or modify it
628 under the same terms as Perl itself.
629
631 Sullivan Beck (sbeck@cpan.org)
632perl v5.12.0 2010-04-27 Date::Manip::Config(3)