/ 
DateTime-Event-Jewish-0.03
River stage zero No dependents
/ DateTime::Event::Jewish::Sunrise

NAME

DateTime::Event::Jewish::Sunrise - Calculate halachically interesting times

SYNOPSIS

use DateTime::Event::Jewish::Sunrise ;

my $jerusalem = DateTime::Event::Jewish::Sunrise->new([31,34,57], [35,13,0]), 'Asia/Jerusalem'; my $date = DateTime->new(year=>2010, month=>3, day=>30);

my $shkia = $jerusalem->shkia($date); my $shabbat = $jerusalem->kabbalatShabbat($date); my $netz = $jerusalem->netzHachama($date); my $night = $jerusalem->motzeiShabbat($date);

DESCRIPTION

This module assumes that the earth is a smooth sphere. No allowance is made for atmospheric refraction or diffraction of light passing close to the earth's surface. To allow for refraction one uses a depression of 0.833 degrees (50' arc). As, by default, we use 1 degree of depression this is more than adequate.

The methods that return times actually return a DateTime object in the correct timezone as specified in the constructor.

All times are corrected for the equation of time: the variation between sundial time and clock time.

If you call this module for a high latitude in the height of summer or the depth of winter it will return nonsense. Ask a silly question and you will get a very silly answer.

Calculations are done using the spherical cosine rule.

new($latitude, $longitude, $timeZone)

Constructs a new object.

$latitude

An arrayref of three numbers representing degrees, minutes and seconds of latitude. North latitudes are positive, south latitudes are negative.

$Longitude

An arrayref of three numbers representing degrees, minutes and seconds of longitude. East longitudes are positive, west longitudes are negative.

$timeZone

A time-zone name as stored in the time-zone database.

halachicHalfDay($date, [$extra])

Calculates the length of the halachic half day in minutes. This is half the time between sunrise and sunset.

If you call this method for a high latitude in the height of summer or the depth of winter it will return 0. Ask a silly question and you will get a very silly answer.

$date

A DateTime object, either a Gregoorian or a Hebrew date. Only the day and month are relevant.

$extra

The number of degrees below the tangent plane that the sun should be at halachic sunrise/set. Default 1.

localnoon($date)

Returns a DateTime object of the UTC time of local noon. You will have to call set_time_zone on it to get your local time.

$date

A DateTime object, either a Gregorian or a Hebrew date. Only the day and month are relevant.

halfday($date, [$as])

Calculates the offset in minutes from local noon of sunrise/sunset at the given location on the specified day of the year. i.e. the time when the sun is 90 degrees from the zenith.

$date

A DateTime object. Only the day and month are relevant. N.B. This is a Gregorian date.

sunset($date)

Calculates the time of sunset, i.e. when the mid-line of the sun is 90degs from the zenith. The result returned has to be corrected for your distance from the standard meridian.

$date

A DateTime object. Only the day and month are relevant.

sunrise($date)

Calculates the time of sunrise, i.e. when the mid-line of the sun is 90degs from the zenith. The result returned has to be corrected for your distance from the standard meridian.

$date

A DateTime object. Only the day and month are relevant.

shkia($date, [$extra])

Kabbalat Shabbat is 15 minutes before shkia, though some people use 18 minutes; Motzei Shabbat is 72 minutes after shkia (R Tam)

Other values for 'extra' give the times of Motzei Shabbat. Pre 1977 7.5 degs Post 1977 8 degs or 8.5 Fast end 6 degs

$date

A DateTime object specifying the Gregorian date that we are interested in.

$extra

The number of degrees below the tangent plane that the sun should be at halachic sunrise/set. Default 1.

netzHachama($date, [$extra])

Calculates the time of halachic sunrise. This is usually when the sun is 1 degree below the tangent plane, though some people use other values.

$date

A DateTime object specifying the Gregorian date that we are interested in.

$extra

The number of degrees below the tangent plane that the sun should be at halachic sunrise/set. Default 1.

kabbalatShabbat($date, [$extra])

Calculates the time of kabbalat Shabbat. This is usually 15 minutes before shkia, though some people use 18 minutes.

$date

A DateTime object specifying the Gregorian date that we are interested in.

$extra

The number of minutes before shkia that one should use for kabbalat Shabbat. Default 15.

motzeiShabbat($date, [$extra])

Motzei Shabbat according to R Tam is 72 mins after shkia. More conventionally we use the time when the sun is either 7degs or 8 degs or 8.5 degs below the horizon. Some people even use 11 or 14 degrees, but this quickly becomes ridiculous in even moderate latitudes.

For fast ends we use 6 degs (R Schneur Zalman).

$date

A DateTime object. Only the day and month are relevant.

$extra

The number of degrees below the tangent plane that the sun should be at motzei Shabbat. Default 8.

recalculate_coordinate($location, $as)

Convert a tupe of (degrees, minutes, seconds) to a normal form.

$location

An arrayref of three components: degrees, minutes, seconds.

$as

Return value type. Can be specified as 'deg', 'min', 'sec' or 'rad'; default return value is a proper coordinate tuple.

AUTHOR

Raphael Mankin, <rapmankin at cpan.org>

BUGS

Please report any bugs or feature requests to bug-datetime-event-jewish at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=DateTime-Event-Jewish. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc DateTime::Event::Jewish

You can also look for information at:

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

Copyright 2010 Raphael Mankin.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.