Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Hebrew(3)	      User Contributed Perl Documentation	     Hebrew(3)

NAME
       DateTime::Calendar::Hebrew - Dates in the Hebrew	calendar

SYNOPSIS
	 use DateTime::Calendar::Hebrew;

	 $dt = DateTime::Calendar::Hebrew->new(	year  => 5782,
						month => 10,
						day   => 4 );

DESCRIPTION
       "DateTime::Calendar::Hebrew" is the implementation of the Hebrew
       calendar.  Read on for more details on the Hebrew calendar.

THE HEBREW (JEWISH) CALENDAR
       The Hebrew/Jewish calendar is a Luni-Solar calendar. Torah Law mandates
       that months are Lunar. The first	day of a month coincides with the new
       moon in Jerusalem. (In ancient times, this was determined by witnesses.
       Read the	books in the bibliography for more info). The Torah also
       mandates	that certain holidays must occur in certain seasons. Seasons
       are solar, so a calendar	that can work with lunar & solar events	is
       needed.

       The Hebrew Calendar uses	a leap-month to	regulate itself	to the solar
       seasons.	There are 12 months in a regular year. Months can be 29	or 30
       days long. 2 of the months (Cheshvan & Kislev) change between having 29
       & 30 days, depending on the year. In a Jewish Leap Year,	an extra month
       number 13 is added.

       Now a quick note	about the numbering of the months. Most	people expect
       a new year to start with	month #1. However, the Hebrew calendar has
       more than one new year. The year	number changes in the (Northern
       Hemisphere) Autumn with Tishrei (month #7), but the months are numbered
       beginning with Nissan (month #1)	in the Spring.

       Tishrei is the month in which you find the High-Holy-Days - 'Rosh
       HaShana'	& 'Yom Kippur'.

       Nissan, the Spring-new-year, commemorates the Exodus of the Ancient
       Israelites from Egypt. The Torah	refers to months only by number,
       beginning with Nissan, e.g. giving the date of Yom Kippur in 'the
       seventh month'.

       This system works for well for us, because of the leap month. If	the
       new year	is in the spring, the leap month is month 13. Otherwise, we'd
       have to re-number the months after a leap-month.

       Every month has a set number, using this	module.	Here's a list:

       1. Nissan
       2. Iyar
       3. Sivan
       4. Tammuz
       5. Av or	Menachem-Av
       6. Elul
       7. Tishrei
       8. Cheshvan or Mar-Cheshvan
       9. Kislev
       10. Teves
       11. Shevat
       12. AdarI
       13. AdarII (only	in leap	years)

       ** A NOTE ABOUT SPELLING	** If you speak	Hebrew,	you may	take issue
       with my spelling	of Hebrew words. I'm sorry, I used the spelling
       closest to the way I pronounce it. You could call it "Brooklyn-
       Ashkenaz-Pronunciation",	if you like.

       Back to the calendar. A cycle of	Hebrew years takes 19 years and	is
       called a	Machzor. In that cycle,	years 3, 6, 8, 11, 14, 17 & 19 are
       leap years.

       Days (and holidays) begin at sunset, see	below for more info.

       The calculations	for the	start and length of the	year are based on a
       number of factors, including rules about	what holidays can't be on what
       days of the week, and things like that. For more	detailed information
       about the Hebrew	Calendar and Hebrew-Calendar-Algorithms, pick up one
       of the books listed above. I'm just not willing to plagiarize it	all
       here. Of	course a Google	search on "Jewish Calendar" will probably
       offer you a wealth of materials.

SOURCES
       Here are	some absolutely	essential books	in understanding the
       Hebrew(Jewish) Calendar.	Be forwarned - a working knowledge of Hebrew
       terms will help greatly:

       The Comprehensive Hebrew	Calendar by Arthur Spier. Third, Revised
       edition.	Feldheim Publishers. ISBN 0-87306-398-8

       This book is great. Besides for a complete Jewish Calendar from 1900 to
       2100, it	contains a 22 page discourse on	the Jewish Calendar - history,
       calculation method, religious observances - the works.

       Understanding the Jewish	Calendar by Rabbi Nathan Bushwick. Moznaim
       Publishing Corporation. ISBN 0-94011-817-3

       Another excellent book. Explains	the calendar, lunation cycles, torah
       portions	and more. This has more	Astronomy than any of the others.

       Calendrical Calculations	by Edward Reingold & Nachum Dershowitz.
       Cambridge University Press. ISBN	0-521-77167-6 or 0-521-77752-6

       This book focuses on the	math of	calendar conversions. I	use the	first
       edition,	which is full of examples in LISP. The second edition is
       supposed	to include examples in other languages.	It covers many
       different calendars - not just Hebrew.  See their page @
       <http://emr.cs.iit.edu/home/reingold/calendar-book/second-edition/>

       There are other books, but those	are the	ones I used most extensively
       in my Perl coding.

METHODS
       o   new(...)

		   $dt = new Date::Calendar::Hebrew(
			   year	=> 5782,
			   month => 10,
			   day => 5,
		   );

	   This	class method accepts parameters	for each date and time
	   component: "year", "month", "day", "hour", "minute",	"second" and
	   "nanosecond".  "year" is required, all the rest are optional. time
	   fields default to '0', month/day fields to '1'. All fields except
	   year	are tested for validity:

		   month : 1 to	13
		   day	 : 1 to	30
		   hour	 : 0 to	23
		   minute/second : 0 to	59
		   nanosecond :	0 to 999,999,999

	   "Date::Calendar::Hebrew" doesn't support timezones. It uses the
	   floating timezone.

	   The days on the Hebrew calendar begin at sunset. If you want	to
	   know	the Hebrew date, accurate with regard to local sunset, see the
	   SUNSET section below.

       o   from_object(object => $object)

	   This	class method can be used to construct a	new object from	any
	   object that implements the "utc_rd_values()"	method.	 All
	   "DateTime::Calendar"	modules	must implement this method in order to
	   provide cross-calendar compatibility.

       o   set(...)

		   $dt->set(
			   year	 => 5782,
			   month => 1,
			   day	 => 1,
		   );

	   This	method allows you to modify the	values of the object. valid
	   fields are "year", "month", "day", "hour", "minute",	"second", and
	   "nanosecond"	. Returns the object being modified.  Values are
	   checked for validity	just as	they are in "new()".

       o   utc_rd_values

	   Returns the current UTC Rata	Die days and seconds as	a three
	   element list.  This exists primarily	to allow other calendar
	   modules to create objects based on the values provided by this
	   object. We don't support timezones, so this is actually the local
	   RD.

       o   utc_rd_as_seconds

	   Returns the current UTC Rata	Die days and seconds purely as
	   seconds.  This is useful when you need a single number to represent
	   a date. We don't support timezones, so this is actually the local
	   RD as seconds.

       o   clone

	   Returns a working copy of the object.

       o   now

	   This	class method returns a "Date::Calendar::Hebrew"	object created
	   from	"DateTime-"now()>.

       o   today

	   This	class method returns a "Date::Calendar::Hebrew"	object created
	   from	"DateTime-"today()>.

       o   year

	   Returns the year.

       o   month

	   Returns the month of	the year, from 1..13.

       o   day_of_month, day, mday

	   Returns the day of the month, from 1..30.

       o   day_of_month_0, day_0, mday_0

	   Returns the day of the month, from 0..29.

       o   hour

       o   minute

       o   second

	   Each	method returns the parameter named in the method.

       o   month_name($month);

	   Returns the name of the given month.	 Called	on an object
	   ($dt->month_name), it returns the month name	for the	current	month.

	   The Hebrew months are Nissan, Iyar, Sivan, Tammuz, (Menachem)Av,
	   Elul, Tishrei, (Mar)Cheshvan, Kislev, Teves,	Shevat & Adar. Leap
	   years have "Adar II"	or Second-Adar.	If you feel that the order of
	   the months is wrong,	see the	README.

       o   day_of_week,	wday, dow

	   Returns the day of the week as a number, from 1..7, with 1 being
	   Sunday and 7	being Saturday.

       o   day_of_week_0, wday_0, dow_0

	   Returns the day of the week as a number, from 0..6, with 0 being
	   Sunday and 6	being Saturday.

       o   day_name

	   Returns the name of the current day of the week.

       o   day_of_year,	doy

	   Returns the day of the year.

       o   day_of_year_0, doy_0

	   Returns the day of the year,	starting with 0.

       o   ymd($optional_separator);

       o   mdy($optional_separator);

       o   dmy($optional_separator);

	   Each	method returns the year, month,	and day, in the	order
	   indicated by	the method name.  Years	are zero-padded	to four
	   digits.  Months and days are	0-padded to two	digits.

	   By default, the values are separated	by a dash (-), but this	can be
	   overridden by passing a value to the	method.

       o   hms($optional_separator);

	   Returns the time, in	the format of HH:MM:SS.

	   By default, the values are separated	by a colon (:),	but this can
	   be overridden by passing a value to the method.

       o   hm($optional_separator);

	   Returns the time, in	the format of HH:MM.

	   By default, the values are separated	by a colon (:),	but this can
	   be overridden by passing a value to the method.

       o   timezone

	   Returns 'floating'

       o   datetime

	   Returns the date & time in the format of YYYY/MM/DDTHH:MM:SS

       o   strftime($format, ...)

	   This	method implements functionality	similar	to the "strftime()"
	   method in C.	 However, if given multiple format strings, then it
	   will	return multiple	elements, one for each format string.

	   See DateTime	for a list of all possible format specifiers.  I
	   implemented as many of them as I could.

   INTERNAL FUNCTIONS
       o   _from_rd($RD);

	   Calculates the Hebrew year, month and day from the RD.

       o   _to_rd($year, $month, $day);

	   Calulates the RD from the  Hebrew year, month and day.

       o   _leap_year($year);

	   Returns true	if the given year is a Hebrew leap-year.

       o   _LastMonthOfYear($year);

	   Returns the number of the last month	in the given Hebrew year.
	   Leap-years have 13 months, Regular-years have 12.

       o   _CalendarElapsedDays($year);

	   Returns the number of days that have	passed from the	Epoch of the
	   Hebrew Calendar to the first	day ofthe given	year.

       o   _DaysInYear($year);

	   Returns the number of days in the given year.

       o   _LongCheshvan($year);

	   Returns true	if the given year has an extended month	of Cheshvan.
	   Cheshvan can	have 29	or 30 days. Normally it	has 29.

       o   _ShortKislev($year);

	   Returns true	if the given year has a	shortened month	of Kislev.
	   Kislev can have 29 or 30 days. Normally it has 30.

       o   _LastDayOfMonth($year, $month);

	   Returns the length of the month in question,	for the	year in
	   question.

   OPERATOR OVERLOADING	AND OBJECT MATH
       "DateTime::Calendar::Hebrew" objects can	be compares with the '>', '<',
       '<=>' and 'cmp' operators. You can also call $DT->compare($OTHER_DT).

       Simple math can be done on "DateTime::Calendar::Hebrew" objects,	using
       a "DateTime::Duration". The only	supported fields are: days, hours,
       minutes,	seconds	_ nanoseconds. You can also call
       $DT->add_duration($DURATION) and	$DT->subtract_duration($DURATION).

       o   _compare_overload

       o   _compare

       o   _add_overload

       o   _subtract_overload

       o   add_duration

       o   subtract_duration

       o   _normalize

SUNSET AND THE HEBREW DATE
       Days in the Hebrew Calendar start at sunset. This is only relevant for
       religious purposes or pedantic programmers. There are some serious
       (religious) issues involved, in areas that don't	have a clearly
       defined,	daily sunset or	sunrise. In the	Arctic Circle, there are
       summer days where the sun doesn't set, and winter days where the	sun
       doesn't rise. Other areas (e.g. Anchorage, Alaska Stockholm, Sweden,
       Oslo, Norway) where the days are	very short and twilight	is
       exceptionally long. (I've never experienced this, I'm copying it	from a
       webpage.)

       First off, I'd like to say, that	if you are Jewish and have questions
       related to sunrise/sunset and religious observances - consult your
       local Rabbi. I'm	no expert.

       If you're not Jewish, and you want to know about	Hebrew dates in	these
       areas (or even if you are Jewish	but you	don't live there) - make
       friends with someone Jewish who lives there and ask them	to ask their
       Rabbi. :)

       Now that	my awkward disclaimer is finished, on to the code issues.

       If you wish the Hebrew date to be accurate with regard to sunset, you
       need to provide 2 things: A DateTime::Event::Sunrise object,
       initialized with	a longitude and	latitude for your location AND a time-
       zone for	your location. Without a timezone, I can't calculate sunset
       properly. These items can be passed in via the constructor, or the set
       method. You could configure the "DateTime::Event::Sunrise" object for
       altitude	& interpolation	if you wish.

   NOTES ABOUT SUNSET
       This feature was	only tested for	time-zones with	a sunset for the day
       in question.  THE RD_DAYS VALUE IS NOT MODIFIED.	The internal local-
       year/month/day fields are modified. The change in date only shows when
       using the accessor methods for the object. RD_DAYS only changes at
       midnight.  DateTime::Calendar::Hebrew doesn't support timezones!	It
       still uses a 'floating' time zone. Using	$obj->set_time_zone(...) isn't
       implemented, and	won't help with	sunset calculations. It	needs to be a
       field.

       As has been pointed out to me, there is a feature/bug that causes some
       confusion in the	conversions. I prioritized the calculations, so	that
       the conversion from DateTime to DateTime::Calendar::Hebrew would	always
       look right. If you provide an english date, with	a time after sunset
       but before midnight, you	will get a Hebrew time for the next day. The
       RD will stay the	same, but the Hebrew date changes. Conversly, if you
       want to say the night of	a certain Hebrew date, you need	to use the
       date of the previous day. The sunset 'belongs' to the English date e.g.
       If you say "Nissan 14 5764, after sunset" (The time to search for
       leavening on Passover eve), the code converts it	to the RD equivalent
       to "Monday, April 5th , 2004". After sunset of April 5th, is "Nissan
       15th"! So if you	wanted an object to represent the time to search for
       leavening, you need to create an	object for "Nissan 13 5764, after
       sunset",	which will print out as	"Nissan	14 5764, after sunset".

   SAMPLE CODE
       See "eg/sunset.pl", included in this distribution.

SUPPORT
       Support for this	module is provided via the datetime@perl.org email
       list. See http://lists.perl.org/	for more details.

CREDITS
       - Thanks	to my good friend Richie Sevrinsky who helped me make sense of
       the calculations	in the first place.

       - Thanks	to all the DateTime developers and the authors of the other
       Calendar	modules, who gave me code to steal from	... I mean emulate.

       - Thanks	to Arthur Spier, Rabbi Bushwick	and Messrs. Dershowitz and
       Reingold	for writing excellent books on the subject.

AUTHOR
       Steven J. Weinberger <perl@psycomp.com> Raphael Mankin
       <RAPMANKIN@cpan.org> (co-maintainer)

COPYRIGHT
       Copyright (c) 2003 Steven J. Weinberger.	 All rights reserved.  This
       program is free software; you can redistribute it and/or	modify it
       under the same terms as Perl itself.

SEE ALSO
       DateTime

       DateTime::Event::Sunrise

       DateTime::Duration

       DateTime::Event::Jewish

       datetime@perl.org mailing list

perl v5.32.1			  2011-11-07			     Hebrew(3)

NAME | SYNOPSIS | DESCRIPTION | THE HEBREW (JEWISH) CALENDAR | SOURCES | METHODS | SUNSET AND THE HEBREW DATE | SUPPORT | CREDITS | AUTHOR | COPYRIGHT | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=DateTime::Calendar::Hebrew&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help