% Copyright 2006 by Till Tantau
%
% This file may be distributed and/or modified
%
% 1. under the LaTeX Project Public License and/or
% 2. under the GNU Free Documentation License.
%
% See the file doc/generic/pgf/licenses/LICENSE for more details.


\section{Date and Calendar Utility Macros}
\label{section-calendar}

This section describes the package |pgfcalendar|.

\begin{package}{pgfcalendar}
  This package can be used independently of \pgfname. It has two
  purposes:
  \begin{enumerate}
  \item It provides functions for working with dates. Most noticeably,
    it can convert a date in ISO-standard format (like 1975-12-26) to
    a so-called Julian day number, which is defined in Wikipedia as
    follows:  ``The Julian day or Julian day number is the
    (integer) number of days that have elapsed since the initial epoch
    at noon Universal Time (UT) Monday, January 1, 4713 BC in the
    proleptic Julian calendar.'' The package also provides a function
    for converting a Julian day number to an ISO-format date.

    Julian day numbers make it very easy to work with days. For
    example, the date ten days in the future of 2008-02-20 can
    be computed by converting this date to a Julian day number, adding
    10, and then converting it back. Also, the day of week of a given
    date can be computed by taking the Julian day number modulo~7.
  \item It provides a macro for typesetting a calendar. This macro
    is highly configurable and flexible (for example, it can produce
    both plain text calendars and also complicated \tikzname-based
    calendars), but most users will not use the macro directly. It is
    the job of a frontend to provide useful configurations for
    typesetting calendars based on this command.
  \end{enumerate}
\end{package}


\subsection{Handling Dates}

\subsubsection{Conversions Between Date Types}

\begin{command}{\pgfcalendardatetojulian\marg{date}\marg{counter}}
  This macro converts a date in a format to be described in a moment
  to the Julian day number in the Gregorian calendar. The \meta{date}
  should expand to a string of the following form:
  \begin{enumerate}\label{calendar-date-format}
  \item It should start with a number representing the year. Use
    |\year| for the current year, that is, the year the file is being
    typeset.
  \item The year must be followed by a hyphen.
  \item Next should come a number representing the month. Use |\month|
    for the current month. You can, but need not, use leading
    zeros. For example, |02| represents February, just like |2|.
  \item The month must also be followed by a hyphen.
  \item Next you must either provide a day of month (again, a number
    and, again, |\day| yields the current day of month) or the keyword
    |last|. This keyword refers to the last day of the month, which is
    automatically computed (and which is a bit tricky to compute,
    especially for February).
  \item Optionally, you can next provide a plus sign followed by
    positive or negative number. This number of days will be added to
    the computed date.
  \end{enumerate}

  Here are some examples:
  \begin{itemize}
  \item |2006-01-01| refers to the first day of 2006.
  \item |2006-02-last| refers to February 28, 2006.
  \item |\year-\month-\day| refers to today.
  \item |2006-01-01+2| refers to January 3, 2006.
  \item |\year-\month-\day+1| refers to tomorrow.
  \item |\year-\month-\day+-1| refers to yesterday.
  \end{itemize}

  The conversion method is taken from the English Wikipedia entry on
  Julian days.

  \newcount\mycount
  \example |\pgfcalendardatetojulian{2007-01-14}{\mycount}| sets
  |\mycount| to
  \pgfcalendardatetojulian{2007-01-14}{\mycount}\the\mycount.


\end{command}

\begin{command}{\pgfcalendarjuliantodate\marg{Julian day}\marg{year
      macro}\marg{month macro}\marg{day macro}}
  This command converts a Julian day number to an ISO-date. The
  \meta{Julian day} must be a number or \TeX\ counter, the \meta{year macro},
  \meta{month macro} and \meta{day macro} must be \TeX\ macro
  names. They will be set to numbers representing the year, month, and
  day of the given Julian day in the Gregorian calendar.

  The \meta{year macro} will be assigned the year without leading
  zeros. Note that this macro will produce year 0 (as opposed to other
  calendars, where year 0 does not exist). However, if you really need
  calendars for before the year 1, it is expected that you know what
  you are doing anyway.

  The \meta{month macro} gets assigned a two-digit number representing
  the month (with a leading zero, if necessary). Thus, the macro is
  set to |01| for January.

  The \meta{day macro} gets assigned a two-digit number representing
  the day of the month (again with a possible leading zero).

  To convert a Julian day number to an ISO-date you use code like the
  following:
\begin{verbatim}
\pgfcalendardatetojulian{2454115}{\myyear}{\mymonth}{\myday}
\edef\isodate{\myyear-\mymonth-\myday}
\end{verbatim}
  The above code sets |\isodate| to
  \pgfcalendarjuliantodate{2454115}{\myyear}{\mymonth}{\myday}%
  \edef\isodate{\myyear-\mymonth-\myday}\texttt{\isodate}.
\end{command}


\begin{command}{\pgfcalendarjuliantoweekday\marg{Julian day}\marg{week day counter}}
  This command converts a Julian day to a week day by computing the
  day modulo 7. The \meta{week day counter} must be a \TeX\
  counter. It will be set to 0 for a Monday, to 1 for a Tuesday, and
  so on.

  \example |\pgfcalendarjuliantoweekday{2454115}{\mycount}| sets
  |\mycount| to
  \pgfcalendarjuliantoweekday{2454115}{\mycount}\the\mycount.
\end{command}


\subsubsection{Checking Dates}


\begin{command}{\pgfcalendarifdate\marg{date}\marg{tests}\marg{code}\marg{else code}}
  \label{pgfcalendarifdate}
  This command is used to execute code based on properties of
  \meta{date}. The \meta{date} must be a date in ISO-format. For
  this date, the \meta{tests} are checked (to be detailed later)
  and if one of the tests applied, the \meta{code} is
  executed. If none of the tests applies, the \meta{else code} is
  executed.

  \example |\pgfcalendarifdate{2007-02-07}{Wednesday}{Is a Wednesday}{Is not a Wednesday}|
  yields \texttt{\pgfcalendarifdate{2007-02-07}{Wednesday}{Is a
      Wednesday}{Is not a Wednesday}}.

  The \meta{tests} is a comma-separated list of key-value
  pairs. The following are defined by default:
  \begin{itemize}
  \itemcalendaroption{all} This test is passed by all dates.
  \itemcalendaroption{Monday} This test is passed by all dates that
  are Mondays.
  \itemcalendaroption{Tuesday} as above.
  \itemcalendaroption{Wednesday} as above.
  \itemcalendaroption{Thursday} as above.
  \itemcalendaroption{Friday} as above.
  \itemcalendaroption{Saturday} as above.
  \itemcalendaroption{Sunday} as above.
  \itemcalendaroption{workday} Passed by Mondays, Tuesdays,
  Wednesdays, Thursdays, and Fridays.
  \itemcalendaroption{weekend} Passed Saturdays and Sundays.
  \itemcalendaroption{equals}|=|\meta{reference} The \meta{reference}
  can be in one of two forms: Either, it is a full ISO format date
  like |2007-01-01| or the year may be missing as in |12-31|. In the
  first case, the test is passed if \meta{date} is the same as
  \meta{reference}. In the second case, the test is passed if the
  month and day part of \meta{date} is the same as \meta{reference}.

  For example, the test |equals=2007-01-10| will only be passed by this
  particular date. The test |equals=05-01| will be passed by every first
  of May on any year.
  \itemcalendaroption{at least}|=|\meta{reference} This test works
  similarly to the |equals| test, only it is checked whether
  \meta{date} is equal to \meta{reference} or to any later
  date. Again, the \meta{reference} can be a full date like
  |2007-01-01| or a short version like |07-01|. For example,
  |at least=07-01| is true for every day in the second half of any
  year.
  \itemcalendaroption{at most}|=|\meta{reference} as above.
  \itemcalendaroption{between}|=|\meta{start reference}| and |\meta{end
    reference} This test checks whether the current date lies between
  the two given reference dates. Both full and short version may be
  given.

  For example |between=2007-01-01 and 2007-02-28| is true for the days
  in January and February of 2007.

  For another example, |between=05-01 and 05-07| is true for the
  days of the first week of May of any year.
  \itemcalendaroption{day of month}|=|\meta{number} Passed by the day
  of month of the \meta{date} is \meta{number}. For example, the test
  |day of month=1| is passed by every first of every month.
  \itemcalendaroption{end of month}\opt{|=|\meta{number}} Passed by
  the day of month of the \meta{date} that is \meta{number} from the
  end of the month. For example, the test |end of month=1| is passed
  by the last day of every month, the test |end of month=2| is passed
  by the second last day of every month. If \meta{number} is omitted,
  it is assumed to be |1|.
  \end{itemize}

  In addition to the above checks, you can also define new checks. To
  do so, you must add a new key to the key-value group |pgfcalendar|
  using |\define@key|. The job of the code of this new key is to
  possibly set the \TeX-if |\ifpgfcalendarmatches| to true (if it is
  already true, no action should be taken) to indicate that the
  \meta{date} passes the test setup by this new key.

  In order to perform the test, the key code needs to know the date
  that should be checked. The date is available through a macro, but a
  whole bunch of additional information about this date is also
  available through the following macros:
  \begin{itemize}
  \item |\pgfcalendarifdatejulian|
    is the Julian day number of the \meta{date} to be checked.
  \item |\pgfcalendarifdateweekday|
    is the weekday of the \meta{date} to be checked.
  \item |\pgfcalendarifdateyear|
    is the year of the \meta{date} to be checked.
  \item |\pgfcalendarifdatemonth|
    is the month of the \meta{date} to be checked.
  \item |\pgfcalendarifdateday|
    is the day of month of the \meta{date} to be checked.
  \end{itemize}

  For example, let us define a new key that checks whether the
  \meta{date} is a Workers day (first of May). This can be done as
  follows:
\begin{verbatim}
\define@key{pgfcalendar}{workers day}[]
{
  \ifnum\pgfcalendarifdatemonth=5\relax
    \ifnum\pgfcalendarifdateday=1\relax
      \pgfcalendarmatchestrue
    \fi
  \fi
}
\end{verbatim}
\end{command}


\subsubsection{Typesetting Dates}




\begin{command}{\pgfcalendarweekdayname\marg{week day number}}
  This command expands to a textual representation of the day of week,
  given by the \meta{week day number}. Thus,
  |\pgfcalendarweekdayname{0}| expands to |Monday| if the current
  language is English and to |Montag| if the current language is
  German, and so on. See Section~\ref{section-calendar-locale} for
  more details on translations.

  \example |\pgfcalendarweekdayname{2}| yields
  \texttt{\pgfcalendarweekdayname{2}}.
\end{command}


\begin{command}{\pgfcalendarweekdayshortname\marg{week day number}}
  This command works similarly to the previous command, only an
  abbreviated version of the week day is produced.

  \example |\pgfcalendarweekdayshortname{2}| yields
  \texttt{\pgfcalendarweekdayshortname{2}}.
\end{command}


\begin{command}{\pgfcalendarmonthname\marg{month number}}
  This command expands to a textual representation of the month, which
  is given by the \meta{month number}.

  \example |\pgfcalendarmonthname{12}| yields
  \texttt{\pgfcalendarmonthname{12}}.
\end{command}


\begin{command}{\pgfcalendarmonthshortname\marg{month number}}
  As above, only an abbreviated version is produced.

  \example |\pgfcalendarmonthshortname{12}| yields
  \texttt{\pgfcalendarmonthshortname{12}}.
\end{command}



\subsubsection{Localization}

\label{section-calendar-locale}
All textual representations of week days or months (like ``Monday'' or
``February'') are wrapped with |\translate| commands from the
|translator| package (it this package is not loaded, no translation
takes place). Furthermore, the |pgfcalendar| package will try to load
the |translator-months-dictionary|, if the |translator| package is
loaded.

The net effect of all this is that all dates will be translated to the
current language setup in the |translator| package. See the
documentation of this package for more details.



\subsection{Typesetting Calendars}

\begin{command}{\pgfcalendar\marg{prefix}\marg{start date}\marg{end
      date}\marg{rendering code}}
  This command can be used to typeset a calendar. It is a very general
  command, the actual work has to be done by giving clever
  implementations of \meta{rendering code}. Note that this macro need
  \emph{not} be called inside a |{pgfpicture}| environment (even
  though it typically will be) and you can use it to typeset calendars
  in normal \TeX\ or using packages other than \pgfname.

  \medskip
  \textbf{Basic typesetting process.}
  A calendar is typeset as follows: The \meta{start date} and
  \meta{end date} specify a range of dates. For each date in this
  range the \meta{rendering code} is executed with certain macros
  setup to yield information about the \emph{current date}
  (the current date in the enumeration of dates of the
  range). Typically, the \meta{rendering code} places nodes inside a
  picture, but it can do other things as well. Note that it is also
  the job of the \meta{rendering code} to position the calendar
  correctly.

  The different calls of the \meta{rending code} are not
  surrounded by \TeX\ groups (though you can do so yourself, of
  course). This means that settings can accumulate between different
  calls, which is often desirable and useful.

  \medskip
  \textbf{Information about the current date.}
  Inside the \meta{rendering code}, different macros can be access:

  \begin{itemize}
  \item |\pgfcalendarprefix|
    The \meta{prefix} parameter. This prefix is recommended for nodes
    inside the calendar, but you have to use it yourself explicitly.
  \item |\pgfcalendarbeginiso|
    The \meta{start date} of range being typeset in ISO format (like 2006-01-10).
  \item |\pgfcalendarbeginjulian|
    Julian day number of \meta{start date}.
  \item |\pgfcalendarendiso|
    The \meta{end date} of range being typeset in ISO format.
  \item |\pgfcalendarendjulian|
    Julian day number of \meta{end date}.
  \item |\pgfcalendarcurrentjulian| This \TeX\ count holds the
    Julian day number of day currently begin rendered.
  \item |\pgfcalendarcurrentweekday| The weekday
    (a number with zero representing Monday) of the current date.
  \item |\pgfcalendarcurrentyear| The year of the current date.
  \item |\pgfcalendarcurrentmonth| The month of the current date
    (always two digits with a leading zero, if necessary).
  \item |\pgfcalendarcurrentday| The day of month of the current date
    (always two digits).
  \end{itemize}

  \medskip
  {\bfseries The |\ifdate| command.}
  Inside the |\pgfcalendar| the macro |\ifdate| is available
  locally:
  \begin{command}{\ifdate\marg{tests}\marg{code}\marg{else code}}
    \label{ifdate}%
    This command has the same effect as calling |\pgfcalendarifdate|
    for the current date.
  \end{command}

  \medskip
  \textbf{Examples.}
  In a first example, let us create a very simple calendar: It just
  lists the dates in a certain range.
\begin{codeexample}[vbox,ignorespaces]
\pgfcalendar{cal}{2007-01-20}{2007-02-10}{\pgfcalendarcurrentday\ }
\end{codeexample}
  Let us now make this a little more interesting: Let us add a line
  break after each Sunday.
\begin{codeexample}[vbox,ignorespaces]
\pgfcalendar{cal}{2007-01-20}{2007-02-10}
{
  \pgfcalendarcurrentday\
  \ifdate{Sunday}{\par}{}
}
\end{codeexample}
  We now want to have all Mondays to be aligned on a column. For this,
  different approaches work. Here is one based positioning each day
  horizontally using a skip.
\begin{codeexample}[vbox,ignorespaces]
\pgfcalendar{cal}{2007-01-20}{2007-02-10}
{%
  \leavevmode%
  \hbox to0pt{\hskip\pgfcalendarcurrentweekday cm\pgfcalendarcurrentday\hss}%
  \ifdate{Sunday}{\par}{}%
}
\end{codeexample}
  Let us now typeset two complete months.
\begin{codeexample}[vbox,ignorespaces]
\pgfcalendar{cal}{2007-01-01}{2007-02-28}{%
  \ifdate{day of month=1}{
    \par\bigskip\hbox to7.5cm{\itshape\hss\pgfcalendarshorthand mt\hss}\par
  }{}%
  \leavevmode%
  {%
    \ifdate{weekend}{\color{black!50}}{\color{black}}%
    \hbox to0pt{%
      \hskip\pgfcalendarcurrentweekday cm%
      \hbox to1cm{\hss\pgfcalendarshorthand d-}\hss%
    }%
  }%
  \ifdate{Sunday}{\par}{}%
}
\end{codeexample}
  For our final example, we use a |{tikzpicture}|.
\begin{codeexample}[vbox,ignorespaces]
\begin{tikzpicture}
  \pgfcalendar{cal}{2007-01-20}{2007-02-10}{%
    \ifdate{workday}
      {\tikzset{filling/.style={fill=blue!20}}}
      {\tikzset{filling/.style={fill=red!20}}}
    \node (\pgfcalendarsuggestedname) at (\pgfcalendarcurrentweekday,0)
      [anchor=base,circle,filling] {\pgfcalendarcurrentday};
    \ifdate{Sunday}{\pgftransformyshift{-3em}}{}%
  }
  \draw (cal-2007-01-21) -- (cal-2007-02-03);
\end{tikzpicture}
\end{codeexample}
\end{command}


\begin{command}{\pgfcalendarshorthand\marg{kind}\marg{representation}}
  \label{pgfcalendarshorthand}
  This command can be used inside a |\pgfcalendar|, where it will
  expand to a representation of the current day, month, year or day of
  week, depending on whether \meta{kind} is |d|, |m|, |y| or |w|. The
  \meta{representation} can be one of the following: |-|, |=|, |0|,
  |.|, and |t|. They have the following meanings:
  \begin{itemize}
  \item The minus sign selects the shortest numerical representation
    possible (no leading zeros).
  \item The equal sign also selects the shortest numerical
    representation, but a space is added to single digit days and
    months (thereby ensuring that they have the same length as other
    days).
  \item The zero digit selects a two-digit numerical representation
    for days and months. For years it is allowed, but has no effect.
  \item The letter |t| selects a textual representation.
  \item The dot selects an abbreviated textual representation.
  \end{itemize}
  Normally, you should say |\let\%=\pgfcalendarshorthand| locally, so
  that you can write |\%wt| instead of the much more cumbersome
  |\pgfcalendarshorthand{w}{t}|.

\begin{codeexample}[leave comments]
\let\%=\pgfcalendarshorthand
\pgfcalendar{cal}{2007-01-20}{2007-01-20}
{ ISO form: \%y0-\%m0-\%d0, long form: \%wt, \%mt \%d-, \%y0}
\end{codeexample}
\end{command}


\begin{command}{\pgfcalendarsuggestedname}
  This macro expands to a suggested name for nodes representing days
  in a calendar. If the \meta{prefix} is empty, it expands to the
  empty string, otherwise it expands to the \meta{prefix} of the
  calendar, followed by a hyphen, followed by the ISO format version
  of the date. Thus, when the date |2007-01-01| is typeset in a
  calendar for the prefix |mycal|, the macro expands to
  |mycal-2007-01-01|.
\end{command}