Date-Pcalc

 view release on metacpan or  search on metacpan

lib/Date/Pcalendar/Profiles.pm  view on Meta::CPAN

    "Christmas Day"             => \&GB_Christmas,
    "Boxing Day"                => \&GB_Boxing
};

sub GB_New_Year
{
    my($year,$label) = @_;
    return( &Next_Monday($year,1,1) );
}
#
# The following formula (also from Jonathan Stowe <gellyfish@gellyfish.com>)
# also contradicts my pocket calendar, but for lack of a better guess I
# left it as it is. Please tell me the correct formula in case this one
# is wrong! Thank you!
#
sub GB_Early_May # May bank holiday is the first Monday after May 1st
{
    my($year,$label) = @_;
    if (Day_of_Week($year,5,1) == 1)
        { return( Nth_Weekday_of_Month_Year($year,5,1,2) ); }
    else
        { return( Nth_Weekday_of_Month_Year($year,5,1,1) ); }
}

lib/Date/Pcalendar/Profiles.pm  view on Meta::CPAN

    "Queen's Birthday"          => "2/Mon/Jun",
    "Royal Show (Brisbane)"     => \&AU_QLD_Brisbane
};
$Profiles->{'AU-TAS'} = # Tasmania
{
    %{$Profiles->{'AU'}},
    "New Year's Day"            => "01.01.",
    "Regatta Day"               => "2/Tue/Feb",
    "Lauceston Cup Day"         => \&AU_Lauceston,
    "King Island Show Day"      => "1/Tue/Mar", # uncertain! (maybe Tuesday after 1/Sun/Mar?)
    "Eight Hour Day"            => "2/Mon/Mar", # dubious, formula probably wrong!
    "Easter Saturday"           => "-1",
    "Queen's Birthday"          => "2/Mon/Jun",
    "Recreation Day"            => "1/Mon/Nov"  # only North Tasmania - date not confirmed!
};
$Profiles->{'AU-SA'} =  # South Australia
{
    %{$Profiles->{'AU'}},
    "New Year's Day"            => "01.01.",
    "Easter Saturday"           => "-1",
    "Adelaide Cup Day"          => "3/Mon/May", # uncertain! (maybe Monday after 3/Sun/May?)

lib/Date/Pcalendar/Profiles.pm  view on Meta::CPAN

    %{$Profiles->{'AU'}},
    "New Year's Day"            => "01.01.",
    "Labour Day"                => "1/Mon/Mar",
    "Foundation Day"            => "1/Mon/Jun",
    "Queen's Birthday"          => "1/Mon/Oct"
};
$Profiles->{'AU-ACT'} = # Australian Capital Territory
{
    %{$Profiles->{'AU'}},
    "New Year's Day"            => "01.01.",
    "Canberra Day"              => "2/Mon/Mar", # dubious, formula probably wrong!
    "Easter Saturday"           => "-1",
    "Queen's Birthday"          => "2/Mon/Jun",
    "Labour Day"                => "1/Mon/Oct"
};
$Profiles->{'AU-NSW'} = # New South Wales
{
    %{$Profiles->{'AU'}},
    "New Year's Day"            => \&AU_New_Year,
    "Easter Saturday"           => "-1",
    "Queen's Birthday"          => "2/Mon/Jun",

lib/Date/Pcalendar/Profiles.pod  view on Meta::CPAN

sets yet, or at least tell me which character set you used
so I can document this in this manual page. Thank you!)

=head1 DESCRIPTION

The method "init()" in module Date::Pcalendar::Year(3) is
responsible for parsing the calendar schemes contained
here in the Date::Pcalendar::Profiles module.

This method offers a "mini-language" which allows to
specify common date formulas, like for instance a simple
fixed date (in various different formats, e.g. american
or european), or things like "the second Sunday of May"
(Mother's Day), or "Easter Sunday minus 46 days" (Ash
Wednesday), to cite just a few.

See the section "DATE FORMULA SYNTAX" below for more
details.

There are some more complicated formulas, however, which
cannot be expressed in such simple terms.

The rule that if a holiday falls on a weekend, it will
be substituted by either the adjacent Friday or Monday
(whichever lies closer), is an example of this.

In order to be able to deal with such formulas, and in
order to be as flexible as possible, the "init()" method
offers the possibility of using callback functions to
deal with such dates and formulas.

See the section "CALLBACK INTERFACE" below for more
details on this topic.

In order to assist you with more common cases of odd
formulas, the module Date::Pcalendar::Profiles exports
the following utility subroutines (which are meant to
be used as "filters" in callback functions of your own):

=over 2

=item *

C<($year,$month,$day[,ANYTHING]) = Previous_Friday($year,$month,$day[,ANYTHING]);>

If the given date falls on a Saturday or Sunday, this

lib/Date/Pcalendar/Profiles.pod  view on Meta::CPAN

=head1 HOW TO ROLL YOUR OWN

Every calendar profile (holiday scheme) is a hash.

The name of the holiday (like "Christmas", for instance)
serves as the key in this hash and must therefore be
unique (unless you want to override a default which was
set previously, but see below for more on this).

The value for each key is either a string, which specifies
a simple date formula, or the reference of a callback function.

See the section "CALLBACK INTERFACE" above for a description
of the interface (in and out) of these callback functions.

See the section "DATE FORMULA SYNTAX" above and the description
of the "init()" method in L<Date::Pcalendar::Year(3)> for the
exact syntax of date formula strings.

B<BEWARE> that if keys are not unique in the source code,
later entries will overwrite previous ones! I.e.,

    ...
    "My special holiday" => "01-11",
    "My special holiday" => "02-11",
    ...

will B<NOT> set two holidays of the same name, one on November

lib/Date/Pcalendar/Profiles.pod  view on Meta::CPAN

historical irregularities into account (even though some do in order
to show how this can be done), they only provide means for calculating
B<regularly> recurring events (B<the profiles should therefore not be
relied upon for historical faithfulness>).

=head1 KNOWN BUGS

The australian calendar profiles are known to contain wrong dates.
This is due to the fact that Australia decrees its holidays individually
for each year, difficulting the calculation of the holidays by way of
a formula. An effort to compare (and to correct) the current implementation
with official documents (web pages) by the Australian authorities is under
way. This hasn't been finished yet because it is very time-consuming.

=head1 VERSION

This man page documents "Date::Pcalendar::Profiles" version 6.1.

=head1 AUTHOR

  Steffen Beyer

lib/Date/Pcalendar/Year.pod  view on Meta::CPAN

C<$year = Date::Pcalendar::Year-E<gt>new( 2001, {} );>

This is the constructor method. Call it to create a new
Date::Pcalendar::Year object.

The first argument must be a year number in the range
[1583..2299].

The second argument must be the reference of a hash,
which usually contains names of holidays and commemorative
days as keys and strings containing the date or formula
for each holiday as values.

Reading this hash and initializing the object's internal
data is performed by an extra method, called "init()",
which is called internally by the constructor method,
and which is described immediately below, after this
method.

In case you want to call the "init()" method yourself,
explicitly, after creating the object, you can pass an
empty profile (e.g., just an empty anonymous hash) to
the "new()" method, in order to create an empty object,
and also to improve performance.

The third argument is optional, and must consist of
the valid name or number of a language as provided by
the Date::Pcalc(3) module, if given.

This argument determines which language shall be used
when reading the profile, since the profile may contain
names of months and weekdays in its formulas in that
language.

The default is English if no value or no valid value
is specified (and if the global default has not been
changed with "Language()").

After the third argument, a list of day numbers which
will constitute the "weekend" can optionally be specified,
where 1=Monday, 2=Tuesday, 3=Wednesday, 4=Thursday,
5=Friday, 6=Saturday and 7=Sunday.

lib/Date/Pcalendar/Year.pod  view on Meta::CPAN

All other types of dates must be specified via callback
functions.

Note that the "last" of a given day of week is written as
the "5th", because the last is always either the 5th or the
4th of the given day of week. So the "init()" module first
calculates the 5th of the requested day of week, and if that
doesn't exist, takes the 4th instead.

There are also two modifier characters which may prefix the
string with the date formula, "#" and ":".

The character "#" (mnemonic: it's only a comment) signals
that the date in question is a purely commemorative day,
i.e., it will not enter into any date calculations, but
can be queried with the "labels()" and "search()" methods,
and appears when printing a calendar, for instance.

The character ":" (mnemonic: divided into two halfs) specifies
that the date in question is only a "half" holiday, i.e., you
only get half a day off instead of a full day. Some companies
have this sort of thing. C<:-)>

The exact syntax for the date formula strings is the following
(by example):

 -  Fixed dates:

    "Christmas"  =>  "24.12",   # European format (day, month)
    "Christmas"  =>  "24.12.",

    "Christmas"  =>  "24Dec",
    "Christmas"  =>  "24.Dec",
    "Christmas"  =>  "24Dec.",

lib/Date/Pcalendar/Year.pod  view on Meta::CPAN

 -  The 1st, 2nd, 3rd, 4th or last day of week:

    "Thanksgiving"      =>  "4Thu11",
    "Thanksgiving"      =>  "4/Thu/Nov",
    "Columbus Day"      =>  "2/Mon/Oct",
    "Columbus Day"      =>  "2/Mon/10",
    "Columbus Day"      =>  "2/1/Oct",
    "Columbus Day"      =>  "2/1/10",
    "Memorial Day"      =>  "5/Mon/May", # LAST Monday of May

Remember that each of these date formula strings may
also be prefixed with either "#" or ":":

    "Christmas"         =>  ":24.12.", # only half a day off
    "Valentine's Day"   =>  "#Feb/14", # not an official holiday

Note that the name of the month or day of week may have any
length you like, it just must specify the intended month or
day of week unambiguously. So "D", "De", "Dec", "Dece",
"Decem", "Decemb", "Decembe" and "December" would all
be valid, for example. Note also that case is ignored.

lib/Date/Pcalendar/Year.pod  view on Meta::CPAN

(See also the description of the three methods "vec_full()",
"vec_half()" and "vec_full()" immediately below.)

It then sets the bits which correspond to Saturdays and
Sundays (or optionally to the days whose numbers have been
specified as the "weekend") in the "full holidays" bit vector.

At last, it iterates over the keys of the given holiday
scheme (of the hash referred to by the hash reference
passed to the "init()" method as the second argument),
evaluates the formula (or calls the given callback
function), and sets the corresponding bit in the "full"
or "half" holidays bit vector if the calculated date
is valid.

A fatal error occurs if the date formula cannot be parsed
or if the date returned by a formula or callback function
is invalid (e.g. 30-Feb-2001 or the like) or lies outside
the given year (e.g. Easter+365).

Finally, the "init()" method makes sure that days marked
as "full" holidays do not appear as "half" holidays as
well.

Then the "init()" method returns.

Note that when deciphering the date formulas, the "init()"
method uses the functions "Decode_Day_of_Week()" and
"Decode_Month()" from the Date::Pcalc(3) module, which
are language-dependent.

Therefore the "init()" method allows you to pass it an optional
third argument, which must consist of the valid name or number
of a language as provided by the Date::Pcalc(3) module.

For the time of scanning the given holiday scheme, the "init()"
method will use the language that has been specified, or the