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 most awkward disclaimer is finished, on to the code issues.

I added the ability to pass a function reference to a DateTime::Calendar::Hebrew object. The Calendar will
call this routine to determine sunset for a given date. This puts the responsibilty on you to figure out
sunset in your routine. I use Astro::Sunrise, because sunset is a pretty regular occurence in NYC. I
could imagine that people in other areas could use lookup tables after speaking to a Rabbi. As a suggestion,
most calendar calculations (Dershowitz/Reingold included) use 6pm as the boundary between days. If you want a
Hebrew calendar for the North Pole, use 6pm as your sunset.

The API for your subroutine is simple. It gets the parameters year, month & day, and is expected to return
an integer, representing the time of sunset, in seconds since midnight. e.g. 64800 is equivalent to 6pm.

If there is a time component in the Calendar, and it is later than the time returned by your routine, the
internal RD day count will be incremented, resulting in a Hebrew date one day later. Of course if you do this,
you can't convert it to another Calendar anymore, because the RD is off.

Here's sample code:

SAMPLE CODE:
-----------

#!/usr/local/bin/perl
use DateTime::Calendar::Hebrew;
use Astro::Sunrise;

# Rosh HaShana (Jewish New Year) 2003/5764
$HT = new DateTime::Calendar::Hebrew(
	year   => 5764,
	month  => 7,
	day    => 1,
);

# Since the default time is 00:00,
# there's no change in the date

print $HT->ymd, "\n";

$HT->set(
	hour   => 22,
	minute => 30,
	sunset => \&sunset,
);

# The time 22:30 is always after sunset
# in New York. The date has changed

print $HT->ymd, "\n";

exit;

sub sunset {
	my($year, $month, $day) = @_;

	# Latitude/Longitude for NYC
	my $long = -73.59;
	my $lat  = 40.38;

	# Eastern Time
	my $zone = -5;

	my $dst  = 1;

	my ($sunrise, $sunset) = sunrise($year,$month,$day,$long,$lat,$zone,$dst);
	my ($hs, $ms) = split(/:/, $sunset);
	my $seconds = $hs * 60 * 60 + $ms * 60;

	return $seconds;
}

Steven Weinberger <perl@psycomp.com> 2003-09-23
