The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Calendar-Dates-0.2.3
River stage one • 2 direct dependents • 8 total dependents
++
/ Calendar::Dates

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.

SEE ALSO

Related namespaces:

  • Calendar::DatesUtils

    This is namespace for modules that make use of Calendar::Dates::* modules, e.g. Calendar::DatesUtils::To::ICal.

  • Calendar::DatesRoles

    For roles related to Calendar::Dates.

Related modules and applications:

Related projects:

  • Date::Holidays

    A long established project. Shares a similar goal with Calendar::Dates (to provide a common interface for all Date::Holidays::* modules) but focuses on holidays only.

AUTHOR

perlancar <perlancar@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2019 by perlancar@cpan.org.

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