NAME
Calendar::Dates - Modules that contain calendar dates

SPECIFICATION VERSION
0.1

VERSION
This document describes version 0.2.3 of Calendar::Dates (from Perl
distribution Calendar-Dates), released on 2019-06-22.

DESCRIPTION
The "Calendar::Dates::*" namespace is reserved for modules that provide
calendar dates using a common interface. The interface is designed to
be: simple to implement, lightweight, and easy to use and export (e.g.
to an iCal calendar).

Conventions for subdivision under the "Calendar::Dates::" namespace:

* Country-specific calendars go to <XX>::*, where <XX> is the
ISO3166-1 2-letter country code

Examples:

Calendar::Dates::SG::Events
Calendar::Dates::SG::FestivalsEvents
Calendar::Dates::ID::Tax

* Country-specific (public) holiday calendars go to <XX>::Holiday::*

Examples:

Calendar::Dates::US::Holiday

* Region/province- and locality-specific calendars go to
<CC>::<Name>::*

Examples:

Calendar::Dates::ID::Jakarta::Events

* Year number can be added as the last component if the module only
supports a specific year

Examples:

Calendar::Dates::ID::Holiday::2019

* Religion-related calendars go to Religion::<Name>::*

Examples:

Calendar::Dates::Religion::Christianity

* Sports-related calendars go to Sports::*

Examples:

Calendar::Dates::Sports::WTA
Calendar::Dates::Sports::WTA::2019
Calendar::Dates::ID::Jakarta::Sports::Marathon

STATUS
Draft series (0.x), expected to be stable in 1.0.

METHODS
get_min_year
Usage:

my $min_year = Calendar::Dates::Foo->get_min_year;

Return the earliest year that the module has dates for. See also
"get_max_year". Note that the module might not support some years
between the earliest and latest years.

get_max_year
Usage:

my $max_year = Calendar::Dates::Foo->get_max_year;

Return the latest year that the module has dates for. See also
"get_min_year". Note that the module might not support some years
between the earliest and latest years.

get_entries
Usage:

my $entries = Calendar::Dates::Foo->get_entries([ \%params, ] $year [, $mon [, $day ] ]);

Return entries for a particular year (or month, or day). Method must die
if year (or month, or day) is not supported.

Parameters. The optional %params can be specified for more complex
querying/filtering. Each calendar module might support different
parameters, and should die if a parameter is unsupported. Currently
known common/standardized parameters:

* all

Boolean. If set to true, will include all entries that are normally
not included, e.g. low-priority entries (entries with tag
"low-priority").

* include_tags

Array. If set, then only entries which contain all tags mentioned in
this parameter should be included.

* exclude_tags

Array. If set, then entries which contain any of the tags mentioned
in this parameter should NOT be included.

* q

String. String/keyword matching. Only include entries that match
this keyword/string.

Result. Result is arrayref of entries, where each entry is a DefHash.
The following keys are recognized, an asterisk ("*") signifies required
key (see DefHash for more details on each key):

* date*

String. Either ISO8601 date in the form of "YYYY-MM-DD" or
"YYYY-MM-DD"T"HH:MM", or date interval in the form of
"YYYY-MM-DD"T"HH:MM/HH:MM".

Examples:

2019-02-13
2019-02-13T07:00
2019-02-13T07:00/09:00

Interval that spans day is currently not allowed. You might want to
create separate entries for each day in the span.

Timezones are not currently allowed. Dates are assumed in the local
time zone.

* year*

Integer. Year number (e.g. 2019).

* month*

Integer. Month number (1-12).

* day*

Integer. Day of month number (1-31).

* summary

From DefHash specification. Can be in English or another language,
but providing English version is recommended. To specify summary in
other language, use "summary.alt.lang.<LL>" keys.

* description

From DefHash specification. Can be in English or another language,
but providing English version is recommended. To specify description
in other language, use "description.alt.lang.<LL>" keys.

* tags

From DefHash specification. Some recommended/known tags: tentative,
holiday, religious, low-priority (entry with this tag by default
should not be returned by "get_entries" unless it specifies a true
"all" option), anniversary (entry with this tag will repeat yearly
and will be included in every (later) year).

* url

URL.

* image_url

URL.

* is_holiday

Boolean. You can also use tag "holiday" to mark an entry as a
holiday.

Optional parameters. A hashref (parameters) can be specified as an
optional first argument. It can be used to specify in more details what
kind of entries are requested. For example, a
Calendar::Dates::AU::Holiday module (Australian holiday calendar)
contains different holidays for different provinces. User can specify:

# return 2019 holiday dates for Victoria
$entries = Calendar::Dates::AU::Holiday->get_entries({province=>'VIC'}, 2019);

HOMEPAGE
Please visit the project's homepage at
<https://metacpan.org/release/Calendar-Dates>.

SOURCE
Source repository is at
<https://github.com/perlancar/perl-Calendar-Dates>.

BUGS
Please report any bugs or feature requests on the bugtracker website
<https://rt.cpan.org/Public/Dist/Display.html?Name=Calendar-Dates>

When submitting a bug or request, please include a test-file or a patch
to an existing test-file that illustrates the bug or desired feature.