# fdate
This library addresses the challenge of interpreting relative dates from everyday
language, specifically designed for straightforward use cases commonly found in scheduling
and journaling contexts.
# Examples
## Absolute
While focused on relative dates, the library still supports absolute date parsing. These
do not account for today’s date.
- 2000-04-15
- 15(th) April 2000
- April 15(th) 00
- 4/15/2000
## Relative
Relative queries depend on today's date, yet there are several different logic paths to
follow from there.
### Intervals
This syntax allows for the addition or subtraction of a specific number of days from
today's date. In the case of month intervals, the library attempts to preserve the
calendar day where possible. If the day does not fit (e.g., moving one month away from
the 31st of the current month), it will default to the greatest day that fits into the
resulting month. This ensures it won't overflow into the following month or skip ahead by
two months.
Interval counts may be written either as digits or as words from `zero` to `twenty`.
- Today / (in) 0 day(s) / 0 days(s) ago / (in) 0 year(s) / 0 month(s) ago
- Tomorrow / (in) (a) day(s)
- Yesterday / (1) day(s) ago
- (in) (1) month(s)
- 2 month(s) ago
### Relative days of week
#### Default behavior
By default this query finds the closest day of the week in both directions that is not
today. At most, the target day will be exactly 7 days away if it matches today's day
of the week. In general, for `fdate`, "next" means the closest occurrence excluding the
current day; this logic applies to the following sections as well.
- (next) wednesday
- last wednesday
#### Alternative behavior
This behavior can be customized, as there is no universal consensus on whether "next"
means "closest in the future" or "next calendar week". Alternatively, `next` and `last`
can apply on a week-by-week basis.
- next wednesday (equals to `wednesday next week`)
- last wednesday (equals to `wednesday last week`)
- wednesday (closest Wednesday in the future, same as `next wednesday` in default mode)
### Relative days of month
#### Default behavior
Inputting a number will target a specific day of a month.
- (next) 14(th)
- last 14(th)
#### Alternative behavior
This behavior can also be customized so that `next` strictly means "the next calendar
month".
- next 14th (equals to `14th next month`)
- last 14th (equals to `14th last month`)
- 14th (closest 14th in the future, same as `next 14th` in default mode)
### Days on relative month
#### Default behavior
As usual, `next` means the closest occurrence in the future, and `last` means the
opposite.
- (next) 14th April
- (next) April 14th
- last 14 April
- last April 14
#### Alternative behavior
Using a parameter, this behavior can be altered to refer to the next or previous calendar
year.
- next 14th April (equals to `14th April next year`)
- last 14th April (equals to `14th April last year`)
- 14th April (closest 14th April in the future, same as `next 14th April` in default mode)
### Dates on relative intervals
It is possible to query a specific date interval and perform a "subquery" on it. An
interval can be a certain week, month, or year relative to today. Supported intervals are
`week`, `month`, and `year`, then a day of the week, a day of the month, or a specific
day/month of a year can be selected, respectively.
- wednesday this week (regardless of the current day, only the relative week counts)
- friday 2 weeks ago
- tuesday in 2 weeks
- 14th next month
- 17th in two months
- 10 this month
- 1st May this year
- 10th July in two years