dateling 0.1.0

dateling provides a normalized formal language and grammar for handling relative time expressions. It includes a DSL (domain-specific language) to represent time anchors, offsets, and modifiers, along with a robust parser and resolver to evaluate these expressions into concrete dates. The name 'dateling' comes from combining 'date' and 'handling', reflecting its purpose of handling complex date computations

dateling

dateling: A DSL parser and resolver for normalized date expressions

dateling provides a formalized expression language and grammar for handling relative and absolute date computations.
It defines a structured Date DSL (Domain-Specific Language) and provides a parser that resolves these expressions into actual dates.

The name dateling combines date and handling, representing its core purpose: structured date handling.

---

✅ Date Expression DSL

Format:

Anchors

• today (current date)
• YYYYMMDD (e.g., 20250101)
• YYYY-MM-DD (e.g., 2025-01-01)

Offsets

• +Nd, -Nd → days
• +Nm, -Nm → months
• +Ny, -Ny → years

Modifiers

• year_start → start of year
• year_end → end of year
• year=infer_year → use anchor year; if resulting date is in future, fallback to previous year
• year=YYYY → explicit year override
• month=MM → month override
• day=DD → day override

---

✅ Examples

DSL Expression	Meaning
{today}	today's date
{today - Nd}	N days ago
{today - Ny}	N years ago
`{today	year_start}`
`{today	year=infer_year, month=MM, day=DD}`
`{today -1y	year_end}`

---

✅ Test Examples (executed on 2025-06-11)

DSL	Resolved Date
{today}	2025-06-11
{today -1d}	2025-06-10
`{today -365d	year=infer_year}`
{today -3y}	2022-06-11
`{today	year_start}`
`{today	year_end}`
`{today -1y	year_start}`
`{today -1y	year_end}`
`{today	year=infer_year, month=06, day=10}`
`{today -1y	year=infer_year, month=03, day=10}`
`{today	year=2024, month=06, day=10}`
{year=2022, month=05, day=15}	2022-05-15
2025-01-01	2025-01-01
20250101	2025-01-01
`{1000-01-01 +30y	year_end}`
{today -36m}	2022-06-11
`{today	year=infer_year, month=06, day=10}`

---

✅ Install

pip install dateling

---

✅ Usage

from dateling import DatelingResolver

resolver = DatelingResolver()
date = resolver.resolve("{today -1y | year_start}")
print(date)

---

✅ License

MIT License

---

✅ Purpose

• Fully normalized date expression language (DSL)
• Precise parsing and evaluation of relative and absolute date computations
• Designed for any system that needs structured time computations:
  • search systems
  • reporting tools
  • schedulers
  • time-based data processing