view release on metacpan or  search on metacpan

lib/Date/Indian.pm  view on Meta::CPAN

=head1	DESCRIPTION

	This module is not a calander generator. It helps to wirte one by 
	providing essential and auxillary services.
	
	Services offered by this module are:

	 1. Sun rise/set.
	 2. Moon rise/set.
	 3. Tithi at a given time.
	 4. Moon's constallatation at a given time.
	 5. Tithi ending time(s) on a given day.
	 6. Moon's constallation change time(s) on a given day.
	 7. Length of the day (sunrise to sunset).
	 8. Previous / current new moon date and time.
	 9. Next new moon date and time.
	10. Rahu kalam.
	11. Gulika kalam.
	12. Yama gandam.
	13. Durmuhurta periods.
	14. Current yoga.
	15. Current karana.
	16. Yoga change time(s) on given day.
	17. Karana change time(s) on given day.
	18. Weekday.
	19. Julian day.
	20. ymdt ( year, month, day and time values)
	21. Ayanamsa.
	22.

=head1	SERVICES

Here is a description of the services provided by the module.

=over 4

=item Gregorian date and time.

This service provides the date ( and time of the day in hours & fraction of 
hours ) for the given date object.

my (@y, $m, $d, $t ) = $date -> ymd();


=item Sun rise and Sun set

This service is provided by the method sunriseset().

($sunrise, $sunset, $flag) = $date -> sunriseset();

Depending the latitude and time of the year, the Sun may not
rise or set at a given location. This is indicated by the $flag
string data.

=item Moon rise and Moon set

This service is provided by the method moonriseset().

($moonrise, $moonset, $flag) = $date -> moonriseset();

At times the Moon may set or rise more than once on a gicen calendar
day. Also some days the Moon will not rise or set. Such cases are
indicated by the  $flag string.

=item Tithi 

This service is provided by the the following methods.

=over 4

=item  Tithi at a given time.

The method 'tithi' provides this service.

my $tithi = $date -> tithi(<time of the day>);

where the time of the day is expressed as a decimal fraction in the
range 0.0 ..... 1.0 where a 0 value means at 00:00 hrs of the calendar
date and 0.5 the 12:00 noon and 1.0 the begining of the next day.

=item Tithi endings.

The method tithi_endings() provides the service of itentifying when the
a tithi ending occurs on a given date. 

my %t_times = $date->tithi_endings();

At times more than one tithi may end on the same calendar date and on some
days none ends. Hence the method returns an hash where keys are tithi
numbers in the range 0...29 and values corrosponding are times in hours
at local time. Note that the hash may be empty if no tithi ends on a given
calendar date.

=back

=item Nakshatra

=over 4

=item Nakshyatra at a given time.

The method serving is nakshyatra().

$n_time = $date -> nakshyatra(<time of the day>)

=item Nakshyatra endings.

my %n_endings = $date -> nakshyatra_endings ();

This service is analogous to the tithi_endings service.

=back

=item Length of the day

The length of the day is kind of misnomer. It actually is the duration
of the Sun's visibility defined as 
  
     sun set - sun rise

on a given day provied they both are meaningful.

The usage is

$d_length = $date -> daylength();

=item New moon time

The date and time of the most recent new moon is provided by the service.

my $pnm = $date -> newmoon();

The service allowes you to find the 'n' th new moon, if that is needed.

my $next_newmoon = $date -> newmoon(1);

=item Varjyam

This is provided by the method varjyam

my @varjyam = $date -> varjyam();

The array returned provides starting times of varjya periods on the
given date. The ending time of any varjya is always 1.6 hours from
the respective start time. So, ending times are seperately not 
provided by the method.

=item Rahu kalam

This is provided by the method rahu_kalam.

my ($rk_start, $rk_end) = $date -> rahu_kalam ();