NAME

Date::Holidays::BY - Determine public holidays and business days in Belarus.

SYNOPSIS

use Date::Holidays::BY;

my $holidays = Date::Holidays::BY::holidays( 2024 );
  # {
  #   "0101" => "New Year",
  #   ...
  #   "1225" => "Christmas (Catholic Christmas)"
  # }

if ( my $holidayname = Date::Holidays::BY::is_holiday( 2007, 1, 1 ) ) {
    print "Is a holiday: $holidayname\n";
}

if ( Date::Holidays::BY::is_business_day( 2012, 3, 11 ) ) {
    print "2012-03-11 is a business day on a weekend\n";
}

if ( Date::Holidays::BY::is_short_business_day( 2015, 4, 30 ) ) {
    print "2015-04-30 is a short business day\n";
}

my $short_days = Date::Holidays::BY::short_business_days( 2024 );
  # {
  #   "0307" => "Pre-holiday working day",
  #   ...
  #   "1231" => "Pre-holiday working day"
  # }

DESCRIPTION

Date::Holidays::BY provides functions to check if a given date is a public holiday in Belarus. This module follows the standard holiday calendar observed in Belarus, including both national holidays and specific religious observances recognized in the country.

Imports nothing by default.

CONFIGURATION VARIABLES

$Date::Holidays::BY::ref

Hash reference containing all static holiday data, including holiday names for i18n support. Dates are formatted as MMDD.

HOLIDAYS_VALID_SINCE

$Date::Holidays::BY::ref->{'HOLIDAYS_VALID_SINCE'}

The module is only relevant from this year onward. Throws an exception (croak) for dates before this year.

INACCURATE_TIMES_BEFORE - INACCURATE_TIMES_SINCE

$Date::Holidays::BY::ref->{'INACCURATE_TIMES_BEFORE'}

$Date::Holidays::BY::ref->{'INACCURATE_TIMES_SINCE'}

The regular public holidays are defined for all years, but the exact postponements of days off are known only within this period. Outside it, in strict mode ($Date::Holidays::BY::strict=1) an exception is thrown (croak).

$Date::Holidays::BY::strict

If true, throws an exception (croak) when the requested year is outside the period for which the data is defined. Default is 0.

$Date::Holidays::BY::lang

The language is determined from the locale in $ENV{LC_ALL}, $ENV{LC_MESSAGES} or $ENV{LANG} (in this order of priority). You can override it after loading the module.

FUNCTIONS

holidays( $year )

Returns a hash reference of all holidays in the year.

{
  MMDD => 'name',
  ...
}

The result is cached for the selected language and year in $Date::Holidays::BY::ref->{'cache'}.

The returned hash reference is the cache itself, not a copy. Changes made to it (for example, adding your own days) are visible to is_holiday() and is_business_day() until the cache is cleared (see "I18N").

Throws an exception (croak) if the year is not valid.

is_holiday( $year, $month, $day )

Determines whether the date is a public holiday in Belarus. Returns the holiday name or undef.

Throws an exception (croak) if the date is invalid.

is_by_holiday( $year, $month, $day )

Alias for is_holiday().

is_business_day( $year, $month, $day )

Returns true if the date is a business day in Belarus, taking holidays, weekends and working days on weekends into account.

Throws an exception (croak) if the date is invalid.

short_business_days( $year )

Returns hash ref of all shortened business days in the year.

{
  MMDD => 'name',
  ...
}

A shortened business day is a business day immediately preceding a public holiday (Labor Code of the Republic of Belarus, art. 116), its length is reduced by one hour. The days are calculated by this rule.

The result is cached in $Date::Holidays::BY::ref->{'cache'} like in holidays().

is_short_business_day( $year, $month, $day )

Returns true if date is a shortened business day. See short_business_days().

Throws an exception (croak) if the date is invalid.

I18N

Translations are available in Belarusian (be), English (en), and Russian (ru), with the language selected from the locale in $ENV{LC_ALL}, $ENV{LC_MESSAGES} or $ENV{LANG} (in this order of priority). If the locale is not one of these, "en" is used. See $Date::Holidays::BY::lang.

Holiday names can be redefined in $Date::Holidays::BY::ref:

use Date::Holidays::BY;

$Date::Holidays::BY::ref->{'HOLIDAYS'}->{'0308'}->{'name'}->{'en'} = 'name1';

say Date::Holidays::BY::holidays(2024)->{'0308'}; # name1

$Date::Holidays::BY::ref->{'HOLIDAYS'}->{'0308'}->{'name'}->{'en'} = 'name2';
$Date::Holidays::BY::ref->{'cache'} = undef;

say Date::Holidays::BY::holidays(2024)->{'0308'}; # name2

LICENSE

This software is copyright (c) 2026 by Vladimir Varlamov.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

Terms of the Perl programming language system itself

a) the GNU General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version, or b) the "Artistic License"

AUTHOR

Vladimir Varlamov, <bes.internal@gmail.com>

cpanm Date::Holidays::BY

perl -MCPAN -e shell
install Date::Holidays::BY