https://github.com/tbrowder/date-names

Provides names (full and abbreviated) for month and day numbers (multilingual) via Raku programming arrays
https://github.com/tbrowder/date-names

perl6

Last synced: 4 months ago
JSON representation

Provides names (full and abbreviated) for month and day numbers (multilingual) via Raku programming arrays

• Host: GitHub
• URL: https://github.com/tbrowder/date-names
• Owner: tbrowder
• License: artistic-2.0
• Created: 2019-02-09T20:17:57.000Z (almost 6 years ago)
• Default Branch: master
• Last Pushed: 2024-02-17T11:55:28.000Z (11 months ago)
• Last Synced: 2024-10-10T20:42:12.803Z (4 months ago)
• Topics: perl6
• Language: Raku
• Homepage:
• Size: 233 KB
• Stars: 5
• Watchers: 3
• Forks: 8
• Open Issues: 6
• Metadata Files:
  • Readme: README.md
  • Changelog: Changes
  • Contributing: CONTRIBUTING.md
  • License: LICENSE.md

Awesome Lists containing this project

README

        
[![Actions Status](https://github.com/tbrowder/Date-Names/workflows/linux/badge.svg)](https://github.com/tbrowder/Date-Names/actions) [![Actions Status](https://github.com/tbrowder/Date-Names/workflows/macos/badge.svg)](https://github.com/tbrowder/Date-Names/actions) [![Actions Status](https://github.com/tbrowder/Date-Names/workflows/win64/badge.svg)](https://github.com/tbrowder/Date-Names/actions)

Date::Names

===========

Module **Date::Names** - Provides month and weekday names for numbers (multilingual)

SYNOPSIS

========

    use Date::Names;

    # choose the German language (English is the default)

    my $d = Date::Names.new: :lang;

    # 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, :mset, :dset;

    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␤»

DESCRIPTION

===========

Module **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 **Raku**'s date functions.

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

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

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 Рік 

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.

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 **tclc**, **uc**, or **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).

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 **Date::Names** class constructor.

### Table 2. Name array availability by language

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 

Table 3 defines the note codes used in Table 2.

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

### Table 3. Name array cell codes and meaning

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 

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.

### Table 4. Name array for truncated dow2 and dow3 languages

Language ISO dow3 dow2

 French fr YL    Indonesian id Y    Italian it     Norwegian (Bokmål) nb YL    Norwegian (Nynorsk) nn YL  

Note that when the **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).

### Methods to see what is available

(See [All-SETS](ALL-SETS.md) for the complete list for all languages.)

    use Date::Names

    my $dn = Date::Names.new: :lang;

    # 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)

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.

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]

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 **New features** and **Planned features** above) and will be able to control casing, absence or presence of periods on abbreviations, and truncation or padding as desired.

VERSION 3

=========

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

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

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

  * The **Date::Names** class API will be fixed and all currently planned features will be fully implemented and tested.

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 [CONTRIBUTING](CONTRIBUTING.md) file for details.

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.

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!

REFERENCES

==========

1. [FR] [http://bdl.oqlf.gouv.qc.ca/bdl/gabarit_bdl.asp?id=3617](http://bdl.oqlf.gouv.qc.ca/bdl/gabarit_bdl.asp?id=3617)

2. [ES] [http://www.wikilengua.org/index.php/Abreviaciones_en_fechas](http://www.wikilengua.org/index.php/Abreviaciones_en_fechas)

3. [ES] [http://lema.rae.es/dpd/srv/search?id=fKODyKTfZD6s0mX7bz](http://lema.rae.es/dpd/srv/search?id=fKODyKTfZD6s0mX7bz)

AUTHOR

======

Tom Browder, 

COPYRIGHT and LICENSE

=====================

Copyright © 2019-2024 Tom Browder

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