.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Oxford::Calendar 3pm"
.TH Oxford::Calendar 3pm "2020-06-06" "perl v5.30.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Oxford::Calendar \- University of Oxford calendar conversion routines
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 4
\& use 5.10.0;
\& use Oxford::Calendar;
\& use Date::Calc;
\& say "Today is " . Oxford::Calendar::ToOx(reverse Date::Calc::Today);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module converts University of Oxford dates (Oxford academic dates)
to and from Real World dates, and provides information on Terms of the
University.
.PP
The Terms of the University are defined by the
\&\fBRegulations on the number and lengths of terms\fR, available online from
.PP
.PP
This document describes the start and end dates of Oxford Terms.
.PP
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 \fBUniversity Gazette\fR.
.PP
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.
.PP
Data for these prescribed dates may be supplied in the file
\&\fI/etc/oxford\-calendar.yaml\fR; 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
.PP
.
.PP
or the authoritative source, the Gazette, available online from
.PP
.
.PP
describes the academic year at Oxford.
.SH "DATE FORMAT"
.IX Header "DATE FORMAT"
An Oxford academic date has the following format:
.Sp
.RS 4
, [st,nd,rd,th] week,
.RE
.PP
where term name is one of
.IP "\(bu" 4
Michaelmas (autumn)
.IP "\(bu" 4
Hilary (spring)
.IP "\(bu" 4
Trinity (summer)
.PP
Example:
.PP
Friday, 8th Week, Michaelmas 2007
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.ie n .IP "ToOx($day, $month, $year, [\e%options])" 3
.el .IP "ToOx($day, \f(CW$month\fR, \f(CW$year\fR, [\e%options])" 3
.IX Item "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
.Sp
.Vb 1
\& Day, xth week, Term year
.Ve
.Sp
or an array
.Sp
.Vb 1
\& (Day, week of term, Term, year)
.Ve
.Sp
depending on how it is called. The exact behaviour is modified by the 'mode'
option described below.
.Sp
If the requested date is not in full term or extended term (see below),
undef will be returned.
.Sp
If the requested date is not covered by the database, ToOx will die with
an \*(L"out of range\*(R" error message. Therefore it is recommended to eval ToOx
with appropriate error handling.
.Sp
\&\f(CW%options\fR can contain additional named parameter options:
.RS 3
.IP "mode" 5
.IX Item "mode"
Several modes are available:
.RS 5
.IP "full_term" 6
.IX Item "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).
.IP "ext_term" 6
.IX Item "ext_term"
Term dates will only be returned if the date requested is part of an extended
term, or statutory term.
.IP "nearest" 6
.IX Item "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).
.Sp
This is currently the default behaviour, for backwards compatibility with
previous releases; this may be changed in future.
.RE
.RS 5
.RE
.RE
.RS 3
.IP "confirmed" 4
.IX Item "confirmed"
If true, ignores dates marked as provisional in the database.
.RE
.RS 3
.RE
.ie n .IP "ThisTerm($year, $month, $day)" 3
.el .IP "ThisTerm($year, \f(CW$month\fR, \f(CW$day\fR)" 3
.IX Item "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).
.ie n .IP "NextTerm($year, $month, $day)" 3
.el .IP "NextTerm($year, \f(CW$month\fR, \f(CW$day\fR)" 3
.IX Item "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).
.IP "StatutoryTermDates($year)" 3
.IX Item "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.
.Sp
Note: these are the statutory term dates, not full term dates.
.IP "Parse($string)" 3
.IX Item "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
\&\f(CW\*(C`($year,$term,$week,$day)\*(C'\fR.
.Sp
This function is experimental.
.ie n .IP "FromOx($year, $term, $week, $day)" 3
.el .IP "FromOx($year, \f(CW$term\fR, \f(CW$week\fR, \f(CW$day\fR)" 3
.IX Item "FromOx($year, $term, $week, $day)"
Converts an Oxford date into a Gregorian date, returning a string of the
form \f(CW\*(C`DD/MM/YYYY\*(C'\fR or undef.
.Sp
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').
.Sp
If the requested date is not covered by the database, FromOx will die with
an \*(L"out of range\*(R" error message. Therefore it is recommended to eval ToOx
with appropriate error handling.
.SH "BUGS"
.IX Header "BUGS"
Bugs may be browsed and submitted at
.PP
.PP
A copy of the maintainer's git repository may be found at
.PP
.SH "AUTHOR"
.IX Header "AUTHOR"
Simon Cozens is the original author of this module.
.PP
Eugene van der Pijll, \f(CW\*(C`pijll@cpan.org\*(C'\fR took over maintenance from
Simon for a time.
.PP
Dominic Hargreaves maintains this module (between 2008 and 2015 for
\&\s-1IT\s0 Services, University of Oxford).