Calendar::Simple(3pm)

💖 Calendar::Simple(3pm) 💖

okay bestie, so this is the Calendar::Simple page from the Perl manual (it lives in the "User Contributed Perl Documentation" section, iykyk) and honestly? it's giving tiny-but-mighty. one little module, one little function, and it'll hand you a whole month laid out in weeks. no cap. 🗓️✨

---

✨ NAME ✨

Calendar::Simple — a Perl extension that makes simple calendars. that's it. that's the whole vibe. 🎀

---

🌸 SYNOPSIS 🌸

look at her go:

use Calendar::Simple;

my @curr      = calendar;             # get current month
my @this_sept = calendar(9);          # get 9th month of current year
my @sept_2002 = calendar(9, 2002);    # get 9th month of 2002
my @monday    = calendar(9, 2002, 1); # get 9th month of 2002,
                                      # weeks start on Monday

my @span      = date_span(mon   => 10,  # returns span of dates
                          year  => 2006,
                          begin => 15,
                          end   => 28);

like, she's literally just a few lines and she ate. 💅

---

🦋 DESCRIPTION 🦋

a very simple module (her words, not mine, but she's right) that exports one function called calendar. that's the main character. and then there's date_span too — more on her in a sec. 🫶

🌼 calendar

this function returns a data structure representing the dates in a month. and bestie, it's an array of array references: the first level array represents the weeks in the month, and the second level array contains the actual days. so it's weeks → days, nested like russian dolls but for calendars. 🪆

by default each week starts on a Sunday, and the value in the array is the date of that day. any days hanging out at the beginning of the first week or the end of the last week that are actually from the previous or next month? they get the value undef. they're just visiting, they don't live here. 🙈

if the month or year parameters are omitted, then the current month or year are assumed. so calendar with no args is like "sure babe, today's month, go off". 💖

there's a third, optional parameter, start_day, that lets you set the day each week starts with, and it takes the same values as localtime sets for wday (namely, 0 for Sunday, 1 for Monday and so on). slay. 🌈

🌺 date_span

this function returns a cut-down version of a month data structure which begins and ends on dates other than the first and last dates of the month. so it's calendar but with boundaries. she has range. 👑

any weeks that fall completely outside of the date range are removed from the structure, and any days within the remaining weeks that fall outside of the date range are set to undef. thorough. 💀

as there are a number of parameters to this function, they are passed using a named parameter interface (because positional args for this many things would be chaos, and we respect ourselves). the parameters are as follows:

🌷 year

the required year. defaults to the current year if omitted. (so "required" is doing a lot of heavy lifting here, but okay, love that for her. 😭)

🌷 mon

the required month. defaults to the current month if omitted.

🌷 begin

the first day of the required span. defaults to the first if omitted.

🌷 end

the last day of the required span. defaults to the last day of the month if omitted.

🌷 start_day

indicates the day of the week that each week starts with. this takes the same values as the optional third parameter to calendar. the default is 1 (for Monday). ✨

⚠️ NOTE: as of version 2.0.0, the default start_day has changed. previously, it was Sunday; now, it is Monday. this is so the default behaviour matches that of the standard Unix cal command. glow-up fr fr. 💅

and heads up — this function isn't exported by default, so in order to use it in your program you need to use the module like this:

use Calendar::Simple 'date_span';

don't forget the string, bestie. it's the whole point. 🎀

🌸 EXAMPLE 🌸

a simple cal replacement would therefore look like this:

#!/usr/bin/perl

use strict;
use warnings;
use Calendar::Simple;

my @months = qw(January February March April May June July August
                September October November December);

my $mon = shift // (localtime)[4] + 1;
my $yr  = shift // (localtime)[5] + 1900;
my $sd  = shift // 1;

my @month = calendar($mon, $yr, $sd);
print "\n$months[$mon -1] $yr\n\n";

my @days = qw(Su Mo Tu We Th Fr Sa);
push @days, splice @days, 0, $sd;
print "@days\n";

foreach (@month) {
  print map { $_ ? sprintf "%2d ", $_ : '   ' } @$_;
  print "\n";
}

a version of this example, called pcal, is installed when you install this module. so you get a whole tool for free. we love a bonus. 🎁

🌼 Date Range 🌼

this module will make use of DateTime if it is installed. by using DateTime it can use any date that DateTime can represent. iconic. 🔥

if DateTime is not installed it uses Perl's built-in date handling and therefore can't deal with dates before 1970 and it will also have problems with dates after 2038 on a 32-bit machine. so like… plan accordingly. no cap. ⏳

---

⭐ EXPORT ⭐

calendar 💖 (and only calendar by default — date_span needs the explicit ask, remember?)

---

🧚 AUTHOR 🧚

Dave Cross <dave@mag-sol.com>

---

🫶 ACKNOWLEDGEMENTS 🫶

with thanks to Paul Mison <cpan@husk.org> for the start day patch. king behaviour. 👑

---

💜 COPYRIGHT 💜

Copyright (C) 2002-2008, Magnum Solutions Ltd. All Rights Reserved.

---

🌈 LICENSE 🌈

this script is free software; you can redistribute it and/or modify it under the same terms as Perl itself. i.e. go wild, but respectfully. 💅

---

🔥 SEE ALSO 🔥

perl, localtime, DateTime

---

and that's the whole page bestie, hope this was useful 💖 this was perl v5.42.0 dated 2024-05-05 — literal documentation from the future (or at least, like, recent past), served fresh by Calendar::Simple(3pm). mwah 🎀✨🍓