Oxford::Calendar - University of Oxford calendar conversion routines

       Simon Cozens is the original author of this module.

       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).

perl v5.40.1                                       2025-03-24                              Oxford::Calendar(3pm)

       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>

       An Oxford academic date has the following format:

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

       where term name is one of

       •   Michaelmas (autumn)

       •   Hilary (spring)

       •   Trinity (summer)

       Example:

       Friday, 8th Week, Michaelmas 2007

       This module converts University of Oxford dates (Oxford academic dates) to and from Real World dates, and
       provides information on Terms of the University.

       The Terms of the University are defined by the Regulationsonthenumberandlengthsofterms, available
       online from

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

       This document describes the start and end dates of Oxford Terms.

       In addition to this, the dates of Full Term, required to calculate the week number of the term, are
       prescribed by Council, and published periodically in the UniversityGazette.

       Full term comprises weeks 1-8 inclusive, but sometimes, dates outside of full term are presented in the
       Oxford academic date format.  This module will optionally provide such dates.

       Data for these prescribed dates may be supplied in the file /etc/oxford-calendar.yaml; if this file does
       not exist, built-in data will be used. 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 the authoritative source, the Gazette, available online from

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

       <http://www.ox.ac.uk/news-and-events/The-University-Year> describes the academic year at Oxford.

       ToOx($day, $month, $year, [\%options])
          Given  a  day,  month and year in standard human format (that is, month is 1-12, not 0-11, and year is
          four digits) will return a string of the form

              Day, xth week, Term year

          or an array

              (Day, week of term, Term, year)

          depending on how it is called. 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. Therefore it is recommended to eval ToOx with appropriate error handling.

          %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)
          Given a year, month, term in standard human format (that is, month is 1-12, not 0-11, and year is four
          digits) will returns the current term or undef if in vacation or unknown. The  term  is  given  as  an
          array in the form (year, term).

       NextTerm($year, $month, $day)
          Given  a  day,  month and year in standard human format (that is, month is 1-12, not 0-11, and year is
          four digits) will return the next term (whether or not the date given is in term time).  The  term  is
          given as an array in the form (year, term).

       StatutoryTermDates($year)
          Returns  a  hash  reference  keyed on terms for a given year, the value of each being 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.

       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.

       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.

       Oxford::Calendar - University of Oxford calendar conversion routines

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