Localize.Inputs.Date.Parser (Localize.Inputs.Date v0.3.0)

Copy Markdown View Source

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: it names the calendar by its module, and returns the date in that calendar or in Calendar.ISO.

Summary

Functions

parse_date(string, options \\ [])

Parses a locale-formatted date string.

Functions

parse_date(string, options \\ [])

@spec parse_date(term(), 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 module given as the :calendar option — Calendar.ISO (the default), Calendrical.Hebrew, Calendrical.Japanese, and so on. Pass return_calendar: :iso to force the result into Gregorian regardless.

Arguments

  • string is the raw user input: a string, or nil for a blank field.

  • options is a keyword list of options.

Options

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

  • :calendar — the calendar module whose patterns to try AND the calendar of the returned Date, such as Calendrical.Hebrew. Defaults to Calendar.ISO. A CLDR calendar type, such as :hebrew, is not a calendar and is refused.

  • :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, an unknown :calendar, a :return_calendar other than :native or :iso, or a string that is neither a string nor nil.

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-10]}

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: Calendrical.Hebrew)
{:ok, ~D[5786-08-29 Calendrical.Hebrew]}

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

iex> {:error, %Localize.UnknownCalendarError{}} =
...>   Localize.Inputs.Date.Parser.parse_date("2026-05-16", locale: :en, calendar: :hebrew)

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