# `Mojibake.LanguageTag`
[🔗](https://github.com/zaerl/mojibake/blob/main/src/elixir/lib/mojibake/language_tag.ex#L5)

BCP 47 language tags, such as "en-US", "sr-Latn-RS", or "de-CH-1996".

`parse/1` checks the syntax of a tag strictly and splits it into its subtags, with the case
conventions of BCP 47 applied: lowercase language, titlecase script, uppercase region. It does
not check the subtags against the IANA registry, so "qq-Zzzz" parses.

`to_string/1` formats a parsed tag back:

    iex> {:ok, tag} = Mojibake.LanguageTag.parse("SR-latn-rs")
    iex> to_string(tag)
    "sr-Latn-RS"

The `:locale` option of `Mojibake.upcase/2` and the other casing functions takes a tag; only
its language matters there, and `matched_locale` says which locale Mojibake recognizes.

# `t`

```elixir
@type t() :: %Mojibake.LanguageTag{
  extensions: [String.t()],
  extlang: String.t() | nil,
  grandfathered: String.t() | nil,
  language: String.t() | nil,
  matched_locale: String.t() | nil,
  private_use: [String.t()],
  region: String.t() | nil,
  script: String.t() | nil,
  variants: [String.t()]
}
```

A parsed language tag:

  * `language` - the language subtag, such as `"sr"`
  * `extlang` - extended language subtags, such as `"yue"` in "zh-yue"
  * `script` - an ISO 15924 script code, such as `"Latn"`
  * `region` - an ISO 3166-1 or UN M.49 region code, such as `"RS"` or `"419"`
  * `variants` - variant subtags, such as `["rozaj", "biske"]`
  * `extensions` - extensions, each with its singleton, such as `["u-ca-buddhist"]`
  * `private_use` - the private-use subtags after "x", such as `["foo"]`
  * `grandfathered` - a whole irregular or grandfathered tag, such as `"i-klingon"`; the other
    fields are then empty
  * `matched_locale` - the ISO 639-1 code of the casing locale Mojibake recognizes in the tag,
    such as `"tr"`, or `nil`

Absent subtags are `nil` or `[]`.

# `parse`

```elixir
@spec parse(String.t()) :: {:ok, t()} | {:error, Mojibake.Error.t()}
```

Parse a BCP 47 language tag. Returns
`{:error, %Mojibake.Error{reason: :invalid_locale}}` if it is not well-formed.

## Examples

    iex> Mojibake.LanguageTag.parse("sl-Latn-IT-rozaj-u-ca-buddhist-x-foo")
    {:ok,
     %Mojibake.LanguageTag{
       language: "sl",
       script: "Latn",
       region: "IT",
       variants: ["rozaj"],
       extensions: ["u-ca-buddhist"],
       private_use: ["foo"],
       matched_locale: "sl"
     }}

    iex> Mojibake.LanguageTag.parse("en--US")
    {:error, %Mojibake.Error{reason: :invalid_locale}}

# `parse!`

```elixir
@spec parse!(String.t()) :: t()
```

Like `parse/1`, but raises `Mojibake.Error`.

## Examples

    iex> Mojibake.LanguageTag.parse!("tr-TR").matched_locale
    "tr"

# `to_string`

```elixir
@spec to_string(t()) :: String.t()
```

Format a parsed tag.

## Examples

    iex> Mojibake.LanguageTag.to_string(%Mojibake.LanguageTag{language: "pt", region: "BR"})
    "pt-BR"

# `valid?`

```elixir
@spec valid?(String.t()) :: boolean()
```

Return `true` if `tag` is a well-formed BCP 47 language tag.

## Examples

    iex> Mojibake.LanguageTag.valid?("zh-Hant-TW")
    true

    iex> Mojibake.LanguageTag.valid?("en_US")
    false

---

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