Add localized parse to Date, Time and DateTime, and gate guide examples in CI

Author: kipcole9

lib/localize/date.ex

@@ -472,4 +472,59 @@ defmodule Localize.Date do
   # ── Locale resolution ──────────────────────────────────────
 
   defp resolve_locale_id(locale), do: Localize.Locale.cldr_locale_id_from(locale)
+
+  @doc """
+  Parses a localized date string.
+
+  Parsing lives in the companion [calendrical](https://hex.pm/packages/calendrical)
+  package, which carries the calendar systems Localize formats for.
+  `calendrical` depends on Localize, so Localize resolves it at runtime rather
+  than depending on it in return — add `{:calendrical, "~> 1.0"}` to your
+  dependencies to use this function.
+
+  ### Arguments
+
+  * `string` is a string in any shape the locale accepts, including the
+    locale's CLDR short, medium, long and full patterns and ISO 8601.
+
+  * `options` is a keyword list of options.
+
+  ### Options
+
+  * `:locale` is a locale identifier. The default is the locale returned by
+    `Localize.get_locale/0`.
+
+  * Remaining options are passed to `Calendrical.Date.parse/2`, which
+    documents them.
+
+  ### Returns
+
+  * `{:ok, value}` where `value` is a `t:Date.t()` , or
+
+  * `{:error, exception}` if the string does not parse, or a
+    `t:Localize.DependencyRequiredError.t/0` if `calendrical` is not among
+    the application's dependencies.
+
+  ### Examples
+
+  Shown rather than run as doctests: `calendrical` is not a dependency of
+  Localize itself, so the call does not resolve in this package's own tests.
+
+      Localize.Date.parse("22.03.2026", locale: :de)
+      #=> {:ok, ~D[2026-03-22]}
+
+      Localize.Date.parse("March 22, 2026", locale: :en)
+      #=> {:ok, ~D[2026-03-22]}
+
+  """
+  @spec parse(String.t(), Keyword.t()) :: {:ok, Date.t()} | {:error, Exception.t()}
+  def parse(string, options \\ []) when is_binary(string) do
+    Localize.OptionalDependency.call(
+      "Calendrical.Date",
+      :parse,
+      [string, options],
+      package: "calendrical",
+      operation: "Localize.Date.parse/2"
+    )
+  end
 end

lib/localize/datetime.ex

@@ -559,4 +559,60 @@ defmodule Localize.DateTime do
   end
 
   defp resolve_locale_id(locale), do: Localize.Locale.cldr_locale_id_from(locale)
+
+  @doc """
+  Parses a localized date and time string.
+
+  Parsing lives in the companion [calendrical](https://hex.pm/packages/calendrical)
+  package, which carries the calendar systems Localize formats for.
+  `calendrical` depends on Localize, so Localize resolves it at runtime rather
+  than depending on it in return — add `{:calendrical, "~> 1.0"}` to your
+  dependencies to use this function.
+
+  ### Arguments
+
+  * `string` is a string in any shape the locale accepts, including the
+    locale's CLDR short, medium, long and full patterns and ISO 8601.
+
+  * `options` is a keyword list of options.
+
+  ### Options
+
+  * `:locale` is a locale identifier. The default is the locale returned by
+    `Localize.get_locale/0`.
+
+  * Remaining options are passed to `Calendrical.DateTime.parse/2`, which
+    documents them.
+
+  ### Returns
+
+  * `{:ok, value}` where `value` is a `t:NaiveDateTime.t()` , or
+
+  * `{:error, exception}` if the string does not parse, or a
+    `t:Localize.DependencyRequiredError.t/0` if `calendrical` is not among
+    the application's dependencies.
+
+  ### Examples
+
+  Shown rather than run as doctests: `calendrical` is not a dependency of
+  Localize itself, so the call does not resolve in this package's own tests.
+
+      Localize.DateTime.parse("22.03.2026, 14:30", locale: :de)
+      #=> {:ok, ~N[2026-03-22 14:30:00]}
+
+      Localize.DateTime.parse("March 22, 2026, 2:30 PM", locale: :en)
+      #=> {:ok, ~N[2026-03-22 14:30:00]}
+
+  """
+  @spec parse(String.t(), Keyword.t()) ::
+          {:ok, NaiveDateTime.t() | DateTime.t()} | {:error, Exception.t()}
+  def parse(string, options \\ []) when is_binary(string) do
+    Localize.OptionalDependency.call(
+      "Calendrical.DateTime",
+      :parse,
+      [string, options],
+      package: "calendrical",
+      operation: "Localize.DateTime.parse/2"
+    )
+  end
 end

lib/localize/exception/dependency_required_error.ex

@@ -0,0 +1,35 @@
+defmodule Localize.DependencyRequiredError do
+  @moduledoc """
+  Exception returned when an operation needs a companion package that is
+  not among the application's dependencies.
+
+  Localize delegates a few operations to sibling packages that depend on
+  Localize in turn, so it cannot depend on them back. Those operations
+  resolve the module at runtime and return this exception when it is
+  absent, naming the package to add.
+
+  """
+
+  defexception [:package, :operation]
+
+  @typedoc """
+  The package that is required, and the operation that needs it.
+
+  """
+  @type t :: %__MODULE__{package: String.t(), operation: String.t()}
+
+  @impl true
+  def exception(bindings) when is_list(bindings) do
+    struct!(__MODULE__, bindings)
+  end
+
+  @impl true
+  def message(%__MODULE__{package: package, operation: operation}) do
+    Localize.Exception.safe_message(
+      "datetime",
+      "{$operation} requires the {$package} package, which is not among your dependencies.",
+      operation: operation,
+      package: package
+    )
+  end
+end

lib/localize/gettext/messages.ex

@@ -17,6 +17,13 @@ defmodule Localize.Gettext.Messages do
   def __messages__ do
     [
       # Currency
+      # Dependencies
+      Gettext.Macros.dpgettext_noop_with_backend(
+        Localize.Gettext,
+        "localize",
+        "datetime",
+        "{$operation} requires the {$package} package, which is not among your dependencies."
+      ),
       Gettext.Macros.dpgettext_noop_with_backend(
         Localize.Gettext,
         "localize",

lib/localize/nif.ex

@@ -215,6 +215,18 @@ defmodule Localize.Nif do
   An integer: `-1` (less than), `0` (equal), or `1` (greater than).
 
   """
+  @spec nif_collation_cmp(
+          binary(),
+          binary(),
+          integer(),
+          integer(),
+          integer(),
+          integer(),
+          integer(),
+          integer(),
+          integer(),
+          binary()
+        ) :: -1 | 0 | 1
   @dialyzer {:no_return, nif_collation_cmp: 10}
   # The arity mirrors the C NIF signature one-to-one; collapsing the
   # collation options into a map would add per-call marshalling on a

lib/localize/optional_dependency.ex

@@ -0,0 +1,32 @@
+defmodule Localize.OptionalDependency do
+  @moduledoc false
+
+  # Some operations belong to a sibling package in the Localize family rather
+  # than to Localize itself — parsing a localized date is `calendrical`'s job,
+  # and `calendrical` depends on Localize, so Localize cannot depend on it in
+  # return without a cycle.
+  #
+  # The target module is therefore built with `Module.concat/1` and called
+  # through a variable rather than named literally. The compiler records no
+  # dependency and emits no undefined-module warning, and the call resolves at
+  # runtime against whatever the consuming application actually has.
+
+  @doc false
+  @spec call(String.t(), atom(), [term()], keyword()) :: term() | {:error, Exception.t()}
+  def call(module_name, function, args, context) do
+    module = Module.concat([module_name])
+
+    # `Code.ensure_loaded?/1` first: `function_exported?/3` answers false for a
+    # module that is compiled but not yet loaded, which would report the
+    # package missing on the first call after boot.
+    if Code.ensure_loaded?(module) and function_exported?(module, function, length(args)) do
+      Kernel.apply(module, function, args)
+    else
+      {:error,
+       Localize.DependencyRequiredError.exception(
+         package: Keyword.fetch!(context, :package),
+         operation: Keyword.fetch!(context, :operation)
+       )}
+    end
+  end
+end

lib/localize/time.ex

@@ -539,4 +539,59 @@ defmodule Localize.Time do
   # ── Locale resolution ──────────────────────────────────────
 
   defp resolve_locale_id(locale), do: Localize.Locale.cldr_locale_id_from(locale)
+
+  @doc """
+  Parses a localized time string.
+
+  Parsing lives in the companion [calendrical](https://hex.pm/packages/calendrical)
+  package, which carries the calendar systems Localize formats for.
+  `calendrical` depends on Localize, so Localize resolves it at runtime rather
+  than depending on it in return — add `{:calendrical, "~> 1.0"}` to your
+  dependencies to use this function.
+
+  ### Arguments
+
+  * `string` is a string in any shape the locale accepts, including the
+    locale's CLDR short, medium, long and full patterns and ISO 8601.
+
+  * `options` is a keyword list of options.
+
+  ### Options
+
+  * `:locale` is a locale identifier. The default is the locale returned by
+    `Localize.get_locale/0`.
+
+  * Remaining options are passed to `Calendrical.Time.parse/2`, which
+    documents them.
+
+  ### Returns
+
+  * `{:ok, value}` where `value` is a `t:Time.t()` , or
+
+  * `{:error, exception}` if the string does not parse, or a
+    `t:Localize.DependencyRequiredError.t/0` if `calendrical` is not among
+    the application's dependencies.
+
+  ### Examples
+
+  Shown rather than run as doctests: `calendrical` is not a dependency of
+  Localize itself, so the call does not resolve in this package's own tests.
+
+      Localize.Time.parse("14:30", locale: :de)
+      #=> {:ok, ~T[14:30:00]}
+
+      Localize.Time.parse("2:30 PM", locale: :en)
+      #=> {:ok, ~T[14:30:00]}
+
+  """
+  @spec parse(String.t(), Keyword.t()) :: {:ok, Time.t()} | {:error, Exception.t()}
+  def parse(string, options \\ []) when is_binary(string) do
+    Localize.OptionalDependency.call(
+      "Calendrical.Time",
+      :parse,
+      [string, options],
+      package: "calendrical",
+      operation: "Localize.Time.parse/2"
+    )
+  end
 end

lib/localize/unit/operators.ex

@@ -68,6 +68,7 @@ defmodule Localize.Unit.Operators do
   through to `Kernel.+/2`.
 
   """
+  @spec unquote(:+)(Unit.t() | number(), Unit.t() | number()) :: Unit.t() | number()
   def unquote(:+)(%Unit{} = left, %Unit{} = right) do
     unwrap!(Unit.Math.add(left, right))
   end
@@ -84,6 +85,7 @@ defmodule Localize.Unit.Operators do
   through to `Kernel.-/2`.
 
   """
+  @spec unquote(:-)(Unit.t() | number(), Unit.t() | number()) :: Unit.t() | number()
   def unquote(:-)(%Unit{} = left, %Unit{} = right) do
     unwrap!(Unit.Math.sub(left, right))
   end
@@ -101,6 +103,7 @@ defmodule Localize.Unit.Operators do
   `Kernel.*/2`.
 
   """
+  @spec unquote(:*)(Unit.t() | number(), Unit.t() | number()) :: Unit.t() | number()
   def unquote(:*)(%Unit{} = left, %Unit{} = right) do
     unwrap!(Unit.Math.mult(left, right))
   end
@@ -128,6 +131,7 @@ defmodule Localize.Unit.Operators do
   `Kernel.//2`.
 
   """
+  @spec unquote(:/)(Unit.t() | number(), Unit.t() | number()) :: Unit.t() | number()
   def unquote(:/)(%Unit{} = left, %Unit{} = right) do
     unwrap!(Unit.Math.div(left, right))
   end