todo.parse-date-phrase

def parse_date_phrase(text: str, today: str) -> Optional[str]

from fune.todo.parse_date_phrase import parse_date_phrase  # todo.parse-date-phrase@^1

import re
from typing import List, Optional

from .dates_add_days import add_days, days_in_month  ← from dates.add-days ^1.0.0 · built alongside by fune
from .dates_add_months import add_months  ← from dates.add-months ^1.0.0 · built alongside by fune
from .dates_day_of_week import day_of_week  ← from dates.day-of-week ^1.0.0 · built alongside by fune

_WEEKDAYS = {
    "monday": 1, "mon": 1,
    "tuesday": 2, "tue": 2, "tues": 2,
    "wednesday": 3, "wed": 3,
    "thursday": 4, "thu": 4, "thur": 4, "thurs": 4,
    "friday": 5, "fri": 5,
    "saturday": 6, "sat": 6,
    "sunday": 7, "sun": 7,
}

_NUMBER_WORDS = {
    "a": 1, "an": 1, "one": 1, "two": 2, "three": 3, "four": 4, "five": 5,
    "six": 6, "seven": 7, "eight": 8, "nine": 9, "ten": 10,
}

_UNITS = {
    "day": "day", "days": "day", "week": "week", "weeks": "week",
    "month": "month", "months": "month", "year": "year", "years": "year",
}

_SPACES = re.compile(r"[ \t\n\r\x0b\x0c]+")
_COUNT = re.compile(r"[1-9][0-9]{0,2}")
_ISO = re.compile(r"[0-9]{4}-[0-9]{2}-[0-9]{2}")


def _lower_ascii(text: str) -> str:
    """Upper-case ASCII letters only, so no other script can spell a keyword."""
    return "".join(chr(ord(c) + 32) if "A" <= c <= "Z" else c for c in text)


def _split_words(text: str) -> List[str]:
    return [w for w in _SPACES.split(text) if w != ""]


def _is_real_date(word: str) -> bool:
    if not _ISO.fullmatch(word):
        return False
    year, month, day = int(word[0:4]), int(word[5:7]), int(word[8:10])
    return year >= 1 and 1 <= month <= 12 and 1 <= day <= days_in_month(year, month)


def _count(word: str) -> Optional[int]:
    if _COUNT.fullmatch(word):
        return int(word)
    return _NUMBER_WORDS.get(word)


def _days_until(weekday: int, today: int) -> int:
    """Days from today to the next given weekday, 1 to 7: never today itself."""
    return (weekday - today + 6) % 7 + 1


def parse_date_phrase(text: str, today: str) -> Optional[str]:
    """The date a typed phrase names, counted from today, or None when the
    whole text is not one of the phrases in the README."""
    # add_days(x, 0) is the date check: it raises dates.add-days's message.
    add_days(today, 0)
    words = _split_words(_lower_ascii(text))
    if len(words) > 1 and words[0] in ("on", "due"):
        words = words[1:]
    dow = day_of_week(today)

    if len(words) == 1:
        word = words[0]
        if word in ("today", "tod"):
            return today
        if word in ("tomorrow", "tmr", "tmrw"):
            return add_days(today, 1)
        if word == "yesterday":
            return add_days(today, -1)
        if word == "weekend":
            return today if dow >= 6 else add_days(today, 6 - dow)
        if word in _WEEKDAYS:
            return add_days(today, _days_until(_WEEKDAYS[word], dow))
        return word if _is_real_date(word) else None
    if len(words) == 2:
        first, second = words
        if first == "this" and second == "weekend":
            return today if dow >= 6 else add_days(today, 6 - dow)
        if first != "next":
            return None
        next_monday = 8 - dow
        if second == "week":
            return add_days(today, next_monday)
        if second == "month":
            return add_months(today[0:8] + "01", 1)
        if second == "year":
            return add_months(today[0:5] + "01-01", 12)
        if second in _WEEKDAYS:
            return add_days(today, next_monday + _WEEKDAYS[second] - 1)
        return None
    if len(words) == 3 and words[0] == "in":
        n = _count(words[1])
        unit = _UNITS.get(words[2])
        if n is None or unit is None:
            return None
        if unit == "day":
            return add_days(today, n)
        if unit == "week":
            return add_days(today, 7 * n)
        if unit == "month":
            return add_months(today, n)
        return add_months(today, 12 * n)
    return None

Install

fune build

With that line in your source, in a Python project (language python in fune.project), fune build resolves it and its 3 dependencies, pins them in fune.lock, downloads only the Python package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. Or pin a range in fune.project and build in one step:

fune add todo.parse-date-phrase

The manifest, vectors and README with only the Python implementation. Install it without the registry with fune add ./todo.parse-date-phrase-1.0.0-python.fune, or fetch it from a terminal with fune pull todo.parse-date-phrase@1.0.0:python.

The whole function, every language, is one file too: todo.parse-date-phrase-1.0.0.fune, 27,727 bytes, sha256 d450114d42ed52f5273b9e892f470087e1157482e503316c84b52862283d32bd. It installs into a project of any language.

# fune: before todo.parse-date-phrase

# fune: after todo.parse-date-phrase

# fune: replace dates.add-days in todo.parse-date-phrase
# fune: replace dates.add-months in todo.parse-date-phrase
# fune: replace dates.day-of-week in todo.parse-date-phrase

# fune: step todo.parse-date-phrase after <n|label>

More from the author

todo.parse-quick-add uses it to find the due date inside a whole quick-add line.

## Grammar

The whole text must be one phrase. Letters are matched case-insensitively (ASCII only: `ＴＯＤＡＹ` in full-width letters is not a keyword). Words are separated by one or more ASCII whitespace characters (space, tab, CR, LF, VT, FF), and whitespace at either end is ignored.

| Phrase | Means | Example, today Monday 2026-09-28 | | --- | --- | --- | | `today`, `tod` | today | 2026-09-28 | | `tomorrow`, `tmr`, `tmrw` | today + 1 day | 2026-09-29 | | `yesterday` | today - 1 day (a due date may be overdue) | 2026-09-27 | | a weekday: `monday`/`mon`, `tuesday`/`tue`/`tues`, `wednesday`/`wed`, `thursday`/`thu`/`thur`/`thurs`, `friday`/`fri`, `saturday`/`sat`, `sunday`/`sun` | the next such day strictly after today (1 to 7 days on) | `friday` = 2026-10-02; `monday` = 2026-10-05 | | `next week` | Monday of next ISO week | 2026-10-05 | | `next <weekday>` | that weekday in next ISO week (Monday to Sunday) | `next friday` = 2026-10-09 | | `next month` | the 1st of next month | 2026-10-01 | | `next year` | 1 January next year | 2027-01-01 | | `weekend`, `this weekend` | the coming Saturday; today if today is Saturday or Sunday | 2026-10-03 | | `in N day(s)` | today + N days | `in 3 days` = 2026-10-01 | | `in N week(s)` | today + 7N days | `in a week` = 2026-10-05 | | `in N month(s)` | today + N months, clamped to the month end (dates.add-months) | `in 1 month` from 2026-01-31 = 2026-02-28 | | `in N year(s)` | today + 12N months, clamped (29 Feb becomes 28 Feb) | `in a year` from 2028-02-29 = 2029-02-28 | | `YYYY-MM-DD` | that date, if it is a real date (years 0001-9999) | `2026-10-01` | | `on <phrase>`, `due <phrase>` | the same as the phrase | `due friday`, `on 2026-10-01` |

N is 1 to 999 in ASCII digits with no leading zero (`in 03 days` is not a phrase), or one of the words `a`, `an`, `one` ... `ten`. Units may be singular or plural whatever N is. Only one `on` or `due` is allowed, and only in front.

Anything else is null: `friday week`, `in 3 lightyears`, `in 0 days`, `in 1000 days`, `2026-02-30`, `next`, an empty string, or a phrase with other words around it (`pay rent tomorrow`; finding a phrase inside a line is todo.parse-quick-add's job).

## Decisions

- **A weekday name never means today.** On a Friday, `friday` is a week away: someone typing a weekday means a day to come, and `today` is the word for today. - **`next <weekday>` means next week's.** On Monday 28 September, `friday` is 2 October and `next friday` is 9 October. People disagree about this one; the ISO-week reading at least gives the two phrases different answers, and a UI can show the date it picked. - **`weekend` on a Sunday is today.** It is still the weekend, and jumping to next Saturday would push the task six days out. - **`in 1 month` clamps**, as dates.add-months does: 31 January + 1 month is 28 February (29 in a leap year), never 3 March. - **An impossible ISO date is null, not an error.** It is something typed, like any other unrecognised text; only `today` is the caller's responsibility.

Files