=begin pod

=head1 Date::Names

Module B<Date::Names> - Provides month and weekday names for numbers (multilingual)

=head1 SYNOPSIS

=begin code
use Date::Names;
# choose the German language (English is the default)
my $d = Date::Names.new: :lang<de>;

# Default is to show full names
say $d.dow(3); # OUTPUT: «Mittwoch␤»
say $d.mon(3); # OUTPUT: «März␤»

# What abbreviations are available?
$d.sets; # OUTPUT: «name sets with values:␤  dow  dow2  mon  mon3␤»

# Choose the desired sets
$d = Date::Names.new: :lang<de>, :mset<mon3>, :dset<dow2>;
say $d.dow(4); # OUTPUT: «Do␤»
say $d.mon(4); # OUTPUT: «Apr␤»

# Arbitrarily truncate a word
say $d.mon(8,2); # OUTPUT: «Au␤»

# Given a name, return the number of month of year or day of week
say $d.mon2num('März');     # OUTPUT: «3␤»
say $d.dow2num('Mittwoch'); # OUTPUT: «3␤»

# How to say "The Year 2030"
say "{$d.the-year} 2030"; # OUTPUT: «Das Jahr 2030␤»
=end code

=head1 DESCRIPTION

Module B<Date::Names> provides the full name of months and days of the
week for the numbers 1..12 and 1..7, respectively, primarily for use
with B<Raku>'s date functions.

Full names of the months and weekdays are currently available in the
following thirteen languages:

=head3 Table 1. Language ISO codes (lower-case) and '.the-year' values

=begin table
Language            | ISO code | .the-year
--------------------+----------+----------
Dutch               | nl       | Het jaar
English             | en       | The Year
French              | fr       | L'année
German              | de       | Das Jahr
Indonesian          | id       | Tahun
Italian             | it       | L'anno
Norwegian (Bokmål)  | nb       | Год» да бокмал
Norwegian (Nynorsk) | nn       | Год» на нюнорск
Polish              | pl       | Rok
Romanian            | ro       | Anul
Russian             | ru       | Год
Spanish             | es       | El año
Ukranian            | uk       | Рік
=end table

The '.the-year' attribute was added for use with the Calendar module to
use on a cover page. The attribute values were obtained using Google's
translation capability, and they may not
be correct. Please file an issue if you are a native
language speaker and see an error.

=head1 CAPITALIZATION and PUNCTUATION

All English month and weekday names are always capitalized.  Other
languages vary in capitalization depending on where the word or
abbreviation is used or other factors. The names and abbreviations
herein are in the most common form, but the user can always explicitly
set the case by applying the Raku routines B<tclc>, B<uc>, or B<lc> to
the name or abbreviation.

Some of the abbreviations include an ending period since that is
customary use in some languages (e.g., Spanish and Ukranian).

=head1 LIMITATIONS

Not all languages have a complete set of two- and three-letter
abbreviations, and some require up to four letters for the official
abbreviations.

Table 2 shows the array names for the full names and abbreviations
currently available. Array names with a 2 or 3 appended are complete
abbreviation sets of that length only.  Array names with an 'a'
appended are sets of abbreviations of mixed length.  A 'Y' in a cell
indicates a language has a complete set of that type of abbreviation.

Note that in some countries the term "abbreviation" is distinctly
different than "code" as it applies to date names. An asterisk in a
cell marks those which are technically codes rather than
abbreviations.  Table 3 shows the meaning of other codes used in the
Table 2 cells.

The array names in Table 2 (without a sigil) are the ones to be used
for the day and month array names for the B<Date::Names> class
constructor.

=head3 Table 2. Name array availability by language
=begin table
Language - ISO   / Array | mon  | dow  | mon3 | dow3 | mon2 | dow2 | mona | dowa
-------------------------+------+------+------+------+------+------+------+-----
Dutch               - nl |  YL  |  YL  |  YL  |  YL  |      |  YL  |      |
English             - en |  Y   |  Y   |  Y   |  Y   |      |  Y   |      |
French              - fr |  YL  |  YL  |      |  YL  |  YU* |      |  YL  |  Y
German              - de |  Y   |  Y   |  Y   |  Y   |      |  Y   |      |
Indonesian          - id |  Y   |  Y   |  Y   |  Y   |      |      |      |
Italian             - it |  Y   |  YL  |      |      |      |      |      |
Norwegian (Bokmål)  - nb |  YL  |  YL  |  YL  |  YL  |      |      |      |  YL
Norwegian (Nynorsk) - nn |  YL  |  YL  |  YL  |  YL  |      |      |      |  YL
Polish              - pl |  YL  |  YL  |  YL  |      |      |  YL  |      |
Romanian            - ro |  YL  |  YL  |  YL  |      |      |  YL  |  YL  |
Russian             - ru |  YL  |  YL  |  YL  |      |      |  YL  |      |
Spanish             - es |  YL  |  YL  |  YL* |  YL* |  YL  |  YL  |  LP  |  LP
Ukranian            - uk |  YL  |  YL  |  YL  |      |  YL  |  YL  |  LP  |  LP
=end table

Table 3 defines the note codes used in Table 2.

Note all arrays are title-cased unless marked with a 'U' or an 'L'.

=head3 Table 3. Name array cell codes and meaning

=begin table
Code | Meaning
-----+---------------------------------
*    | a code rather than an abbreviation
L    | array values are lower-case
P    | array values have a trailing period
U    | array values are upper-case
Y    | language has this array
=end table

Some of the most-used names in calendar construction are the abbreviations
for the days-of-the-week (dow), both two- and three-letter ones. One
common example of using a two-letter dow abbreviation  use is in the
Linux system utility 'cal'. And very common, at least in the US,
are the three-letter dow abbreviations on many printed calendars, especially
ones printed by users on home printers. The five languages
in Table 4 don't have a complete set of dow2 and dow3 abbreviations, so this
module will automatically create one by truncating the full dow or
month name to the desired length.

There are more languages that don't have a full set of two-
and three-letter month abbreviations, as can be seen in Table 2. If
they are required by the user, they will also be created automatically
by truncation.

=head3 Table 4.  Name array for truncated dow2 and dow3 languages

=begin table
Language            | ISO | dow3  | dow2
--------------------+-----+-------+-------
French              | fr  |   YL  |
Indonesian          | id  |   Y   |
Italian             | it  |       |
Norwegian (Bokmål)  | nb  |   YL  |
Norwegian (Nynorsk) | nn  |   YL  |
=end table

Note that when the B<Date::Names> class is fully implemented in
Version 3, the user will be able to specify desired array table
attributes for his or her tastes (case, trailing period, truncation or
padding).

=head3 Methods to see what is available

(See L<All-SETS|ALL-SETS.md> for the complete list for all languages.)

=begin code
use Date::Names
my $dn = Date::Names.new: :lang<nl>;
# how many non-empty data sets?
say $dn.nsets; # OUTPUT: «5␤»
# show the sets:
$dn.sets; # OUTPUT: «name sets with values:␤  dow  dow2  dow3  mon  mon3␤»
# show all sets in all available languages
$dn.show-all; # OUTPUT: see ALL-SETS.md)
=end code

=head1 Features:

1. English language default

2. Default month and weekday array choices

3. User chooses which month and weekday array to use

4. Methods for entering a valid abbreviation of weekday or month name and returning its number

5. When requesting an abbreviation that doesn't exist, the full name
is automatically truncated to the desired length.
=head1 Planned features:

1. User chooses case of the output names [API complete, needs tests]

2. User can choose to have a period or not for abbreviations [API complete, needs tests]

=head1 Possible future features

1. Language-specific attributes to affect class behavior (e.g., allow raw truncation or not)

2. Add additional array names and types on a language basis
   automatically via a separate Common Locale Data Repository (CLDR) date
   module

3. Features desired by users

The basic class is working (see B<New features> and B<Planned features> above) and
will be able to control casing, absence or presence of periods on
abbreviations, and truncation or padding as desired.

=head1 VERSION 3

=item A CLDR module which can produce compatible language data for this module will be available.

=item Additionally, the CLDR date data set names will be mapped to the
  current names where possible, and some short set names added if
  necessary.

=item All CLDR data set names will also be available as aliases or native arrays.

=item The B<Date::Names> class API will be fixed and all currently planned
  features will be fully implemented and tested.

=head1 PULL REQUESTS

Native language speakers please submit PRs to (1) complete the
existing language abbreviations, (2), correct errors, and (3) provide
more languages. See the L<CONTRIBUTING|CONTRIBUTING.md>
file for details.

=head1 CORRECTIONS and SUGGESTIONS

The goal of this module is to be useful to non-English users as well
as English users. The author welcomes suggestions for improvement and
increased utility.

=head1 ACKNOWLEDGEMENTS

The following persons contributed to this project via PRs and
comments (@name is an alias on IRC #raku):

+ Moritz Lenz (@moritz, Github: moritz) - German and Norwegian Bokmﾃ･l data

+ @sena_kun (Github: Altai-man) - Russian data

+ Luc St-Louis (@lucs, Github: lucs) - French data

+ Luis F. Uceta (Github: uzluisf) - Spanish data

+ Elizabeth Mattijsen (@lizmat, Github: lizmat) - Dutch data

+ Github: heince - Indonesian data

+ Github: tzjan - Polish data

+ Eskild Hustvedt (@Zero_Dogg, Github: zerodogg) - Norwegian Nynorsk data

+ Github: altblue - Romanian data

+ Andrij Mizyk (Github: andmizyk) - Ukranian data

I am grateful for their help!

=head1 REFERENCES

1. [FR] L<http://bdl.oqlf.gouv.qc.ca/bdl/gabarit_bdl.asp?id=3617>

2. [ES] L<http://www.wikilengua.org/index.php/Abreviaciones_en_fechas>

3. [ES] L<http://lema.rae.es/dpd/srv/search?id=fKODyKTfZD6s0mX7bz>

=head1 AUTHOR

Tom Browder, <[email protected]>

=head1 COPYRIGHT and LICENSE

Copyright E<0x00a9> 2019-2024 Tom Browder

This program is free software; you may redistribute or modify
it under the same terms as Raku itself.

=end pod