# `Localize.Inputs.Date.Parser`
[🔗](https://github.com/elixir-localize/localize_datetime_inputs/blob/v0.1.1/lib/localize/inputs/date/parser.ex#L1)

Front-door parser for locale-aware date form input.

Delegates to `Calendrical.Date.parse/2`. The input layer does
no parsing of its own — this module is a thin policy layer
over the underlying CLDR-driven parser.

# `parse_date`

```elixir
@spec parse_date(String.t() | nil, Keyword.t()) ::
  {:ok, Date.t() | nil} | {:error, Exception.t()}
```

Parses a locale-formatted date string.

Tries, in order: bare ISO-8601 (`YYYY-MM-DD`), then every
CLDR `availableFormats` skeleton for the (locale, calendar)
tuple. Skeletons encode the locale's preferred field order
(and any era / week-numbering / quarter conventions), so the
same input may parse to different dates under different
locales — by design.

Returns a `Date` in the calendar identified by the `:calendar`
option — `Calendar.ISO` for `:gregorian` (the default),
`Calendrical.Hebrew` for `:hebrew`, `Calendrical.Japanese` for
`:japanese`, and so on. Pass `return_calendar: :iso` to force
the result into Gregorian regardless.

### Arguments

* `string` is the raw user input.

* `options` is a keyword list of options.

### Options

* `:locale` — the locale to interpret the string under. Defaults
  to `Localize.get_locale/0`.

* `:calendar` — the CLDR calendar key whose patterns to try
  AND the calendar of the returned `Date`. Defaults to
  `:gregorian`.

* `:reference_date` — the "today" anchor used for two-digit-year
  pivoting. Defaults to `Date.utc_today/0`.

* `:return_calendar` — `:native` (default) returns the parsed
  date in whatever `:calendar` named. `:iso` forces
  `Calendar.ISO`.

### Returns

* `{:ok, Date.t()}` on success.

* `{:ok, nil}` for blank input.

* `{:error, Exception.t()}` on parse failure.

### Examples

    iex> Localize.Inputs.Date.Parser.parse_date("2026-05-16", locale: :en)
    {:ok, ~D[2026-05-16]}

    iex> Localize.Inputs.Date.Parser.parse_date("5/16/26", locale: :en)
    {:ok, ~D[2026-05-16]}

    iex> Localize.Inputs.Date.Parser.parse_date("16/05/2026", locale: :"en-GB")
    {:ok, ~D[2026-05-16]}

    iex> Localize.Inputs.Date.Parser.parse_date("16.05.2026", locale: :de)
    {:ok, ~D[2026-05-16]}

    iex> Localize.Inputs.Date.Parser.parse_date("Q2 2026", locale: :en)
    {:ok, ~D[2026-04-01]}

    iex> Localize.Inputs.Date.Parser.parse_date("week 20 of 2026", locale: :en)
    {:ok, ~D[2026-05-11]}

    iex> Localize.Inputs.Date.Parser.parse_date("Saturday, May 16, 2026", locale: :en)
    {:ok, ~D[2026-05-16]}

    iex> Localize.Inputs.Date.Parser.parse_date("2026-05-16", locale: :en, calendar: :hebrew)
    {:ok, ~D[5786-09-29 Calendrical.Hebrew]}

    iex> Localize.Inputs.Date.Parser.parse_date("", locale: :en)
    {:ok, nil}

---

*Consult [api-reference.md](api-reference.md) for complete listing*