Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Date::Manip::Holidays(User Contributed Perl DocumentatDate::Manip::Holidays(3)

NAME
       Date::Manip::Holidays - describes holidays and events

SYNOPSIS
       This describes the Holidays and Events sections of the config file, and
       how they	are used.

       Holidays	and events are specific	days that are named. Holidays are used
       in business mode	calculations, events are not. Events may be used for
       other calendaring operations.

HOLIDAYS
       The holiday section of the config file is used to define	holidays.
       Each line is of the form:

	  STRING = HOLIDAY

       HOLIDAY is the name of the holiday or it	can be blank.

       If HOLIDAY is blank, the	holiday	is unnamed, but	still treated as a
       holiday.	 For example, in the US, the day after Thanksgiving is often a
       work holiday though it is not named.

       HOLIDAY should be unique	in most	cases.	The only exception is if the
       holiday definition is complex enough that it is impossible to describe
       it with one STRING.  In this case, multiple lines may be	given with
       different values	of STRING but the same value for HOLIDAY, and in these
       cases, the first	STRING that matches a given year will be used.	This
       situation is described in more detail below.

       NOTE: It	is not allowed to have unnamed holidays	that require multiple
       definitions, so a name will have	to be assigned in that case.

       STRING is a string which	can be parsed to give a	valid date. It can be
       any of the following forms:

       A full date
	   Specific holidays can be set	which occur only a single time.

	      May 5, 2000		      =	A one-time-only	holiday

	   Any format parseable	by "Date::Manip::Date::parse_date" can be
	   used.

	   There is one	caveat to using	a full date.  Date::Manip assumes that
	   most	holidays will appear once per year, so if you were to
	   explicitly defined New Years	(observed) as:

	      2004-12-31		      =	New Year's Day

	   then	it would assume	that it	had found the occurrence of New	Year's
	   for 2004 when in fact, this is the 2005 occurrence.

	   Full	date specifications should only	be used	as a last resort, and
	   probably only if you	will explicitly	specify	all occurrence of the
	   holiday.

       A date without a	year
	   Some	holidays occur every year on the same day. These can be
	   defined using the simple lines:

	      Jan 1			      =	New Year's Day
	      Jul 4th			      =	Independence Day
	      fourth Thu in Nov		      =	Thanksgiving

	   These dates must be written in a form which can be parsed as	a full
	   date	by simply adding the year to the end of	the string. Please
	   refer to the	Date::Manip::Date documentation	to see what forms will
	   work. ISO 8601 dates	will not work since the	year comes first.

	   Any format parseable	by "Date::Manip::Date::parse_date" which
	   allows the year to be at the	end can	be used.

       Recurrence
	   The dates can be specified using recurrences:

	      1*0:0:0:0:0:0*EASTER	      =	Easter
	      1*11:0:11:0:0:0*DWD	      =	Veteran's Day
	      1*11:4:4:0:0:0		      =	Thanksgiving
	      1*11:4:4:0:0:0*FD1	      =	Day after Thanksgiving

	   In cases where you are interested in	business type calculations,
	   you'll want to define most holidays using recurrences, since	they
	   can define when a holiday is	celebrated in the financial world.
	   For example,	Christmas might	be defined as:

	      Dec 25		   = Christmas

	   but if it falls on a	weekend, there won't be	a business holiday
	   associated with it. It could	be defined using a recurrence:

	      1*12:0:24:0:0:0*DWD  = Christmas

	   so that if Christmas	falls on a weekend, a holiday will be taken on
	   the Friday before or	the Monday after the weekend.

	   You can use the fully specified format of a recurrence:

	     1*2:0:1:0:0:0***Jan 1 1999*Dec 31 2002 = Feb 2 from 1999-2002

OTHER HOLIDAY CONSIDERATIONS
       Recurrences which change	years
	   It is now valid to have a recurrence	defined	for New	Year's day
	   which pushes	the holiday to the previous year.

	   For example,	the most useful	definition of New Year's day is:

	      1*1:0:1:0:0:0*DWD		      =	New Year's Day

	   which means to choose the closest working day to observe the
	   holiday, even though	this might mean	that the holiday is observed
	   on the previous year.

       Order of	definitions is preserved
	   The order of	the definitions	is preserved. In other words, when
	   looking at the holidays for a year, previously defined holidays (in
	   the order given in the config file) are correctly handled.

	   As an example, if you wanted	to define both Christmas and Boxing
	   days	(Boxing	is the day after Christmas, and	is celebrated in some
	   parts of the	world),	and you	wanted to celebrate Christmas on a
	   business day	on or after Dec	25, and	Boxing day as the following
	   work	day, you could do it in	one of the following ways:

	      1*12:0:25:0:0:0*NWD  = Christmas
	      1*12:0:26:0:0:0*NWD  = Boxing

	   or

	      1*12:0:25:0:0:0*NWD  = Christmas
	      1*12:0:25:0:0:0*NWD  = Boxing

	   Holidays go into affect the minute they are parsed which is why the
	   second example works	(though	for clarity, the first one is
	   preferable).	 The first recurrence defined the first	business day
	   on or after Dec 25 as Christmas.  The second	one then defines the
	   business day	after that as Boxing day.  Since the definitions are
	   stored as a list (NOT a hash	as they	were in	Date::Manip 5.xx),
	   using the same recurrence twice does	not cause a problem.

       Multiple	holidays
	   Having multiple holidays on a single	day is allowed.	As an example,
	   you may want	to look	at New Years day as both the observed and
	   actual holidays, so you might have:

	      1*1:0:1:0:0:0*DWD		      =	New Year's Day (observed)
	      Jan 1			      =	New Year's Day

	   Most	of the time, both will fall on the same	day, but sometimes
	   they	may differ.  In	this example, it is important that the
	   observed holiday be listed first.  Otherwise, Jan 1 will be marked
	   as a	holiday	and then the observed date will	check Jan 1, but where
	   it is not a business	day, it	will move to another day (due to the
	   DWD modifier).

	   Likewise, the two holidays:

	      3rd Sunday in June	      =	Father's Day
	      Jun 17			      =	Bunker Hill Day

	   sometimes fall on the same day.  Using the
	   "Date::Manip::Date::list_holidays" method (or the "Date_IsHoliday"
	   function), you can get a list of all	names that the date contains.

       Complex holiday descriptions
	   Occasionally, you cannot describe a holiday using a single line.
	   For example,	the US Federal Reserve banks use a complex holiday
	   description where:

	      For holidays falling on Saturday,	Federal	Reserve	Banks
	      and Branches will	be open	the preceding Friday. For holidays
	      falling on Sunday, all Federal Reserve Banks and Branches
	      will be closed the following Monday.

	   Since Saturday is not a business day, the DWD modifier will not
	   work.  For these, you need a	more complicated definition.

	   The following definitions both work:

	      #	Saturday
	      1*1:0:1:0:0:0*NBD,BD1,IBD,FD1   =	New Year's Day
	      #	Sunday (observed Monday)
	      1*1:0:1:0:0:0*NBD,BD1,NBD,FD2   =	New Year's Day
	      #	M-F
	      1*1:0:1:0:0:0*IBD		      =	New Year's Day

	   and

	      #	Saturday
	      1*1:0:1:0:0:0*IW6		      =	New Year's Day
	      #	Sunday (observed Monday)
	      1*1:0:1:0:0:0*IW7,FD1	      =	New Year's Day
	      #	M-F
	      1*1:0:1:0:0:0*IBD		      =	New Year's Day

EVENTS
       The Events section of the config	file is	similar	to the Holiday
       section.	 It is used to name certain days or times, but there are a few
       important differences:

       Events can be assigned to any time and duration
	   All holidays	are exactly 1 day long.	 They are assigned to a	period
	   of time from	midnight to midnight.

	   Events can be based at any time of the day, and may be of any
	   duration.

       Events don't affect business mode calculations
	   Unlike holidays, events are completely ignored when doing business
	   mode	calculations.

       Whereas holidays	were added with	business mode math in mind, events
       were added with calendar	and scheduling applications in mind.

       Every line in the events	section	is of the form:

	  EVENT	= NAME

       where NAME is the name of the event, and	EVENT defines when it occurs
       and its duration.  An EVENT can be defined in the following ways:

	  Date
	  YMD
	  YM
	  Recur

	  Date	; Date
	  YMD	; YMD
	  YM	; YM
	  Date	; Delta
	  Recur	; Delta

       Date refers to a	full date/time (and is any string that can be parsed
       by "Date::Manip::Date::parse"). YMD is any string which can be parsed
       by "Date::Manip::Date::parse_date". YM is any string which can be
       parsed by the parse_date	method to give a date in the current year.
       Recur is	a partial or fully specified recurrence. Delta is any string
       that can	be parsed to form a delta.

       With the	"Date" form, or	the "Recur" form, the event starts at the time
       (or times) specified by the date	or recurrence, and last	1 hour long.
       With the	"YMD" and "YM" forms, the event	occurs on the given day, and
       lasts all day.

       With all	of the two part	forms ("Date;Date", "YM;YM", etc.), the	event
       starts at the first date	and goes to the	second date, or	goes an	amount
       of time specified by the	delta.

       The "YMD;YMD" and "YM;YM" forms means that the event lasts from the
       start of	the first date to the end of the second. In the	Date;Date
       form, the event goes from the first date	to the second date inclusive.
       In other	words, both dates are in the event. In the "Date;Delta"	and
       "Recur;Delta" forms, the	Delta tells the	length of the event. Also, in
       the Date;Date form, the second date may NOT be expressed	as a delta.

       Currently, having an event longer than 1	year is	NOT supported, but no
       checking	is done	for this.

KNOWN BUGS
       None known.

BUGS AND QUESTIONS
       Please refer to the Date::Manip::Problems documentation for information
       on submitting bug reports or questions to the author.

SEE ALSO
       Date::Manip	  - main module	documentation

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

AUTHOR
       Sullivan	Beck (sbeck@cpan.org)

perl v5.32.1			  2020-06-01	      Date::Manip::Holidays(3)

NAME | SYNOPSIS | HOLIDAYS | OTHER HOLIDAY CONSIDERATIONS | EVENTS | KNOWN BUGS | BUGS AND QUESTIONS | SEE ALSO | LICENSE | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Date::Manip::Holidays&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help