Module Proposal: Calendar::CelticTree
am 27.01.2007 15:20:13 von jimicarloHi guys, long time no see
I have a script on a website: http://www.webu.co.uk/cgi-bin/
treecal.cgi
that I am converting to a module (stripping the GUI stuff and making
the subs make sense!)
Here's my pod so far (not complete!)... any suggestions on the
functionality side? How about the name?
=pod
=head1 NAME
Calendar::CelticTree
=head1 SYNOPSIS
use Calendar::CelticTree qw/calendar/;
my $calendar_year = makeyear(2007);
=head1 DESCRIPTION
This module provides functions for working with Tree Calendar dates
and creating calendars.
The Celtic Tree Calendar is a complex system and does not translate
onto the Gregorian calendar
easily, with key dates changing from year to year. It consists of 13
months, all of which are governed
by the lunar cycle.
The tree calendar has various incarnations but mine is based on the
Celtic Tree Calendar by
Linda Kerr which may be found at http://www.auburn.edu/~kerrlin/
treecal.html in which the
months follow the lunations and February 2, or Imbolc, always falls on
the Rowan moon, the
2nd lunation.
I also had help from http://www.timeanddate.com/ and http://
www.hermetic.ch/cal_sw/ve/ve.htm
as references for lunation times.
Various pages at http://en.wikipedia.org/ helped me write the
algorithms for figuring out when the
lunations and solstices are.
A working implementation of the calendar may be found at http://
www.webu.co.uk/cgi-bin/treecal.cgi
=head1 Subs
The EXPORT_TAGS hash is used so that you can import a bunch of related
subs at once...
=over
=item use Calendar::CelticTree ':calendar';
Imports only those subs that are directly related to calendar
creation, ie:
=over
=item makeyear (?$year?)
This sub returns a data structure for the given or current year. The
structure takes the form of
a hash of hashes of arrays. The keys of the top-level hash are the
names of the tree months -
Birch, Rowan, Ash, Alder, Willow, Hawthorn, Oak, Holly, Hazel, Vine,
Ivy, Reed, Elder. The
values of this hash are more hashes. The keys of these child hashes
are the dates of the tree
month. The values are arrays, containing the return value of
gmtime(), and special dates in the
calendar are also labelled with an extra element, eg 'Midsummer':
($time,$tday,$tmon,$tyear,$tdayname,$tfullmon, $label)
$time = Time in seconds since epoch
$tday = Tree calendar day of the month (index 1, not 0!)
$tmon = Three letter code for the month
$tyear = The year
$tdayname = Tree calendar name of the weekday
$tfullmon = Three calendar full month name
$label = Optional additional information for that day (empty string if
not present)
To make use of this:
use TreeCalendar qw/:all/;
my $year = makeyear(2007);
foreach my $mon(months()){ # three-letter codes
print "\n$mon\n";
my $month = $year->{$mon};
foreach my $date (sort keys %$month){
my ($time,$tday,$tmon,$tyear,$tdayname,$tfullmon, $label)
= @{$month->{$date}};
my $gmtime = gmtime($time);
print "$tdayname, $tday $tfullmon, $tyear ($gmtime)\n";
}
}
=item makemonth
Currently undocumented (and relatively unimportant)
=item treedate
Accepts a gmtime date string or uses the current date
and returns ($tday,$tmon,$tyear,$tdayname,$tfullmon)
=back
=item use Calendar::CelticTree ':month';
Imports only those subs that are directly related to lunar date
calculations, ie:
=over
=item months
Returns an array of the three-letter month codes used in the calendar
qw/DAp
Bir Row Ash Ald
Wil Haw Oak Hol
Haz Vin Ivy Bla Eld/
=item corr
Returns an array of the full-names of the months used in the calendar
"Days Apart",qw/
Birch Rowan Ash Alder
Willow Hawthorn Oak Holly
Hazel Vine Ivy Reed Elder/
=item daynames
Returns an array of the full-names of the days of the month
qw/Moonday Tirsday Odinsday Thorsday
Friggasday Lokiday Sunday Mooneve/
=back
=item use Calendar::CelticTree ':moon';
Imports only those subs that are directly related to lunar date
calculations, ie:
=over
=item lastmoon
Accepts a gmtime date string and returns the index of the moon just
before the date given
=item nextmoon
Accepts a gmtime date string and returns the index of the moon just
after the date given
=item lastmoongmtime
Accepts a gmtime date string and returns the gmtime of the moon just
before the date given
=item nextmoongmtime
Accepts a gmtime date string and returns the gmtime of the moon just
after the date given
=back
=item use Calendar::CelticTree ':basic';
Imports only those subs form the fundamental framework for
calculations, ie:
=over
=item timesinceequinox
Accepts a gmtime date string and returns the time between it and the
equinox preceeding it.
=item moontotime
Accepts a moon index and converts it to time
=item moontogmtime
Accepts a moon index and converts it to gmtime
=item timetomoon
Reverse of moontotime
=item gmtimetomoon
Reverse of moontogmtime
=item solvequadratic
Accepts ($y,$a,$b,$c) and solves x for
y = axx + bx + c
=back
=back
=head1 AUTHOR
Jimi-Carlo Bukowski-Wills jimicarlo@gmail.com
=head1 SEE ALSO
HTTP::Date (the str2time function is used in this module)
Calendar (for other calendars)
=cut