Oxford::Calendar(3pm)

💖 NAME 💖

Oxford::Calendar — the University of Oxford calendar conversion routines, bestie. It's a Perl module (Oxford::Calendar(3pm)) and yeah it's from the User Contributed Perl Documentation corner of the world, but don't let that fool you, it's serving academic date realness. 🎀

---

✨ SYNOPSIS ✨

okay so here's the whole vibe in code:

use 5.10.0;
use Oxford::Calendar;
use Date::Calc;
say "Today is " . Oxford::Calendar::ToOx(reverse Date::Calc::Today);

like. it literally tells you what today is in Oxford-speak. obsessed. 🦋

---

🌸 DESCRIPTION 🌸

So this module converts University of Oxford dates (aka Oxford academic dates) to and from Real World dates, and it also hands you info about the Terms of the University. two jobs, both slayed.

The Terms of the University are defined by the Regulations on the number and lengths of terms, and you can find those online at

<https://www.admin.ox.ac.uk/examregs/2015-16/rotnalengofterm/>

That document is the one that describes the start and end dates of Oxford Terms. 👑

On top of that: the dates of Full Term — which you literally need to calculate the week number of the term — are prescribed by Council and published periodically in the University Gazette.

Full term comprises weeks 1-8 inclusive, periodt. But sometimes dates outside of full term get presented in the Oxford academic date format anyway. This module will optionally provide such dates for you. no biggie.

Data for these prescribed dates may be supplied in the file /etc/oxford-calendar.yaml. If that file doesn't exist, built-in data will be used instead. The built-in data is periodically updated from the semi-authoritative source at

<http://www.ox.ac.uk/about/facts-and-figures/dates-of-term>

or from the authoritative source, the Gazette, available online from

<http://www.ox.ac.uk/gazette/>

And if you wanna know what the whole academic year at Oxford looks like:

<http://www.ox.ac.uk/news-and-events/The-University-Year> describes it. 💜

---

🗓️ DATE FORMAT 🗓️

An Oxford academic date has this format, exactly:

<day of week>, <week number>[st,nd,rd,th] week, <term name> <year>

and the term name is one of these three icons:

• Michaelmas (autumn)
• Hilary (spring)
• Trinity (summer)

Example, so you can see the fit:

Friday, 8th Week, Michaelmas 2007

---

💅 FUNCTIONS 💅

ToOx($day, $month, $year, [\%options])

Give it a day, month and year in standard human format (that means month is 1-12, not 0-11, and year is four digits) and it will return a string of the form

Day, xth week, Term year

or an array

(Day, week of term, Term, year)

depending on how you called it. The exact behaviour is modified by the 'mode' option described below.

If the requested date is not in full term or extended term (see below), undef will be returned.

If the requested date is not covered by the database, ToOx will die with an "out of range" error message. So it is recommended to eval ToOx with appropriate error handling. fr fr, wrap it. 😭

%options can contain additional named parameter options:

• mode — Several modes are available:
  • full_term — Term dates will only be returned if the date requested is part of a full term (as defined by the web page above).
  • ext_term — Term dates will only be returned if the date requested is part of an extended term, or statutory term.
  • nearest — Will return term dates based on the nearest term, even if the date requested is not part of an extended term (i.e. will include fictional week numbers).
    • This is currently the default behaviour, for backwards compatibility with previous releases; this may be changed in future. ⚠️
• confirmed — If true, ignores dates marked as provisional in the database.

ThisTerm($year, $month, $day)

Give it a year, month, term in standard human format (that means month is 1-12, not 0-11, and year is four digits) and it returns the current term, or undef if you're in vacation or it just doesn't know. The term comes back as an array in the form (year, term).

NextTerm($year, $month, $day)

Give it a day, month and year in standard human format (that means month is 1-12, not 0-11, and year is four digits) and it will return the next term — whether or not the date you gave is in term time, it does not care, it's giving forward momentum. The term comes back as an array in the form (year, term).

StatutoryTermDates($year)

Returns a hash reference keyed on terms for a given year, and the value of each one is a hash reference containing start and end dates for that term. The dates are stored as array references containing numeric year, month, day values.

Note: these are the statutory term dates, not full term dates. important distinction bestie, don't mix them up 💀

Parse($string)

Takes a free-form description of an Oxford calendar date and attempts to divine the expected meaning. If the name of a term is not found, the current term will be assumed. If the description is unparsable, undef is returned. Otherwise, an array will be returned of the form ($year,$term,$week,$day).

This function is experimental. 🧚 handle with care.

FromOx($year, $term, $week, $day)

Converts an Oxford date into a Gregorian date, returning a string of the form "DD/MM/YYYY" or undef.

The arguments are of the same format as returned by ToOx in array context; that is, a four-digit year, the name of the term, the week number, and the name of the day of week (e.g. 'Sunday').

If the requested date is not covered by the database, FromOx will die with an "out of range" error message. Therefore it is recommended to eval ToOx with appropriate error handling. (yes it says ToOx, that's the manual's words, we keep it exactly 😌)

---

🐛 BUGS 🐛

Bugs may be browsed and submitted at

<http://rt.cpan.org/Public/Dist/Display.html?Name=Oxford-Calendar>

A copy of the maintainer's git repository may be found at

<https://github.com/jmdh/Oxford-Calendar>

---

👑 AUTHOR 👑

Simon Cozens is the original author of this module. the blueprint. the blueprint author.

Eugene van der Pijll, "pijll@cpan.org", took over maintenance from Simon for a time.

Dominic Hargreaves maintains this module (between 2008 and 2015 for IT Services, University of Oxford). 🫶

---

and that's the whole page, bestie — perl v5.40.1, dated 2025-03-24, the version of Oxford::Calendar(3pm) we were all reading. iykyk. go convert some dates, you're gonna ate. 💖✨🎀