fuzzy dates

1.0.0

A library to fuzzily parse date strings

About Fuzzy-Dates

This is a small library to very fuzzily parse time and date strings into a universal-time timestamp. Among the fuzzily supported formats are:

Forwards and backwards relative stamps
Clocks
RFC1123
RFC3339
ISO8661
Weekdays and months
UNIX timestamps

In short, it should parse a lot of what you throw at it and give you a reasonable timestamp for it. Note that while this does make this parsing rather suitable for parsing human input, there's still ambiguities that cannot be resolved, such as whether the user thinks dates are YMD, DMY, or MDY, and the human mind's ingenuity in coming up with new ways to write dates and times can't all be accounted for, so there are definitely timestamps that we can understand, which this library won't be able to parse or will parse different to how we understand it.

System Information

Version: 1.0.0

Dependencies:

Author: Yukari Hafner

License: zlib

Homepage: https://shinmera.github.io/fuzzy-dates/

Bug Tracker: https://github.com/shinmera/fuzzy-dates/issues

Sources: https://github.com/shinmera/fuzzy-dates.git

Definition Index

ORG.SHIRAKUMO.FUZZY-DATES

No documentation provided.

EXTERNAL FUNCTION

DECODE-INTEGER

I
&OPTIONAL
ERRORP

Source

Parse an integer in digit or word format.

If ERRORP is true, failing to parse the month name will signal an
error. Otherwise NIL is returned.

The understood words go from one all the way up to trillion, though no
abbreviations are supported.

Examples:

  100
  one hundred
  twenty-two million three hundred two

EXTERNAL FUNCTION

DECODE-MONTH

M
&OPTIONAL
ERRORP

Source

Turn a month name into an integer between 1 and 12.

If ERRORP is true, failing to parse the month name will signal an
error. Otherwise NIL is returned.

See http://www.lispworks.com/documentation/HyperSpec/Body/25_ada.htm

Examples:

  ja
  feb
  march

EXTERNAL FUNCTION

DECODE-TIMEZONE

TZ
&OPTIONAL
ERRORP

Source

Turn a timezone name into a number of hours of UTC offset.

If ERRORP is true, failing to parse the month name will signal an
error. Otherwise NIL is returned.

See http://www.lispworks.com/documentation/HyperSpec/Body/25_ada.htm

Examples:

  Z
  GMT
  JST

EXTERNAL FUNCTION

DECODE-UNIT

U
&OPTIONAL
ERRORP

Source

Turn a unit name into a scaling factor relative to seconds.

If ERRORP is true, failing to parse the month name will signal an
error. Otherwise NIL is returned.

The supported time units go from nanoseconds to aeons and includes all
sorts of abbreviations for them.

See http://www.lispworks.com/documentation/HyperSpec/Body/25_ada.htm

Examples:

  ms
  sec
  y
  aeons

EXTERNAL FUNCTION

DECODE-WEEKDAY

W
&OPTIONAL
ERRORP

Source

Turn a weekday name into an integer between 0 and 6.

If ERRORP is true, failing to parse the month name will signal an
error. Otherwise NIL is returned.

See http://www.lispworks.com/documentation/HyperSpec/Body/25_ada.htm

Examples:

  mo
  tue
  thursday

EXTERNAL FUNCTION

PARSE

STRING
&KEY
NOW
ERRORP

Source

Fuzzily parse a time string into a universal-time timestamp.

If NOW is given it should be a universal-time timestamp that the
parsed timestring will be relative to. If not given, the current time
is used.

If ERRORP is true, failing to parse the string name will signal an
error. Otherwise NIL is returned. When an error is signalled, two
restarts will be active:

  USE-VALUE -- interactive, allows supplying a universal-time to use
  CONTINUE  -- simply returns the current universal-time timestamp

This also applies to all the sub-functions used.

See PARSE-FORWARD-TIME
See PARSE-BACKWARD-TIME
See PARSE-RFC3339-LIKE
See PARSE-ISO8661-LIKE
See PARSE-REVERSE-LIKE
See PARSE-RFC1123-LIKE
See PARSE-SINGLE

EXTERNAL FUNCTION

PARSE-BACKWARD-TIME

STRING
&KEY
NOW
ERRORP

Source

Parse a relative time for the past.

The basic syntax is:

  STAMP ::= (C U)(,? C U)* ago
  C     --- a positive integer
  U     --- a unit name

Examples:
  10 seconds ago
  6 years, 5 minutes ago
  thirty hours ago

If ERRORP is true, failing to parse the timestring will signal an
error. Otherwise NIL is returned.

If NOW is given it should be a universal-time timestamp that the
parsed timestring will be relative to. If not given, the current time
is used.

See DECODE-UNIT
See DECODE-INTEGER
See PARSE

EXTERNAL FUNCTION

PARSE-FORWARD-TIME

STRING
&KEY
NOW
ERRORP

Source

Parse a relative time for the future.

The basic syntax is:

  STAMP ::= in (C U)(,? C U)*
  C     --- a positive integer
  U     --- a unit name

Examples:

  in 10 seconds
  in 5 minutes, 10 years
  in five hours

If ERRORP is true, failing to parse the timestring will signal an
error. Otherwise NIL is returned.

If NOW is given it should be a universal-time timestamp that the
parsed timestring will be relative to. If not given, the current time
is used.

See DECODE-UNIT
See DECODE-INTEGER
See PARSE

EXTERNAL FUNCTION

PARSE-ISO8661-LIKE

STRING
&KEY
NOW
ERRORP

Source

Parse a timestamp that looks vaguely like an ISO8661 date.

This is very similar to the RFC3339 format, but instead follows the
compact format without separators between date and time formats.

A typical compact ISO8661 string has the following format:

  20230916T100615Z

This function is slightly more lenient and permits the following
separators between date and time parts:

  space dash t

It permits date and time parts to not be padded.

It also permits omitting the date and timezone parts of the
timestamp.

If ERRORP is true, failing to parse the timestring will signal an
error. Otherwise NIL is returned.

If NOW is given it should be a universal-time timestamp that the
parsed timestring will be relative to. If not given, the current time
is used.

See PARSE

EXTERNAL FUNCTION

PARSE-REVERSE-LIKE

STRING
&KEY
NOW
ERRORP

Source

Parse a timestamp that is "reverse" from the others

A typical reverse time string has the following format:

  10:18:03 16.9.2023

This function is more lenient, and makes the following fuzzy matches:
It permits the following separators between date parts:

  space comma period slash dash

It permits the following separators between date and time parts:

  space dash t

It permits the following separators between time parts:

  space period dash colon

It permits date and time parts to not be padded.

It also permits omitting the time and timezone parts of the
timestamp.

If ERRORP is true, failing to parse the timestring will signal an
error. Otherwise NIL is returned.

If NOW is given it should be a universal-time timestamp that the
parsed timestring will be relative to. If not given, the current time
is used.

See PARSE

EXTERNAL FUNCTION

PARSE-RFC1123-LIKE

STRING
&KEY
NOW
ERRORP

Source

Parse a timestamp that looks vaguely like an RFC1123 date.

A typical RFC1123 string has the following format:

  Thu, 23 Jul 2013 19:42:23 GMT

This function is more lenient, and makes the following fuzzy matches:
It permits the following separators between date parts:

  space comma period slash dash

It permits the following separators between date and time parts:

  space comma period slash dash t

It permits the following separators between time parts:

  space period dash colon

It permits date and time parts to not be padded.

It also permits omitting the day of week, time, and timezone parts of
the timestamp.

If ERRORP is true, failing to parse the timestring will signal an
error. Otherwise NIL is returned.

If NOW is given it should be a universal-time timestamp that the
parsed timestring will be relative to. If not given, the current time
is used.

See PARSE

EXTERNAL FUNCTION

PARSE-RFC3339-LIKE

STRING
&KEY
NOW
ERRORP

Source

Parse a timestamp that looks vaguely like an RFC3339 date.

A typical RFC3339 string has the following format:

  2023-09-16T10:06:15.00-05:00

This function is more lenient, and makes the following fuzzy matches:
It permits the following separators between date parts:

  space comma period slash dash

It permits the following separators between date and time parts:

  space dash t

It permits the following separators between time parts:

  space period dash colon

It permits date and time parts to not be padded.

It also permits omitting the date and timezone parts of the
timestamp.

If ERRORP is true, failing to parse the timestring will signal an
error. Otherwise NIL is returned.

If NOW is given it should be a universal-time timestamp that the
parsed timestring will be relative to. If not given, the current time
is used.

See PARSE

EXTERNAL FUNCTION

PARSE-SINGLE

STRING
&KEY
NOW
ERRORP

Source

Parse a single token.

If it's an integer, it can denote either:

  seconds in the future, if below 1000
  a year, if below 5000
  a UNIX timestamp

If it's a word, it can denote either:

  a day of the week, pushed to the next week if the current day is
  already past.
  a month, pushed to the next year if the current month is already
  past.

Examples:

  10
  1900
  mon
  march

If ERRORP is true, failing to parse the timestring will signal an
error. Otherwise NIL is returned.

If NOW is given it should be a universal-time timestamp that the
parsed timestring will be relative to. If not given, the current time
is used.

See PARSE