Quando

A Taskwarrior-style date expression parser for Elixir. Parse expressions like +7d, eom, monday, or P1Y2M3D into DateTime structs using NimbleParsec.

Installation

Add quando to your list of dependencies in mix.exs:

def deps do
  [
    {:quando, "~> 0.1.0"}
  ]
end

Usage

# Parse relative durations
{:ok, dt} = Quando.parse("+7d")      # 7 days from now
{:ok, dt} = Quando.parse("-2w")      # 2 weeks ago
{:ok, dt} = Quando.parse("+3m")      # 3 months from now (m = months)
{:ok, dt} = Quando.parse("30min")    # 30 minutes from now

# Parse chained durations
{:ok, dt} = Quando.parse("+1d+9h")   # Tomorrow at this time + 9 hours

# Parse date synonyms
{:ok, dt} = Quando.parse("today")    # Start of today
{:ok, dt} = Quando.parse("tomorrow") # Start of tomorrow

# Parse period boundaries
{:ok, dt} = Quando.parse("eom")      # End of month
{:ok, dt} = Quando.parse("sow")      # Start of week

# Parse day/month names
{:ok, dt} = Quando.parse("monday")   # Next Monday
{:ok, dt} = Quando.parse("fri")      # Next Friday
{:ok, dt} = Quando.parse("december") # December 1st

# Parse ordinals
{:ok, dt} = Quando.parse("15th")     # 15th of current/next month

# Parse ISO-8601 durations
{:ok, dt} = Quando.parse("P3D")      # 3 days from now
{:ok, dt} = Quando.parse("PT1H30M")  # 1 hour 30 minutes from now

# Bang version raises on error
dt = Quando.parse!("+7d")

# Get the parsed AST without calculation
{:ok, ast} = Quando.parse_ast("+7d")
# => {:ok, {:chained_duration, [{:duration, %{sign: :+, amount: 7, unit: :days}}]}}

Supported Syntax

Duration Offsets

Chained Durations

Chain multiple durations together:

Date Synonyms

Day Names

Full names and abbreviations are supported:

monday, mon, tuesday, tue, wednesday, wed, thursday, thu, friday, fri, saturday, sat, sunday, sun

Returns the next occurrence of the specified day.

Month Names

Full names and abbreviations are supported:

january, jan, february, feb, march, mar, april, apr, may, june, jun, july, jul, august, aug, september, sep, october, oct, november, nov, december, dec

Returns the 1st of the next occurrence of the specified month.

Period Boundaries

Ordinals

Returns the specified day of the current month if not yet passed, otherwise the next month.

ISO-8601 Durations

Options

Reference Time

By default, calculations are relative to DateTime.utc_now(). You can specify a custom reference time:

reference = ~U[2026-06-15 10:00:00Z]
{:ok, dt} = Quando.parse("+7d", reference: reference)
# => ~U[2026-06-22 10:00:00Z]

Week Start

By default, weeks start on Monday (1). You can specify a different start day:

# Week starts on Sunday
{:ok, dt} = Quando.parse("sow", week_start: 7)

Key Disambiguation

Following Taskwarrior conventions:

• m = months (not minutes)
• min or mins = minutes

This matches CLI tools where quick typing is important and months are more commonly referenced than minutes for task scheduling.

Reference

• Taskwarrior Date Documentation
• Taskwarrior Duration Documentation
• ISO-8601 Duration Format

License

MIT - see LICENSE