User’s Guide to the Dates package^{∗}

Frank G. Bennett, Jr.^{†}

January 24, 1998

Abstract

This package provides macros for the parsing of dates using L^{A}TEX 2ε.

1 Introduction

This package provides a macro, \dateread, that can be used to parse date strings, either individually or recursively. The macro expects a human-readable syntax, which it converts into an integer (a “long date”) that can be more easily used for some types of computation. A set of companion macros and token registers is also provided for converting long dates into human-readable form.

Dates may be specified either individually, or as recursive dates within a range. The human-readable syntax for two types of recursive date are built into the package, but an interface for writing specialized extensions in native L^{A}TEX is also provided. The handling of parsed dates is also within user control; it is defined in a single argument fed to \dateread when it is invoked in front of a list of dates.

This package was developed as one of the building blocks of the calendar package, but is released as a separate chunk of code because the date parsing task is a function discrete from the work of building a calendar from constituent blocks of information (which is the main task of the Calendar package proper).

For a description of the syntax understood by the parser, and examples of how it can be extended, please see the Calendar package and the documentation for its associated style files. The documentation here is not intended for end users; it is provided for reference by style designers who might wish to use the parser in their own packages.

2 Calling the Parser

Printing of variable text (such as the text of the date) is done by passing that information through to the argument to the \dateread macro. This argument is an action that will be performed once after each date in the list is read. The date and the description text may be included by using the appropriate commands. These are:

∗This file is version number 3.1. It was last revised on 1998/01/17 17:12:39.

†The code contained in this file just provides a smart L^{A}TEX 2εfront end to the calendar macros for TEX that I found on CTAN. The TEX macros work quite well, but lack any documentation. Their provenance is also a mystery. If anyone can tell me who wrote them, I will gladly include an acknowledgement in this documentation.

\theyear  The year (four digits).
\themonth  The full name of the month.
\theshortmonth  The name of the month (3 characters).
\themonthnumber The number of the month.
\theday  The day of the month.
\thetimestart  Starting time for an item.
\thetimeend  Ending time for an item.
\theweekday  The name of the day of the week.
\theshortweekday Abbreviated day of the week (3 characters).
\theshorttext  The text describing the date.
\thelongtext  A longer description of the date.
\thelongdate  The long date (an integer).
\thedays  The maximum number of days this month.

You can also call up information using lower-level registers and macros that contain date-related information. If you need to do this, you’re on your own; please have a look at the code.

The demonstration file included in this package lists dates on the terminal using the \message command. In a more serious application, text can be printed, stored to registers or boxes, or sent in pre-processed form to an external file.

The following is a valid invocation of the macro:

  \dateread{%
    \message{%
      \theweekday, %
      \theday\space%
      \themonthname\space%
      \theyear}}
  %
  % The list of dates to be parsed
  %
  June 15 1997 {Summer Holiday Begins}
  September 25 1997 {Summer Holiday Ends}
  January 1 1997 {First day of January}
  February 18 1997 {Frank's Birthday}
  Every Monday at 2:00 {Go to the Beach}
  Every 20 {20th day of the month}
  %
  % The end of the list.
  %
  \relax{}

A style package that uses the date parser should of course conceal stretches of code like that above from the end user. If lists of dates are maintained in separate files, you can do something like the following,

      \def\readinput{%
        \dateread{\message{\theweekday^^J}}}
      \def\inputandread{%
        \expandafter\readinput%
          \@@input \filename\relax{}
        }

where \filename contains the name of a file to be read. One would confirm the existence of the file, then run \inputandread.

3 Extending the Parser

When the parser is used in a package, it may be necessary to modify its behaviour to perform special actions in the course of processing. For example, you may want to provide a facility for setting the range in files containing recursive dates from a single file so that, say, an academic schedule can be moved forward to the next year without a lot of typing. This kind of effect can be achieved by defining a word which diverts processing to a macro that performs the desired action before continuing to digest the list of dates.

The flow of processing can be diverted at two points:

1. Immediately after a word is read; or

2. Immediately after a date and its text have been digested.

The parser can be re-entered in any of three states:

1. One that looks for the next word in a date string;

2. One that digests the description text; or

3. One that completes the processing of a date entry and its text.

Each of the exit points and reentry states is associated with a macro name. Diversion is accomplished by defining a word that \lets the exit macro name be the user’s own macro. Reentry is accomplished in the user’s macro by ending with the appropriate macro name. The names the macros to use as exit points are, in the order of the first list above:

  1. \dates@@@read
  2. \dates@read@exit

The names of macros to use for reentry states are:

  1. \dates@@@read@default

  2. \dates@@@@read@default
  3. \dates@read@exit@default

An extension therefore consists of a user-defined macro, and a user-defined word that invokes \let as appropriate. Words should be padded to exactly three characters using X, and should be appended with the suffix mac. The following defines a word, if, which sets a toggle and continues parsing a date:

      \newif\ifusedif
      \def\myownmacro{%
        \usediftrue%
        \dates@@@read@default}
      \def\ifXmac{%
        \let\dates@@@read=\myownmacro}

This is the same method used in the package itself to provide recursive dates and the function entry type; see the code commentary section for less trivial examples.

3.1 Using the Argument Text

When dates are read they are unsorted, so text should not be exported directly by \dates@action (let alone dropped on DVI) unless you have a filter for sorting the text after TEX exits. In normal use, events should be sorted and selected in memory after they are read, by other code in the package calling dates.sty. The Calendar package is an example of how this can be done.