The fuzzy-dates Reference Manual

This is the fuzzy-dates Reference Manual, version 1.0.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Wed May 15 05:17:19 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

The main system appears first, followed by any subsystem dependency.


2.1 fuzzy-dates

A library to fuzzily parse date strings

Maintainer

Yukari Hafner <>

Author

Yukari Hafner <>

Home Page

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

Source Control

(GIT https://github.com/shinmera/fuzzy-dates.git)

Bug Tracker

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

License

zlib

Version

1.0.0

Dependencies
  • cl-ppcre (system).
  • documentation-utils (system).
Source

fuzzy-dates.asd.

Child Components

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


3.1 Lisp


3.1.1 fuzzy-dates/fuzzy-dates.asd

Source

fuzzy-dates.asd.

Parent Component

fuzzy-dates (system).

ASDF Systems

fuzzy-dates.


3.1.2 fuzzy-dates/package.lisp

Source

fuzzy-dates.asd.

Parent Component

fuzzy-dates (system).

Packages

org.shirakumo.fuzzy-dates.


3.1.3 fuzzy-dates/fuzzy-dates.lisp

Dependency

package.lisp (file).

Source

fuzzy-dates.asd.

Parent Component

fuzzy-dates (system).

Public Interface
Internals

3.1.4 fuzzy-dates/documentation.lisp

Dependency

fuzzy-dates.lisp (file).

Source

fuzzy-dates.asd.

Parent Component

fuzzy-dates (system).


4 Packages

Packages are listed by definition order.


4.1 org.shirakumo.fuzzy-dates

Source

package.lisp.

Use List

common-lisp.

Public Interface
Internals

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


5.1 Public Interface


5.1.1 Ordinary functions

Function: decode-integer (i &optional errorp)

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

Package

org.shirakumo.fuzzy-dates.

Source

fuzzy-dates.lisp.

Function: decode-month (m &optional errorp)

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

Package

org.shirakumo.fuzzy-dates.

Source

fuzzy-dates.lisp.

Function: decode-timezone (tz &optional errorp)

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

Package

org.shirakumo.fuzzy-dates.

Source

fuzzy-dates.lisp.

Function: decode-unit (u &optional errorp)

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

Package

org.shirakumo.fuzzy-dates.

Source

fuzzy-dates.lisp.

Function: decode-weekday (w &optional errorp)

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

Package

org.shirakumo.fuzzy-dates.

Source

fuzzy-dates.lisp.

Function: parse (string &key now errorp)

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

Package

org.shirakumo.fuzzy-dates.

Source

fuzzy-dates.lisp.

Function: parse-backward-time (string &key now errorp)

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

Package

org.shirakumo.fuzzy-dates.

Source

fuzzy-dates.lisp.

Function: parse-forward-time (string &key now errorp)

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

Package

org.shirakumo.fuzzy-dates.

Source

fuzzy-dates.lisp.

Function: parse-iso8661-like (string &key now errorp)

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

Package

org.shirakumo.fuzzy-dates.

Source

fuzzy-dates.lisp.

Function: parse-reverse-like (string &key now errorp)

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

Package

org.shirakumo.fuzzy-dates.

Source

fuzzy-dates.lisp.

Function: parse-rfc1123-like (string &key now errorp)

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

Package

org.shirakumo.fuzzy-dates.

Source

fuzzy-dates.lisp.

Function: parse-rfc3339-like (string &key now errorp)

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

Package

org.shirakumo.fuzzy-dates.

Source

fuzzy-dates.lisp.

Function: parse-single (string &key now errorp)

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

Package

org.shirakumo.fuzzy-dates.

Source

fuzzy-dates.lisp.


5.2 Internals


5.2.1 Special variables

Special Variable: *tzdb*
Package

org.shirakumo.fuzzy-dates.

Source

fuzzy-dates.lisp.


5.2.2 Macros

Macro: define-parser (name (strvar &optional nowvar errorp) &body body)
Package

org.shirakumo.fuzzy-dates.

Source

fuzzy-dates.lisp.

Macro: with-integers-bound (vars (regex string) &body body)
Package

org.shirakumo.fuzzy-dates.

Source

fuzzy-dates.lisp.

Macro: with-scans (var &body cases)
Package

org.shirakumo.fuzzy-dates.

Source

fuzzy-dates.lisp.


5.2.3 Ordinary functions

Function: backfill-timestamp (y o d h m s tz &optional now)
Package

org.shirakumo.fuzzy-dates.

Source

fuzzy-dates.lisp.

Function: check-error (errorp string &optional default)
Package

org.shirakumo.fuzzy-dates.

Source

fuzzy-dates.lisp.

Function: parse-integer* (thing)
Package

org.shirakumo.fuzzy-dates.

Source

fuzzy-dates.lisp.

Function: parse-relative-time (string errorp)
Package

org.shirakumo.fuzzy-dates.

Source

fuzzy-dates.lisp.

Function: parse-timezone (string &key errorp)
Package

org.shirakumo.fuzzy-dates.

Source

fuzzy-dates.lisp.

Function: parse-tzdb (db)
Package

org.shirakumo.fuzzy-dates.

Source

fuzzy-dates.lisp.


Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   B   C   D   F   M   P   W  
Index Entry  Section

B
backfill-timestamp: Private ordinary functions

C
check-error: Private ordinary functions

D
decode-integer: Public ordinary functions
decode-month: Public ordinary functions
decode-timezone: Public ordinary functions
decode-unit: Public ordinary functions
decode-weekday: Public ordinary functions
define-parser: Private macros

F
Function, backfill-timestamp: Private ordinary functions
Function, check-error: Private ordinary functions
Function, decode-integer: Public ordinary functions
Function, decode-month: Public ordinary functions
Function, decode-timezone: Public ordinary functions
Function, decode-unit: Public ordinary functions
Function, decode-weekday: Public ordinary functions
Function, parse: Public ordinary functions
Function, parse-backward-time: Public ordinary functions
Function, parse-forward-time: Public ordinary functions
Function, parse-integer*: Private ordinary functions
Function, parse-iso8661-like: Public ordinary functions
Function, parse-relative-time: Private ordinary functions
Function, parse-reverse-like: Public ordinary functions
Function, parse-rfc1123-like: Public ordinary functions
Function, parse-rfc3339-like: Public ordinary functions
Function, parse-single: Public ordinary functions
Function, parse-timezone: Private ordinary functions
Function, parse-tzdb: Private ordinary functions

M
Macro, define-parser: Private macros
Macro, with-integers-bound: Private macros
Macro, with-scans: Private macros

P
parse: Public ordinary functions
parse-backward-time: Public ordinary functions
parse-forward-time: Public ordinary functions
parse-integer*: Private ordinary functions
parse-iso8661-like: Public ordinary functions
parse-relative-time: Private ordinary functions
parse-reverse-like: Public ordinary functions
parse-rfc1123-like: Public ordinary functions
parse-rfc3339-like: Public ordinary functions
parse-single: Public ordinary functions
parse-timezone: Private ordinary functions
parse-tzdb: Private ordinary functions

W
with-integers-bound: Private macros
with-scans: Private macros


A.3 Variables

Jump to:   *  
S  
Index Entry  Section

*
*tzdb*: Private special variables

S
Special Variable, *tzdb*: Private special variables