Chronix.Parser (Chronix v0.2.0)

Core parsing logic for Chronix. Prefer the top-level Chronix API.

Orchestrates: normalize → (ISO-8601 short-circuit) → (" at " split for composed date+time) → grammar (Chronix.Grammar.expression/1) → evaluator (Chronix.Evaluator.resolve/2).

Summary

result()

Parses a natural-language date string and resolves it to a DateTime.

@type result() :: {:ok, DateTime.t()} | {:error, String.t()}

@spec parse_expression(
  String.t(),
  keyword()
) :: result()

Parses a natural-language date string and resolves it to a DateTime.

Returns {:ok, datetime} on success or {:error, reason} on failure. Never raises.

:reference_date — a DateTime used as the "now" for all relative expressions, including "today" and "now". Defaults to DateTime.utc_now/0.
:endian — how to interpret ambiguous three-component dates like "01/05/2024" or "01-05-2024". Accepts :us (default, month-first → January 5) or :eu (day-first → May 1). Unambiguous formats (year first, or full ISO-8601) are unaffected.