defmodule BeamlabLanguages do
  @moduledoc """
  Linguistic metadata for human languages.

  Answers questions like:

  - Does this language use grammatical gender? Which genders?
  - Is it written right-to-left?
  - What's the canonical English name? The endonym?
  - Can I collapse a BCP 47 tag like `"en-US"` to a base code?

  All data is curated and embedded at compile time. No runtime file I/O,
  no GenServer, no ETS, no runtime dependencies.

  ## Gender codes

  Genders are returned as strings. Consumers commonly see `"m"` (masculine),
  `"f"` (feminine), and `"n"` (neuter), but **also `"c"` (common)** for the
  Continental Scandinavian and Dutch systems where masculine and feminine
  have merged: Danish, Dutch, Norwegian Bokmål via `no`, and Swedish all
  use `["c", "n"]`. Pattern-match on all four — a `case g do "m" -> ...;
  "f" -> ...; "n" -> ... end` will silently miss those languages.

  ## Quick start

      iex> BeamlabLanguages.has_gender?("fr")
      true

      iex> BeamlabLanguages.genders("de")
      ["m", "f", "n"]

      iex> BeamlabLanguages.direction("ar")
      :rtl

      iex> BeamlabLanguages.normalize("en-US")
      "en"

  Every function that takes a language code runs `normalize/1` on it
  internally — pass `"en-US"`, `"FR"`, or `" fr "` and lookups still work.

  ## Roadmap

  Planned for future versions and intentionally **not** in v1:
  localized language names, plural rules, articles, case marking,
  noun classes, scripts, IPA inventory, honorific levels.
  """

  alias BeamlabLanguages.Language

  @type code :: String.t()
  @type gender :: String.t()
  @type direction :: :ltr | :rtl

  @data_path Path.join([:code.priv_dir(:beamlab_languages), "data", "languages.json"])
  @external_resource @data_path

  @raw @data_path
       |> File.read!()
       |> JSON.decode!()

  # Map deprecated / regional bases to the canonical entry in the data file.
  # Real-world input from POSIX locales, glibc, and browsers emits these:
  #   - "nb" (Bokmål) and "nn" (Nynorsk) collapse to "no" (Norwegian)
  @aliases %{"nb" => "no", "nn" => "no"}

  @languages @raw
             |> Enum.map(fn {code, data} ->
               {code,
                %Language{
                  code: code,
                  name: data["name"],
                  native_name: data["native_name"],
                  direction: String.to_atom(data["direction"]),
                  has_gender: data["has_gender"],
                  genders: data["genders"]
                }}
             end)
             |> Map.new()

  @sorted_codes @languages |> Map.keys() |> Enum.sort()
  @sorted_languages Enum.map(@sorted_codes, &Map.fetch!(@languages, &1))

  @doc """
  Returns the language struct for a code, or `nil` if unknown.

  Accepts BCP 47 input — `"en-US"`, `"zh-Hans-CN"` — and sloppy casing.
  Lookups are normalized internally via `normalize/1`.

  ## Examples

      iex> BeamlabLanguages.get("fr").name
      "French"

      iex> BeamlabLanguages.get("en-US").code
      "en"

      iex> BeamlabLanguages.get("xx")
      nil

  """
  @spec get(any()) :: Language.t() | nil
  def get(code) do
    case normalize(code) do
      nil -> nil
      base -> Map.get(@languages, base)
    end
  end

  @doc """
  Lists every known language struct, sorted by code.

  Sort order is stable so the result can drive UI dropdowns without flicker.

  ## Examples

      iex> langs = BeamlabLanguages.list()
      iex> hd(langs).__struct__
      BeamlabLanguages.Language
      iex> length(langs) > 0
      true

  """
  @spec list() :: [Language.t()]
  def list, do: @sorted_languages

  @doc """
  Lists every known 2-letter base code, sorted.

  ## Examples

      iex> "en" in BeamlabLanguages.list_codes()
      true

      iex> codes = BeamlabLanguages.list_codes()
      iex> codes == Enum.sort(codes)
      true

  """
  @spec list_codes() :: [code()]
  def list_codes, do: @sorted_codes

  @doc """
  Returns true iff the language uses grammatical gender.

  Returns `false` for unknown / `nil` / non-string input rather than
  raising — callers (form validation, template rendering) often pass
  whatever they received from the user.

  ## Examples

      iex> BeamlabLanguages.has_gender?("fr")
      true

      iex> BeamlabLanguages.has_gender?("en")
      false

      iex> BeamlabLanguages.has_gender?("xx")
      false

  """
  @spec has_gender?(any()) :: boolean()
  def has_gender?(code) do
    case get(code) do
      %Language{has_gender: g} -> g
      nil -> false
    end
  end

  @doc """
  Returns the list of gender codes a language uses.

  Returns `[]` for languages without grammatical gender, and `[]` for
  unknown codes.

  ## Examples

      iex> BeamlabLanguages.genders("fr")
      ["m", "f"]

      iex> BeamlabLanguages.genders("de")
      ["m", "f", "n"]

      iex> BeamlabLanguages.genders("en")
      []

  """
  @spec genders(any()) :: [gender()]
  def genders(code) do
    case get(code) do
      %Language{genders: g} -> g
      nil -> []
    end
  end

  @doc """
  Returns the writing direction.

  Returns `:ltr` for unknown codes — the safe default for most rendering
  contexts where an unknown language shouldn't flip the page layout.

  ## Examples

      iex> BeamlabLanguages.direction("ar")
      :rtl

      iex> BeamlabLanguages.direction("en")
      :ltr

      iex> BeamlabLanguages.direction("xx")
      :ltr

  """
  @spec direction(any()) :: direction()
  def direction(code) do
    case get(code) do
      %Language{direction: d} -> d
      nil -> :ltr
    end
  end

  @doc """
  Canonical English name of the language. Returns `nil` for unknown codes.

  ## Examples

      iex> BeamlabLanguages.name("fr")
      "French"

      iex> BeamlabLanguages.name("ja")
      "Japanese"

      iex> BeamlabLanguages.name("xx")
      nil

  """
  @spec name(any()) :: String.t() | nil
  def name(code) do
    case get(code) do
      %Language{name: n} -> n
      nil -> nil
    end
  end

  @doc """
  Native (endonym) name of the language — what speakers call it themselves.

  Returns `nil` for unknown codes.

  ## Examples

      iex> BeamlabLanguages.native_name("fr")
      "Français"

      iex> BeamlabLanguages.native_name("ja")
      "日本語"

      iex> BeamlabLanguages.native_name("xx")
      nil

  """
  @spec native_name(any()) :: String.t() | nil
  def native_name(code) do
    case get(code) do
      %Language{native_name: n} -> n
      nil -> nil
    end
  end

  @doc """
  Normalizes a language input string to a 2-letter base code.

  - Strips dialect tags (`"en-US"` → `"en"`, `"zh-Hans-CN"` → `"zh"`)
  - Accepts `_` as a separator too (`"en_US"` → `"en"`)
  - Lowercases (`"FR"` → `"fr"`)
  - Trims whitespace
  - Maps deprecated / regional bases to their canonical entry: `"nb"`
    (Bokmål) and `"nn"` (Nynorsk) collapse to `"no"` (Norwegian)
  - Returns `nil` if no plausible 2-letter base can be extracted

  This is what every other function calls internally before looking up
  a code, so consumers never need to normalize before calling `get/1`,
  `name/1`, etc. — but it's exposed because consumers sometimes need
  the bare base code for their own purposes.

  ## Examples

      iex> BeamlabLanguages.normalize("en-US")
      "en"

      iex> BeamlabLanguages.normalize("FR")
      "fr"

      iex> BeamlabLanguages.normalize("zh-Hans-CN")
      "zh"

      iex> BeamlabLanguages.normalize("nb-NO")
      "no"

      iex> BeamlabLanguages.normalize("")
      nil

      iex> BeamlabLanguages.normalize(nil)
      nil

  """
  @spec normalize(any()) :: code() | nil
  def normalize(input) when is_binary(input) do
    input
    |> String.trim()
    |> String.downcase()
    |> String.split(["-", "_"], parts: 2)
    |> hd()
    |> base_or_nil()
    |> dealias()
  end

  def normalize(_), do: nil

  defp base_or_nil(<<a, b>>) when a in ?a..?z and b in ?a..?z, do: <<a, b>>
  defp base_or_nil(_), do: nil

  defp dealias(nil), do: nil
  defp dealias(base), do: Map.get(@aliases, base, base)

  @doc """
  Returns true iff the code maps to a known language.

  Sugar over `get/1`. Returns `false` for unknown / `nil` / non-string input.

  ## Examples

      iex> BeamlabLanguages.known?("fr")
      true

      iex> BeamlabLanguages.known?("en-US")
      true

      iex> BeamlabLanguages.known?("xx")
      false

  """
  @spec known?(any()) :: boolean()
  def known?(code), do: get(code) != nil
end