NAME
Vigil::Calendar - Provides a way to describe a calendar _month so that you can easily build HTML calendars or populate your flavour of web calendar.
SYNOPSIS
Here's how you might render a calendar _month using the module:
my ($CURRENT_month, $CURRENT_DAY_OF_month) = do { my @t = localtime; ($t[4] + 1, $t[3]) };
#Create the calendar object
my $calendar = new MongerCalendar($year, $month);
#Now that we know what we are looking at, establish the fore and next _months links
$previous_month_link = "$ScriptURL?_year=$calendar->{_previous_month_year}&_month=$calendar->{_previous_month_number}";
$next_month_link = "$ScriptURL?_year=$calendar->{_next_month_year}&_month=$calendar->{_next_month_number}";
print qq~
<table border="1" width="100%">
<thead>
<tr>
<td colspan="7" style="text-align:center;">
<span style="font-weight: bold;">~, $calendar->_month_name, qq~, $year</span><br>
<a href="$previous_month_link"><< Previous _month</a>
<a href="$next_month_link">Next _month >></a>
</td>
</tr>
<tr>
<th>Sun</th>
<th>Mon</th>
<th>Tue</th>
<th>Wed</th>
<th>Thu</th>
<th>Fri</th>
<th>Sat</th>
</tr>
</thead>
<tbody>
~;
for(my $a = 1; $a <= $calendar->weeks_in_month; $a++) {
my $bgcolor = ($a % 2 == 1) ? "#F5F5F5" : "#DCDCDC";
print qq~<tr style="height:40px;">~;
my @weekdays = $calendar->week_definition($a);
for(my $weekday = 0; $weekday <= 6; $weekday++) {
if(($a == 1) && ($weekdays[$weekday] > $weekdays[$#weekdays])) {
$bgcolor = "#C0C0C0";
}
elsif(($a == $calendar->weeks_in_month) && ($weekdays[$weekday] < $weekdays[0])) {
$bgcolor = "#C0C0C0";
}
print qq~
<td style="background-color: $bgcolor; vertical-align: top; font-weight: bold;">
~;
if(($weekdays[$weekday] == $CURRENT_DAY_OF_month) && ($month == $CURRENT_month)) {
print qq~<span style="color:#ff0000;">$weekdays[$weekday]</span>~;
} else {
print $weekdays[$weekday];
}
print qq~
</td>
~;
}
print qq~
</tr>
~;
}
print qq~
</tbody>
</table>
~;DESCRIPTION
This module is based upon a calendar week. Look at your calendar hanging on the wall. Look at any row of seven days across, where the first day in the row is Sunday. That is a calendar week. Here is a visual reference:
Definition of a Calendar Week:
------------------------------------------------------------------------
| Sunday | Monday | Tuesday | Wednesday | Thursday | Friday | Saturday |
------------------------------------------------------------------------
| | | | | | | |
| 1 | 2 | 3 | 4 | 5 | 6 | 7 |
| | | | | | | |
------------------------------------------------------------------------The basis of most functions in this module is the date, which consists of a _year, a _month and a day of the _month. In most of the methods in this module, all calcualations are based upon a mathematical equation of constants which will always return the day of the week from a given date. The constants must change slightly for each century, however, this script is written to support any date between January 1st, 1800 and December 31st, 2099. It is also important to note that this module also allows for leap _years in all it's calculations.
You can use this module to populate HTML calendars (both calendar weeks and full _months). The ZIP file that this module was distributed in contains two small scripts that demonstrate how this is done. Note that the montly.cgi will also print out a table showing the evaluation of the object plus what is contained in the original object creation variables.
Additionally, this script will provide lots of useful information about _months and _years. As you read on about the various methods you will see how much information you can extract from a simple date.
CLASS METHODS
- my $calendar = Vigil::Calendar->new($year, $month);
-
The year and month are optional. If you do not provide them, the object will default to the current year and month UTC.
OBJECT METHODS
- my @information = $obj->evaluate;
-
Having created the object, calling the evaluate method will return a list of values particular to the year and month of the object. Here are the values returned by this method:
$information[0] contains the name of the month
$information[1] contains the number of days in the previous calendar month
$information[2] contains the number of days in the month referenced by this object
$information[3] contains the number of days in the month following the objects month
$information[4] returns '1' if the object year is a leap year, otherwise returns '0'
$information[5] contains the name of the day (Sunday, Monday, etc.) of the first day of the objects month
$information[6] contains the name of the day of the last day of the month
$information[7] returns the number of sundays in the objects month
- $obj->is_a_leap_year;
-
my $truth = $obj->is_a_leap_year;--or--
if($obj->is_a_leap_year) { ....do stuff here.... }This method returns a '1' or '0' (true or false) if the current objects year is a leap year.
- my $value = $obj->dayname($day_of_month, BOOLEAN);
-
my $name_of_day = $obj->dayname($dayof_month); my $short_name_of_day = $obj->dayname($dayof_month, 1);This method will return the actual name of the day for any day of the current objects month. There are three arguments to be passed but only one is required. The first argument MUST be a day of the month (number from 1-31 depending on the month). The method does not test for the day of the month so make sure you pass it. The dayname that is returned will be in the long format (i.e.: Sunday, Wednesday, etc.).
If you would like to get the name of the day in it's three character abbreviated format, then pass a true value as the second argument.
- my $position = $obj->weekday($day_of_month);
-
This method accepts a day of the month for the current objects year and month and returns that days position within a calendar week. For example, if the current objects year was 2001 and the month was 4 (April), then passing this method the day of month 26 would return a value of 5 since the 26th of April, 2001 is a Thursday which is the fifth day of the calendar week. Here is the list of values returned for each day of the calendar week:
Sunday => 1 Wednesday => 4 Saturday => 7 Monday => 2 Thursday => 5 Tuesday => 3 Friday => 6 - my $value = $obj->calendar_week($day_of_month);
-
This method accepts a day of month as an argument for the current objects year and month and then returns which calendar week that day is in. For example, if we look at April for 2001, there are five calendar weeks:
------------------------------------------------------------------------ | Sunday | Monday | Tuesday | Wednesday | Thursday | Friday | Saturday | ------------------------------------------------------------------------ | | | | | | | | | 1 | 2 | 3 | 4 | 5 | 6 | 7 | | | | | | | | | ------------------------------------------------------------------------ | | | | | | | | | 8 | 9 | 10 | 11 | 12 | 13 | 14 | | | | | | | | | ------------------------------------------------------------------------ | | | | | | | | | 15 | 16 | 17 | 18 | 19 | 20 | 21 | | | | | | | | | ------------------------------------------------------------------------ | | | | | | | | | 22 | 23 | 24 | 25 | 26 | 27 | 28 | | | | | | | | | ------------------------------------------------------------------------ | | | | | | | | | 29 | 30 | | | | | | | | | | | | | | ------------------------------------------------------------------------If you flip through your calendar, you will see that the maximum possible number of calendar weeks in any given _month is six.
With the calendar above:
$obj->calendar_week(20) would return a value of '3' since the 20th is in the third calendar week of the month.
$obj->calendar_week(30) would return 5, $obj->calendar week(4) would return 1, etc.
- my $value = $obj->_month_name;
-
my $name = $obj->_month_name; my $name = $obj->_month_name(4);This method will return the name of the current objects month if called without any arguments. Otherwise, passing the method an argument that is a digit between '1' and '12', the method will return the name of that month.
- my $value = $obj->_month_number;
-
my $number = $obj->_month_number; my $number = $obj->_month_number('Apr'); my $number = $obj->_month_number('April'); my $number = $obj->_month_number($month_name);This method takes the name of a month in letters, and returns the number of that month (between '1' and '12'). The method will even take a three letter abbreviation for the month. Without an argument it returns the number of the month in the object.
- my $value = $obj->weeks_in_month;
-
This method will return the number of calendar weeks in the current objects year and month.
- my $value = $obj->days_in_month;
-
This method returns the number of days in the current objects year and month.
- my $value = $obj->days_in_previous_month;
-
This method returns the number of days in the _month prior to the current objects month.
- my $value = $obj->days_in_next_month;
-
This method returns the number of days in the month following the current objects month.
- my @week_dates = $obj->week_definition($calendar_week);
-
Sample call; my @week_dates = $obj->week_definition($calendar_week); my @week_dates = $obj->week_definition(3);
This method requires one argument and that is the number of a calendar week within the current objects year and month. This value can only be between '1' and '6'. Note, if you supply a number higher than six, the method will return a null value. If you supply zero or a number less than zero, the method will return some very interesting results, none of which will be accurate.
For example, if you created an object for April, 2030 then passed this method the number for the third calendar week: $obj->week_definition(3); Then here is the list that would be returned:
(14, 15, 16, 17, 18, 19, 20) - my $year = $obj->year;
-
This will always contain the year that was specified when the object was created.
- my $month = $obj->month;
-
This will always contain the month that was specified when the object was created.
- my $prev_month = $obj->previous_month_number;
-
This will always contain the number of the month previous to the objects current month.
- my $prev_month_year = $obj->previous_month_year;
-
If the previous months number is 12, that means you went back a year. So instead of forcing you to calculate it, this has been done for you and placed in the above variable.
- my $next_month = $obj->next_month_number;
-
Op. Cit. but the other direction.
- my $next_month_year = $obj->next_month_year;
-
Op. Cit. but the other direction.
Local Installation
If your host does not allow you to install from CPAN, then you can install this module locally two ways:
Same Directory
In the same directory as your script, create a subdirectory called "Vigil". Then add these two lines, in this order, to your script:
use lib '.'; # Add current directory to @INC use Vigil::Calendar; # Now Perl can find the module in the same dir #Then call it as normal: my $calendar = Vigil::Calendar->new;In a different directory
First, create a subdirectory called "Vigil" then add it to
@INCarray through aBEGIN{}block in your script:#!/usr/bin/perl BEGIN { push(@INC, '/path/on/server/to/Vigil'); } use Vigil::Calendar; #Then call it as normal: my $loop = Vigil::Calendar->new;
AUTHOR
Jim Melanson (jmelanson1965@gmail.com).
Created March, 2001.
Last Updated August, 2025.
LICENSE
This module is free software; you may redistribute it and/or modify it under the same terms as Perl itself.