The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

Date::Baha::i - Convert to and from Baha'i dates

VERSION

version 0.2100

SYNOPSIS

  # perl -MDate::Baha::i -le'%d = to_bahai(); print as_string(\%d)'

  use Date::Baha'i;

  my($year, $month, $day) = (2018, 10, 2);

  my $bahai_date = to_bahai();
  $bahai_date = to_bahai(epoch => time);
  $bahai_date = to_bahai(
      year  => $year,
      month => $month,
      day   => $day,
  );

  my %bahai_date = to_bahai();
  %bahai_date = to_bahai(epoch => time);
  %bahai_date = to_bahai(
      year  => $year,
      month => $month,
      day   => $day,
  );

  my($bahai_year, $bahai_month, $bahai_day) = (175, 11, 6);

  my $date = from_bahai(
      year  => $bahai_year,
      month => $bahai_month,
      day   => $bahai_day,
  );

  ($year, $month, $day) = from_bahai(
      year  => $bahai_year,
      month => $bahai_month,
      day   => $bahai_day,
  );

  $day = next_holy_day();
  $day = next_holy_day($year, $month, $day);

  my @cycles = cycles();
  my @years = years();
  my @months = months();
  my @days = days();
  @days = days_of_the_week();
  my %days = holy_days();

DESCRIPTION

This package renders the Baha'i date from two standard date formats - epoch time and a (year, month, day) triple. It also converts a Baha'i date to standard ymd format.

CYCLES

Each cycle of nineteen years is called a Vahid. Nineteen cycles constitute a period called Kull-i-Shay.

The names of the years in each cycle are:

  1.  Alif   - The Letter "A"
  2.  Ba     - The letter "B"
  3.  Ab     - Father
  4.  Dal    - The letter "D"
  5.  Bab    - Gate
  6.  Vav    - The letter "V"
  7.  Abad   - Eternity
  8.  Jad    - Generosity
  9.  Baha   - Splendour
  10. Hubb   - Love
  11. Bahhaj - Delightful
  12. Javab  - Answer
  13. Ahad   - Single
  14. Vahhab - Bountiful
  15. Vidad  - Affection
  16. Badi   - Beginning
  17. Bahi   - Luminous
  18. Abha   - Most Luminous
  19. Vahid  - Unity

MONTH NAMES

The names of the months in the Baha'i (Badi) calendar were given by the Bab, who drew them from the nineteen names of God invoked in a prayer said during the month of fasting in Shi'ih Islam. They are:

  1.  Baha       - Splendour (21 March - 8 April)
  2.  Jalal      - Glory (9 April - 27 April)
  3.  Jamal      - Beauty (28 April - 16 May)
  4.  'Azamat    - Grandeur (17 May - 4 June)
  5.  Nur        - Light (5 June - 23 June)
  6.  Rahmat     - Mercy (24 June - 12 July)
  7.  Kalimat    - Words (13 July - 31 July)
  8.  Kamal      - Perfection (1 August - 19 August)
  9.  Asma'      - Names (20 August - 7 September)
  10. 'Izzat     - Might (8 September - 26 September)
  11. Mashiyyat  - Will (27 September - 15 October)
  12. 'Ilm       - Knowledge (16 October - 3 November)
  13. Qudrat     - Power (4 November - 22 November)
  14. Qawl       - Speech (23 November - 11 December)
  15. Masa'il    - Questions (12 December - 30 December)
  16. Sharaf     - Honour (31 December - 18 January)
  17. Sultan     - Sovereignty (19 January - 6 February)
  18. Mulk       - Dominion (7 February - 25 February)
  * Ayyam-i-Ha   - Days of Ha (26 February - 1 March))
  19. 'Ala       - Loftiness (2 March - 20 March)

AYYAM-I-HA

Intercalary Days: Four (or five) days in a leap year, before the last month.

DAY NAMES

The days of the Baha'i week are:

  1. Jalal    - Glory (Saturday)
  2. Jamal    - Beauty (Sunday)
  3. Kaml     - Perfection (Monday)
  4. Fidal    - Grace (Tuesday)
  5. 'Idal    - Justice (Wednesday)
  6. Istijlal - Majesty (Thursday)
  7. Istiqlal - Independence (Friday)

The Baha'i day of rest is Isiqlal (Friday) and the Baha'i day begins and ends at sunset.

HOLY DAYS

There are 11 Holy Days:

* Naw Ruz - The Spring Equinox

Generally March 21.

If the equinox falls after sunset on 21 March, Naw Ruz is observed on 22 March, since the Baha'i day begins at sunset.

* Ridvan - Declaration of Baha'u'llah in 1863

   1st day - 21 April
   9th day - 29 April
  12th day -  2 May

* Declaration of the Bab - 23 May, 1844

* Ascension of Baha'u'llah - 29 May, 1892

* Martyrdom of the Bab - 9 July, 1850

* Birth of the Bab - 20 October, 1819

* Birth of Baha'u'llah - 12 November, 1817

* Ascension of 'Abdu'l-Baha - 28 November, 1921

* Ayyam-i-Ha (the Intercalary Days) 26 February to 1 March

* The Fast - 2-20 March in the month 'Ala - 19 days from sunrise to sunset

FUNCTIONS

to_bahai()

  # Return a string in scalar context.
  $bahai_date = to_bahai();
  $bahai_date = to_bahai(
      epoch => time,
      use_gmtime => $use_gmtime,
      %args,
  );
  $bahai_date = to_bahai(
      year  => $year,
      month => $month,
      day   => $day,
      %args,
  );

  # Return a hash in array context.
  %bahai_date = to_bahai();
  %bahai_date = to_bahai(
      epoch => time,
      use_gmtime => $use_gmtime,
      %args,
  );
  %bahai_date = to_bahai(
      year  => $year,
      month => $month,
      day   => $day,
      %args,
  );

This function returns either a string or a hash of the date names and numbers from either epoch seconds, or a year, month, day named parameter triple.

If using epoch seconds, this function can be forced to use gmtime instead of localtime. If neither a epoch or a ymd triple are given, the system localtime is used as the default.

The extra, optional arguments are used by the as_string function, detailed below.

In a scalar context, this function returns a string sentence with the numeric or named date. In an array context, it returns a hash with the following keys:

  kull_i_shay,
  cycle, cycle_name, cycle_year,
  year, year_name,
  month, month_name,
  day, day_name,
  dow, dow_name and
  holy_day (if there is one)

from_bahai()

  # Return a y/m/d string in scalar context.
  $date = from_bahai(
      year  => $bahai_year,
      month => $bahai_month,
      day   => $bahai_day,
  );

  # Return a ymd triple in array context.
  ($year, $month, $day) = from_bahai(
      year  => $bahai_year,
      month => $bahai_month,
      day   => $bahai_day,
  );

This function returns either a string or a list of the given date.

Currently, this supports the Baha'i year, month and day, but not the kull-i-shay, cycle, cycle name or cycle year.

as_string()

  $date = as_string(
      \%bahai_date,
      size     => $size,
      alpha    => $alpha,
      numeric  => $numeric,
  );

Return the Baha'i date as a friendly string.

This function takes a Baha'i date hash and Boolean arguments that determine the format of the output.

The "size" argument toggles between short and long representations. As the names imply, the "alpha" and "numeric" flags turn the alphanumeric representations on or off. The defaults are as follows:

  alpha   => 1
  numeric => 0
  size    => 1

(Which mean that "long non-numeric alpha" is the default representation.)

Here are some handy examples (newlines added for readability):

  short numeric:
  159/11/6  # year/month/day

  long numeric:
  7th day of the week, 1st day of the 1st month, year 159,
  7th year of the 9th vahid of the 1st kull-i-shay, holy day: Naw Ruz

  short alpha
  Istiqlal, Baha of Baha, Abad of Baha

  long alpha:
  week day Istiqlal, day Baha of month Baha,
  year one hundred fifty nine of year Abad of the vahid Baha of the
  1st kull-i-shay, holy day: Naw Ruz

  short alpha-numeric:
  Istiqlal (7), Baha (1) of Baha (1), year 159, Abad (7) of Baha (9)

  long alpha-numeric:
  7th week day Istiqlal, 1st day Baha of the 1st month Baha,
  year one hundred and fifty nine (159), 7th year Abad of the
  9th vahid Baha of the 1st kull-i-shay, holy day: Naw Ruz

next_holy_day()

  $d = next_holy_day();
  $d = next_holy_day($year, $month, $day);

Return the name of the first holy day after the provided date.

cycles()

  @c = cycles();

Return the 19 cycle names as an array.

years()

  @y = years();

Return the 19 year names as an array.

months()

  @m = months();

Return the 19 month names as an array, along with the intercalary days as the last element.

days()

  @d = days();

Return the 19 day names as an array.

days_of_the_week()

  @d = days_of_the_week();

Return the seven day-of-the-week names as an array.

holy_days()

  %d = holy_days();

Return a hash with keys of the Holy Day names and values of the date or range.

These values are array references of either two or three elements: month, day and the (optional) number of days observed.

Dates are given in common, standard (non-Baha'i) format.

SEE ALSO

Date::Calc

Exporter

Lingua::EN::Numbers

Lingua::EN::Numbers::Years

http://calendar.bahaiq.com/

TO DO

Base the date computation on the time of day (Baha'i day begins at sunset).

Make this a DateTime module.

Support cycles and Kull-i-Shay.

Overload localtime and gmtime, just to be cool?

AUTHOR

Gene Boggs <gene@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2015 by Gene Boggs.

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