=begin pod

=head1 NAME

Locale::Dates - encapsulate locale information about dates

=head1 SYNOPSIS

=begin code :lang<raku>
use Locale::Dates;

my $ld = Locale::Dates("EN");  # or BG DE FR NL PT RU

say $ld.weekdays[1];              # Monday
say $ld.abbreviated-weekdays[2];  # Tue
say $ld.months[3];                # March
say $ld.abbreviated-months[4];    # Apr

say $ld.code;  # EN
say $ld.am;    # am
say $ld.pm;    # pm

say $ld.date-time-representation;  # %a %b %e %T %Z %Y
say $ld.date-representation        # %a %b %e %Y
say $ld.time-representation        # %T

say Locale::Dates.known-locales;  # (BG DE FR NL PT RU)
=end code

=head1 DESCRIPTION

The C<Locale-Dates> distribution provides a database of locale
information pertaining to dates.  And it provides a class to encapsulate
bespoke information.

=head1 CLASS METHODS

=head2 known-locales

=begin code :lang<raku>
say Locale::Dates.known-locales;  # (BG DE FR NL PT RU)
=end code

Returns a C<List> of known locales, identified by their 2-letter
ISO code.

=head1 INSTANCE METHODS

=head2 weekdays

=begin code :lang<raku>
say $ld.weekdays[0];  # Sunday
say $ld.weekdays[1];  # Monday
say $ld.weekdays[7];  # Sunday
=end code

The C<weekdays> method returns a C<List> with full weekday names,
handling both 0-based as well as 1-based weekday values.

=head2 abbreviated-weekdays

=begin code :lang<raku>
say $ld.abbreviated-weekdays[0];  # Sun
say $ld.abbreviated-weekdays[1];  # Mon
say $ld.abbreviated-weekdays[7];  # Sun
=end code

The C<abbreviated-weekdays> method returns a C<List> with abbreviated
weekday names, handling both 0-based as well as 1-based weekday values.

=head2 months

=begin code :lang<raku>
say $ld.months[ 1];  # January
say $ld.months[12];  # December
=end code

The C<months> method returns a C<List> with full month names.
Handles 1-based month values only.

=head2 abbreviated-months

=begin code :lang<raku>
say $ld.abbreviated-months[ 1];  # Jan
say $ld.abbreviated-months[12];  # Dec
=end code

The C<abbreviated-months> method returns a C<List> with abbreviated
month names.  Handles 1-based month values only.

=head2 code

=begin code :lang<raku>
say $ld.code;  # EN
=end code

The C<code> method returns the identifying code of this locale.

=head2 am / AM

=begin code :lang<raku>
say $ld.am;  # am
say $ld.AM;  # AM
=end code

The C<am> method returns the representation of "ante meridiem",
in lowercase, the C<AM> method in uppercase.

=head2 pm / PM

=begin code :lang<raku>
say $ld.pm;  # pm
say $ld.PM;  # PM
=end code

The C<pm> method returns the representation of "post meridiem"
in lowercase, the C<PM> method in uppercase.

=head2 date-time-representation

=begin code :lang<raku>
say $ld.date-time-representation;  # %a %b %e %T %Z %Y
=end code

The C<date-time-representation> method returns the C<strftime> format
for the representation of date and time.

=head2 date-representation

=begin code :lang<raku>
say $ld.date-representation;  # %a %b %e %Y
=end code

The C<date-representation> method returns the C<strftime> format for
the representation of a date.

=head2 time-representation

=begin code :lang<raku>
say $ld.time-representation;  # %T
=end code

The C<time-representation> method returns the C<strftime> format for
the representation of a time.

=head1 CREATING YOUR OWN DATE LOCALE

=begin code :lang<raku>
my $ld = Locale::Dates.new(
  code => "foo",
  weekdays => <AAAA BBBB CCCC DDDD EEEE FFFF GGGG>,
  months   => <MMMM NNNN OOOO PPPP QQQQ RRRR
               SSSS TTTT UUUU VVVV WWWW XXXX>,
  am => "meh",
  pm => "duh",
);
=end code

The C<Locale::Dates> class can be instantiated like any other Raku
class using named arguments.

=head2 code

Required. The identifier code of this locale.

=head2 weekdays

Required.  A C<List> with weekday names for this locale, starting
at Monday.

=head2 months

Required.  A C<List> with month names for this locale, starting
at January.

=head2 date-time-representation

Optional.  The C<strftime> format representation for date and time
for this locale.  Defaults to C<"%a %e %b %T %Z %Y">.

=head2 date-representation

Optional.  The C<strftime> format representation for a date in this
locale.  Defaults to C<"%a %e %b %Y">.

=head2 time-representation

Optional.  The C<strftime> format representation for a time in this
locale.  Defaults to C<"%T">.

=head2 am

Optional.  The representation of "ante meridiem" for this locale.
Defaults to "am".

=head2 pm

Optional.  The representation of "post meridiem" for this locale.
Defaults to "pm".

=head2 abbreviated-weekdays

Optional.  A C<List> with abbreviated weekday names for this locale,
starting at Monday.  Defaults to the first 3 letters of the weekdays.

=head2 abbreviated-months

Optional.  A C<List> with abbreviated month names for this locale,
starting at January.  Defaults to the first 3 letters of the month names.

=head1 AUTHOR

Elizabeth Mattijsen <liz@raku.rocks>

Source can be located at: https://codeberg.org/lizmat/Locale-Dates .
Comments and Pull Requests are welcome.

If you like this module, or what I'm doing more generally, committing to a
L<small sponsorship|https://github.com/sponsors/lizmat/>  would mean a great
deal to me!

=head1 COPYRIGHT AND LICENSE

Copyright 2025, 2026 Elizabeth Mattijsen

This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.

=end pod

# vim: expandtab shiftwidth=4
