# Dates
Chore interprets a specific list of pairs as describing dates. Their values
are constrained the recognized formats described below.
All Chore dates include an implied time range. If a task was completed on a
given day, this means it was completed some time between the start of that day
and that day's end.
## Absolute date format
Chore recognizes the following absolute date formats:
- `YYYY-MM-DDTHH:MM:SS`
- `YYYY-MM-DDTHH:MM`
- `YYYY-MM-DDTHH`
- `YYYY-MM-DD`
- `YYYY-MM`
- `YYYY`
Any fields left out are interpreted as covering the entire range when
performing date comparisons. For example, `2020-12` is treated as on or after
`2020-12-01T00:00:00` and before `2021-01-01T00:00:00`
The timezone is always assumed to be local.
## Relative date format
Chore recognizes the following relative date formats, which are interpreted
to the next absolute date that matches the description:
- Abbreviated day of the week (e.g. `mon`)
- Day of the week (e.g. `monday`)
- Ordinal numbers (`1st`, `2nd`, `3rd`, etc) corresponding to the day of a
month
- Abbreviated month (e.g. `oct`)
- Month (e.g. `october`)
- `HH:MM:SS`
- `HH:MM`
Chore also recognizes a series of digits followed by a given character as a
given amount of time in in the future:
- `s` indicates seconds, e.g. `3s`.
- `m` indicates minutes, e.g. `3m`.
- `h` indicates hours, e.g. `3h`.
- `d` indicates days, e.g. `3d`.
- `w` indicates weeks, e.g. `3w`.
- `M` indicates months, e.g. `3M`.
- `y` indicates years, e.g. `3y`.
Chore additionally recognizes these descriptions:
- `now`
- `today`
- `tomorrow`
- `yesterday`
# Special tags
## Dedicated field tags
Chore's format has four positional fields with special meanings:
- The completion marker `x`.
- The optional end date in `YYYY-MM-DD` form.
- The optional priority in `(X)` form.
- The optional entry date in `YYYY-MM-DD` form.
Chore's CLI supports accessing these as tags:
- `+done` indicates a task is completed.
- `end:` is used to reference a task's end date. Its value may be either a
date with a resolution of one day, or empty to represent the absence of an
end date.
- `pri:` is used to reference a task's priority. It may be any single capital
letter `A` through `Z`, or empty to represent a task without a priority.
- `entry:` is used to reference a task's entry date. Its value may be either a
date with a resolution of one day, or empty to represent the absence of an
end date.
These keys should not be used in Chore's on-disk files; they are only valid in
the CLI.
## Date keys
Chore knows that the `end:` and `entry:` keys describe absolute dates. If a
relative date is provided on the CLI, Chore will automatically translate this
to the corresponding absolute date. If a non-date is provided on the CLI,
Chore will error accordingly.
Chore can be configured to treat additional keys in this manner by listing them
in a file at `~/.chore/date-keys`, one per line. To emphasize the fact they
are keys, they may optionally contain a trailing `:` character. For example,
`~/.chore/date-keys` may contain:
```
due:
scheduled:
until:
wait:
```
## recur:
The `recur:` key is used for recurring tasks. Its value must be a relative
date. When a task with this key is completed or deleted through Chore, Chore
will automatically create a new instance of the task, with any date keys
adjusted by the `recur:` value. For example, if `~/.chore/date-keys` contains
(at least):
```
due:
wait:
```
and the task
```
2020-12-01 @home give +dog flea meds recur:1M due:2021-01-07 wait:2021-01-01
```
is modified to be completed through Chore, Chore will generate a new
task with the date fields incremented by one month:
```
2021-01-01 @home give +dog flea meds recur:1M due:2021-02-07 wait:2021-02-01
x 2020-12-01 @home give +dog flea meds recur:1M due:2021-01-07 wait:2021-01-01
```
To delete such a task without creating a new instance, first modify the task to
remove the `recur:` tag.
## +update
Users may not care to clutter the task list with every completed instance of a
frequently occurring task. The `+update` tag may be used to tell Chore to keep
no more than one completed instance of a given task. Rather than create a
second completed instance of such a task, a preexisting task which exactly
matches the newly completed one in every way except date values will have the
corresponding task's date values updated. This is generally paired with the
`recur:` tag.
For example, if the task list contains:
```
2020-12-09 garbage day due:2020-12-09 recur:1w +update
x 2020-12-02 (M) 2020-12-02 garbage day due:2020-12-02 recur:1w +update
```
And chore is told on 2020-12-09 that the pending task is completed, Chore will
update the task list to:
```
2020-12-16 garbage day due:2020-12-16 recur:1w +update
x 2020-12-09 (M) 2020-12-09 garbage day due:2020-12-09 recur:1w +update
```
Where `+update` resulted in the completed task having its dates rather than the
normal behavior of creating a new completed entry, and where `recur:1w` created
a new task.