/ 
DateTime-Event-Jewish-0.08
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. If an evaluation fails, e.g. no sunrise inside the Arctic cirle, undef is returned.

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, e.g. "Europe/London".

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 Gregorian 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.

returns

The length of the half-day in minutes. Returns 0 if there is no sensible answer, e.g. inside the Arctic circle in summer.

localnoon($date)

Returns a DateTime object of the local time of local noon.

$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.

Returns

The length of the ahlf day in minutes. Returns 0 if there is no sensible answer, e.g. inside the ARctic circle in summer.

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.

Returns

A DateTime object.

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.