Enter your search terms Submit search form
	Web pdp-10.trailing-edge.com

Documentation for Date/Time Parser found on <LISPUSERS>DATETIME.COM

In general, the parser (via the function PARSEDATETIME will either a
string or a list of tokens, try to understand it as a date and/or time
and return one of the type records DATETIME, MULTIPLEDATETIMES,
DURATION, QUALIFIEDDATETIME, or DATETIMEERROR which will describe the
date/time parsed.  Hopefully, the parser will be able to handle any
date/time expression one is likely to use ranging from a simple
date/time ("tomorrow", "noon", "thursday", "9-3-78", etc.), a cyclic
date/time ("every thursday"), durations ("between now and next week"),
and qualified date/times ("before next month").  It can also handle
some rather baroque combinations of these forms such as "the third
tuesday in the the second month after the fourth of July".  If you
come accross any date/time expression which you think is useful, but
which the parse cannot handle please let me know, and I'll try to
expand the parser in a reasonable way to handle it.  There is a
simplified BNF description of the types of expressions which the
parser can handle at the end of this file, but if you have to work
hard to put your date/time into that form, then the parser isnt
general enough and we should look at what extensions are needed.

Date Structures for dates:

The parser will return the date/time as one of four typerecords,
DATETIME, DURATION, MULTIPLEDATETIMES, and QUALIFIEDDATETIME.  The
typerecord DATETIME indicates that a precise date/time was found and
contains the fields, YEAR (normalize to a small number by subtracting
1900), MONTH, DAYOFMONTH, DAYOFWEEK, HOUR (normalized between 0 and
11), MINUTE, and AMORPM.  All of these except AMORPM is return as an
integer in some appropriate range.  AMORPM indicates whether the hour
is in the morning or in the evening with the possible values of AM and
PM.  Some of the slots in a DATETIME record may be NIL if they could
not be deduced from the input string.  An incomplete DATETIME can be
completed with the function FINISHDATETIME which takes a DATETIME as
an argument and returns an equivalent DATETIME with all slots filled.
However, the defaults for various slots may vary with the application,
so the parser will not fill these slots on its own.

The DURATION typerecord has two fields, STARTDATETIME and ENDDATETIME,
each with the obvious meanings.

A QUALIFIEDDATETIME also has two slots, QUALIFIER and DATETIME.  The
DATETIME slot is the DATETIME be qualified and the QUALIFIER may have
any of the values, BEFORE, AFTER, or AROUND.

The MULTIPLEDATETIMES is the record returned when the parser discovers
a date that it understands to happen repeatedly, such as "every
Christmas" and "every Tuesday".  It doesnt return a DATETIME record
specifying a precised time, but does return the appropriate functions
for 1) testing whether or not a DATETIME is an occurence of this
MULTIPLEDATETIME and 2) generating various (useful) instances of this
MULTIPLEDATETIME.  The fields of a MULTIPLEDATETIME are OCCURENCEPRED,
ADVANCEFN, DECREMENTFN, NEXTFROMDATEFN, and PRINTSTRING.
OCCURENCEPRED is an expression which, when evaled, tests to see if the
DATETIME bound to the variable DATUM is an occurence of this
MUTLIPLEDATETIME.  ADVANCEFN is an expression which, when evaled,
takes a DATETIME (again bound to the variable DATUM) which is assumed
to be an occurence of these MULTIPlEDATETIME, and return the next
future occurence of this MULTIPLEDATETIME.  DECREMENTFN is analogous
to ADVANCEFN but returns the next last occurence in the past rather
than the next occurence in the future.  NEXTFROMDATEFN is an
expression which, when evaled, takes the DATETIME bound to the
variable DATUM which is not assumed to to be an occurence of this
MUTLIPLEDATETIME, and returns the first occurence of this
MULTIPLEDATETIME after DATUM.  Finally, PRINTSTRING contains a string
specifying how this MULTIPLEDATETIME should be printed.

There is another type of record which the parser may return called the
DATETIMEERROR.  A record of this type is returned if the parser can
not handle the expression and the global variable DATETIMEERRORFLG is
NIL.  The relevent fields of this record are ERRORNUMBER,
ERRORMESSAGE, ORIGINALTOKENLST, and CURRENTTOKENLST.  The
ORIGINALTOKENLST is the list of tokens that the input was originally
expanded to, and the CURRENTTOKENLST is what was left of the tokenlst
when the error occured.


User Functions

The following is a list of functions available to the user of the
date/time parser.

ADVANCEDATE[DATETIME,DAYS]

        -  Returns a datetime record structure which is the same
           type as DATETIME but which has been advanced DAYS number
           of days.  If DAYS is NIL, it is assumed to be 1.  DAYS
           may also be one of the key words, DAY, WEEK, MONTH,
           YEAR, in which cause, the construct returned is the
           advanced the corresponding amount.  There are also
           options for advancing the DATETIME combinations and
           multiples of these units which I'll write up in more
           detail later.

DATETIMETOSTRING[DATETIME]

        -  Takes an instance of any of the above records and
           returns a string describing that record (the opposite of
           the parser.)

DEQUALP[DATETIME1,DATETIME2,RESOLUTION]

        -  Test to see if the two DATETIME records specify the same
           date and time to the granularity of RESOLUTION.  Both
           DATETIMEs must be an instance of the DATETIME record,
           and RESOLUTION may be 1)YEAR, 2) MONTH, 3) DAYOFMONTH,
           4) HOUR, 5) MINUTE, or 6) NIL (equivalent to MINUTE.)
           If DEQUALP needs a slot for one of the DATETIMEs which
           is NIL, then it will return INCOMPARABLE rather than T
           or NIL.

DLESSP[DATETIME1,DATETIME2,RESOLUTION]

        -  Analogous to DEQUALP but tests if DATETIME1 is before
           DATETIME2.

EVALMDTFN[MDT,FN,DATUM]

        -  Takes the MULTIPLEDATETIME, MDT, and evals its
           functional field, specified by FN, while binding the
           third argument to DATUM for that evaluation.

FINISHDATETIME[DATETIME]

        -  Returns a DATETIME record equalivent to DATETIME with
           all fields filled.

LISTDATES[DATETIME1,DATETIME2]

        -  Returns a list of the dates (as DATETIMEs) between
           DATETIME1 and DATETIME2 (inclusive).  The list will be
           at most ten elements long, possibly excluding some of
           the later dates.  Note that the hour and minute fields
           of the arguments are totally ingored for the purposes of
           this function.  If DATETIME2 is NIL then the first ten
           days after DATETIME1 are returned.  If DATETIME1 is a
           duration or a multipledatetimem then the list is of
           dates specified by those constructs and DATETIME2 is
           ignored.

PARSEDATETIME[TOKENLST]

        -  Takes either a string or a list of tokens and attempts
           to parse is as a date/time, returning on of the four
           records described earlier.  If the parse fails for any
           reason and the global variable DATETIMEERRORFLG is T,
           then an error will be generated.  Otherwise special
           record of type DATETIMEERROR will be returned.

RESTATE[INPUT]

        -  Simply a call to PARSEDATETIME followed by a call to
           DATETIMETOSTRING.  Useful in seeing whether or not the
           parser can handle some given input, without having to
           look at the final output structure to see what it
           produced.


Synonyms

The parser attempts to do a limited amount of spelling correction and
accepts a great number of synonyms in the input string.  Most
abbreviations are accepted, and numbers spelled out in English are
accepted (E.g.  "twenty five" and "the nineteenth").  Furthermore, the
following are accepted as synonyms to allow quick input.
	
	@		at
	~		about
	<		before
	>		after
	

BNF

The following represents a brief overview of the syntax which the
datetime parser can handle.  It is not complete and, instances, may
specify some syntax which is as yet unimplemented.  Most of the
phrases that can be accepted which are not listed here involve the use
of the synonyms which (see earlier documentation.)  Thus "the fourth
day of next month" is equivalent to "the 4 th day in next month".  The
phrases which are not implemented, but are described by the syntax
below are things that simply didnt make sense to me, so if you run
accross something that makes sense to you, but which the parser cant
handle, let me know.

<simple time> ::= {at} <num> {: <num>} {oclock} {am | pm}

<simple date> ::= {on} ((<monthname> {-} <num>) |
			(<num> {-} <num>) |
			(<num> {- | ,} <monthname>))
				{- | ,} {<num>}

<qualified datetime> ::=
				(after <datetime> {and before <datetime>} |
				(before <datetime> {and after <datetime>}) |
				(about <datetime>) |
				(between <datetime> and <datetime>)

<offsetdatetime> ::= ({<num> th} {<datetimeunit> | <weekday>}
			(of | before | after) <datetime>) |
			(<num> <datetimeunit> (before | after) <datetime>)

<datetimeunit> ::= minute | hour | day | month | week | year

<weekday> ::= sunday | monday | tuesday | wednesday | thursday |
				friday | saturday

<special datetime> ::= now | today | yesterday | noon | midnight |
			Sunday | Monday | Tuesday | Wednesday | Thursday |
			Friday | Saturday | Christmas | New Years Day |
			<weekday>

<datetime> ::= ({every | this | next | last}  <datetime1>) | 
			(<datetime1> {{,} week of <simple date>})

<datetime1> ::= <qualified datetime> | <simple date> | <simple time> |
			<special datetime> {{,} week of <simple date>}



Comments, suggestions, and gripes should be directed to LAASER.