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 Multiple config files are safe, and a section may safely be split
175 across multiple files.
176 Language
178 Date::Manip can be used to parse dates in many different languages.
179 A list of the languages is given in the Date::Manip::Lang document.
180 To parse dates in a different language, just use the Language
182 config variable with the name of the language as the value.
183 Language names are case insensitive.
184 Additional languages may be added with the help of someone fluent
186 in English and the other language. If you are interested in
187 providing a translation for a new language, please refer to the
188 Date::Manip::Lang document for instructions.
189 Encoding
191 Date::Manip has some support for handling date strings encoded in
192 alternate character encodings.
193 By default, input strings may be tested using multiple encodings
195 that are commonly used for the specific languages, as well as using
196 standard perl escape sequences, and output is done in UTF-8.
197 The input, output, or both can be overridden using the Encoding
199 variable.
200 Setting Encoding to the name of a single encoding (a name supported
202 by the Encoding perl module), will force all input and output to be
203 done in that encoding.
204 So, setting:
206 Encoding = iso-8859-1
208 means that all input and output will be in that encoding. The
210 encoding 'perl' has the special meaning of storing the string in
211 perl escape sequences.
212 Encoding can also be set to the name of two encoding (separated by
214 a comma).
215 Encoding = iso-8859-1,utf-16
217 which means that all input is in iso-8859-1 encoding, but all
219 output will be utf-16.
220 Encoding may also be set as follows:
222 Encoding = iso-8859-1,
224 meaning that input is in iso-8859-1 and output is in the default
226 (i.e. UTF-8) encoding.
227 Encoding = ,utf-16
229 means to check the input in all of the encodings, but all output
231 will be in utf-16 encoding.
232 Note that any time you change languages, it will reset the
234 encodings, so you should set this config variable AFTER setting the
235 language.
236 DateFormat
238 Different countries look at the date 12/10 as Dec 10 or Oct 12. In
239 the United States, the first is most common, but this certainly
240 doesn't hold true for other countries. Setting DateFormat to "US"
241 (case insensitive) forces the first behavior (Dec 10). Setting
242 DateFormat to anything else forces the second behavior (Oct 12).
243 The "US" setting is the default (sorry about that... I live in the
244 US :-).
245 YYtoYYYY
247 When parsing a date containing a 2-digit year, the year must be
248 converted to 4 digits. This config variable determines how this is
249 done.
250 By default, a 2 digit year is treated as falling in the 100 year
252 period of CURR-89 to CURR+10. So in the year 2005, a two digit year
253 will be somewhere in the range 1916 to 2015.
254 YYtoYYYY may be set to any integer N to force a 2 digit year into
256 the period CURR-N to CURR+(99-N). A value of 0 forces the year to
257 be the current year or later. A value of 99 forces the year to be
258 the current year or earlier. Although the most common choice of
259 values will be somewhere between 0 and 99, there is no restriction
260 on N that forces it to be so. It can actually be any positive or
261 negative number you want to force it into any 100 year period
262 desired.
263 YYtoYYYY can also be set to "C" to force it into the current
265 century, or to "C##" to force it into a specific century. So, in
266 1998, "C" forces 2 digit years to be 1900-1999. "C18" would always
267 force a 2 digit year to be in the range 1800-1899. Note: I'm aware
268 that the actual definitions of century are 1901-2000, NOT
269 1900-1999, so for purists, treat this as the way to supply the
270 first two digits rather than as supplying a century.
271 It can also be set to the form "C####" to force it into a specific
273 100 year period. C1950 refers to 1950-2049.
274 FirstDay
276 It is sometimes necessary to know what day of week is regarded as
277 first. By default, this is set to Monday as that conforms to ISO
278 8601, but many countries and people will prefer Sunday (and in a
279 few cases, a different day may be desired). Set the FirstDay
280 variable to be the first day of the week (1=Monday, 7=Sunday).
281 Jan1Week1
283 ISO 8601 states that the first week of the year is the one which
284 contains Jan 4 (i.e. it is the first week in which most of the days
285 in that week fall in that year). This means that the first 3 days
286 of the year may be treated as belonging to the last week of the
287 previous year. If this is set to non-nil, the ISO 8601 standard
288 will be ignored and the first week of the year contains Jan 1.
289 Printable
291 Some commands may produce a printable version of a date. By
292 default, the printable version of the date is of the format:
293 YYYYMMDDHH:MN:SS
295 Two other simple versions have been created. If the Printable
297 variable is set to 1, the format is:
298 YYYYMMDDHHMNSS
300 If Printable is set to 2, the format is:
302 YYYY-MM-DD-HH:MN:SS
304 This config variable is present in order to maintain backward
306 compatibility, and may actually be deprecated at some point. As
307 such, additional formats will not be added. Instead, use the printf
308 method in the Date::Manip::Date module to extract information with
309 complete flexibility.
310 DefaultTime
312 When a date is parsed from one of the formats listed in the "Common
313 date formats" or "Less common formats" sections of the
314 Date::Manip::Date document, and no time is explicitly included, the
315 default time can be determined by the value of this variable. The
316 two possible values are:
317 midnight the default time is 00:00:00
319 curr the default time is the current time
320 "midnight" is the default value.
322 NOTE: this only applies to dates parsed with the parse method.
324 Dates parsed using the parse_date method always default to
325 00:00:00.
326 PeriodTimeSep
328 By default, the only default time separator is a colon (:), so the
329 time can be written as 12:15:30 .
330 If you want to use a period (.) as a time separator as well, set
332 this to 1. Then you can write the time as 12.15.30 .
333 By default, a period is used as a date separator, so 12.15.30 would
335 be interpreted as Dec 15 1930 (or 2030), so if you use the period
336 as a date separator, it should not be used as a time separator too.
337
339 These are configuration variables used to define work days and holidays
340 used in business mode calculations. Refer to the Date::Manip::Calc
341 documentation for details on these calculations.
342 WorkWeekBeg
344 WorkWeekEnd
345 The first and last days of the work week. These default to Monday
346 and Friday. Days are numbered from 1 (Monday) to 7 (Sunday).
347 WorkWeekBeg must come before WorkWeekEnd numerically so there is no
348 way to handle a work week of Sunday to Thursday using these
349 variables.
350 There is also no way to handle an odd work schedule such as 10 days
352 on, 4 days off.
353 However, both of these situations can be handled using a fairly
355 simple workaround.
356 To handle a work week of Sunday to Thursday, just set WorkWeekBeg=1
358 and WorkWeekEnd=7 and defined a holiday that occurs every Friday
359 and Saturday.
360 To handle a 10 days on, 4 days off schedule, do something similar
362 but defined a holiday that occurs on all of the 4 days off.
363 Both of these can be done using recurrences. Refer to the
365 Date::Manip::Recur documentation for details.
366 WorkDay24Hr
368 WorkDayBeg
369 WorkDayEnd
370 If WorkDay24Hr is non-zero, a work day is treated as usually being
371 24 hours long (daylight saving time changes ARE taken into
372 account). The WorkDayBeg and WorkDayEnd variables are ignored in
373 this case.
374 By default, WorkDay24Hr is zero, and the work day is defined by the
376 WorkDayBeg and WorkDayEnd variables. These are the times when the
377 work day starts and ends respectively. WorkDayBeg must come before
378 WorkDayEnd (i.e. there is no way to handle the night shift where
379 the work day starts one day and ends another).
380 The time in both should be a valid time format (H, H:M, or H:M:S).
382 Note that setting WorkDay24Hr to a non-zero value automatically
384 sets WorkDayBeg and WorkDayEnd to "00:00:00" and "24:00:00"
385 respectively, so to switch back to a non-24 hour day, you will need
386 to reset both of those config variables.
387 Similarly, setting either the WorkDayBeg or WorkDayEnd variables
389 automatically turns off WorkDay24Hr.
390 TomorrowFirst
392 Periodically, if a day is not a business day, we need to find the
393 nearest business day to it. By default, we'll look to "tomorrow"
394 first, but if this variable is set to 0, we'll look to "yesterday"
395 first. This is only used in the
396 Date::Manip::Date::nearest_business_day method (and the
397 Date_NearestWorkDay function) and is easily overridden (see
398 documentation for the nearest_business_day method).
399 EraseHolidays
401 EraseEvents
402 If these variables are used (a value must be passed in, but is
403 ignored), the current list of defined holidays or events is erased.
404 A new set will be set the next time a config file is read in.
405 Although these variables are supported, the best way to have
407 multiple holiday or events lists will be to create multiple
408 Date::Manip::Base objects based on separate config files.
409
411 The following config variables help in the handling of recurrences.
412 RecurRange
414 When a recurrence is created, it begins with a default range (start
415 and end date). The range selected depends on the value of this
416 variable, and can be set to any of the following:
417 none no default range supplied
419 year the current year
420 month the current month
421 week the current week
422 day the current day
423 all Jan 2, 0001 to Dec 30, 9999
424 The default value is "none".
426
428 The following configuration variables may alter the current time zone.
429 As such, they are only available once the Date::Manip::TZ module is
430 available. An easy way to handle this is to only pass them to the
431 config method of a Date::Manip::TZ object or one of the high level
432 objects (Date::Manip::Date, Date::Manip::Delta, or Date::Manip::Recur).
433 Many of Date::Manip's operations rely on knowing what time it is now.
435 This consists of three things: knowing what date and time it is,
436 knowing what time zone it is, and knowing whether it is daylight saving
437 or not. All of this is necessary in order to correctly handle every
438 possible date.
439 The daylight saving time information is only used for a couple hours
441 each year during daylight saving time changes (at all other times, the
442 date, time, and time zone are sufficient information), so it is
443 optional, and defaults to standard time if omitted.
444 The default behavior of Date::Manip is to use the system localtime
446 function to determine the date, time, and daylight saving time
447 information, and to use various methods (see DETERMINING THE SYSTEM
448 TIME ZONE in the Date::Manip::TZ documentation) to determine what time
449 zone the computer is in.
450 TZ This variable is deprecated, but will be supported for several
452 releases. The SetDate or ForceDate variables (described next)
453 should be used instead.
454 The following are equivalent:
456 $date->config("tz","Europe/Rome");
458 $date->config("setdate","now,Europe/Rome");
459 SetDate
461 The SetDate config variable is used to set the current date, time,
462 or time zone, but then allow it to change over time using the rules
463 of that time zone.
464 There are several cases where this may be useful.
466 Often, you may want to use the system time to get the date and
468 time, but you want to work in another time zone. For this, use the
469 call:
470 $date->config("setdate","now,ZONE");
472 If it is currently
474 Jun 6, 2009 12:00:00 in the America/New_York time zone
476 and you call:
478 $date->config("setdate","Europe/Rome");
480 the Date::Manip will treat that exact instant as
482 Jun 6, 2009 12:00:00 in the Europe/Rome time zone
484 At that precise moment, looking at the system time and parsing the
486 date "now" in Date::Manip will give the same date and time.
487 The time will continue to advance, but it will use time change
489 rules from the Europe/Rome time zone. What that means is that if a
490 daylight saving time occurs on the computer, but NOT in the
491 Europe/Rome time zone (or vice versa), the system date and time
492 will no longer match the results of parsing the date "now" in
493 Date::Manip.
494 In general (unless the program runs for an extended period of
496 time), the system date and time WILL match the value of "now", so
497 this is a good way to simulate placing the computer in another time
498 zone.
499 If the current date/time is ambiguous (i.e. it exists in both
501 standard and daylight saving time in the alternate zone), you can
502 use the call:
503 $date->config("setdate","now,DSTFLAG,ZONE");
505 to force it to be in one or the other. DSTFLAG can be "std", "dst",
507 "stdonly", or "dstonly". "std" and "dst" mean that the date can be
508 in either standard or saving time, but will try standard first (for
509 "dst") or saving time first (if "dst"), and will only try the other
510 if the date is not valid. If "stdonly" or "dstonly" is used, the
511 date will be forced to be standard or saving time respectively (an
512 error will be triggered if there is no valid date in that time).
513 If the current date/time doesn't exist in the alternate zone, an
515 error will occur.
516 The other common operation is that you might want to see results as
518 they would appear on a computer running in a different time zone.
519 This can be done using the call:
521 $date->config("setdate","zone,ZONE");
523 $date->config("setdate","zone,DSTFLAG,ZONE");
524 If it is currently
526 Jun 6, 2009 12:00:00 in the America/New_York time zone
528 and you call:
530 $date->config("setdate","zone,America/Chicago");
532 then parsing "now" at precisely that moment will return "Jun 6,
534 2009 11:00:00". This is equivalent to working in the current zone,
535 but then converting everything to the alternate zone.
536 Note that DSTFLAG is only used if ZONE is entered as an offset.
538 The final case where the SetDate config variable is used is to
540 alter the date and time to some other value (completely independent
541 of the current date and time) and allow it to advance normally from
542 that point.
543 $date->config("setdate","DATE");
545 $date->config("setdate","DATE,ZONE");
546 $date->config("setdate","DATE,DSTFLAG,ZONE");
547 set both the date/time and zone.
549 If DATE is not valid in the time zone (either the local time zone
551 or the specified one), and error occurs.
552 The call:
554 $date->config("setdate","now");
556 resets everything to use the current date/time and zone and lets it
558 advance normally.
559 ForceDate
561 The ForceDate config variable is similar to the SetDate variable,
562 except that once "now" is set, it is not allowed to change. Parsing
563 the date "now" will not change, regardless of how long the program
564 runs (unless either the SetDate or ForceDate variables are set to
565 some other value).
566 $date->config("forcedate","now,ZONE");
568 $date->config("forcedate","now,DSTFLAG,ZONE");
569 $date->config("forcedate","zone,ZONE");
570 $date->config("forcedate","zone,DSTFLAG,ZONE");
571 $date->config("forcedate","DATE");
572 $date->config("forcedate","DATE,ZONE");
573 $date->config("forcedate","DATE,DSTFLAG,ZONE");
574 $date->config("forcedate","now");
575 all set "now" in the same way as the SetDate variable. Spaces
577 after commas are ignored.
578 ZONE can be any time zone name, alias, abbreviation, or offset, and the
580 best time zone will be determined from all given information.
581 It should be noted that setting the SetDate or ForceDate variable twice
583 will always refer to the system date/time as a starting point. For
584 example, if a program is running, and calls the method:
585 $date->config("forcedate","now");
587 at Jun 6, 2009 at 12:00, that time will be treated as now from that
589 point on. If the same call is done an hour later, "now" will then be
590 Jun 6, 2009 at 13:00 from that moment on.
591 Since the current date is used in the date parsing routines, no parsing
593 can be done on the DATE value in any of the calls. Instead, DATE must
594 be a date in one of the two formats:
595 YYYY-MM-DD-HH:MN:SS
597 YYYYMMDDHH:MN:SS
598
600 The following config variables are currently supported, but are
601 deprecated. They will be removed in a future Date::Manip release:
602 TZ This is discussed above. Use SetDate or ForceDate instead.
604 Scheduled for removal 2013-12-01 .
606
608 None known.
609
611 Please refer to the Date::Manip::Problems documentation for information
612 on submitting bug reports or questions to the author.
613
615 Date::Manip - main module documentation
616
618 This script is free software; you can redistribute it and/or modify it
619 under the same terms as Perl itself.
620
622 Sullivan Beck (sbeck@cpan.org)
623perl v5.16.3 2014-06-09 Date::Manip::Config(3)