# `Localize.Script`
[🔗](https://github.com/elixir-localize/localize/blob/v0.14.0/lib/localize/script.ex#L1)

Provides script name localization functions built on the
Unicode CLDR repository.

Script display names are loaded on demand from the locale
data provider. Each locale provides localized names for
script codes in one or more styles.

## Styles

Script display names come in several styles:

* `:standard` — the default form, suitable for combining with
  a language name in a locale pattern (e.g., "Simplified").

* `:short` — a shorter form when available (e.g., "UCAS"
  instead of "Unified Canadian Aboriginal Syllabics"). Falls
  back to `:standard` when unavailable.

* `:stand_alone` — a stand-alone form when the script name
  differs from its combined form (e.g., "Simplified Han"
  instead of "Simplified"). Falls back to `:standard` when
  unavailable.

* `:variant` — an alternative variant name (e.g.,
  "Perso-Arabic" instead of "Arabic"). Falls back to
  `:standard` when unavailable.

# `available_scripts`

```elixir
@spec available_scripts(Keyword.t()) :: {:ok, [atom()]} | {:error, Exception.t()}
```

Returns a sorted list of script codes available in a locale.

### Arguments

* `options` is a keyword list of options.

### Options

* `:locale` is a locale identifier. The default is
  `Localize.get_locale()`.

### Returns

* `{:ok, codes}` where `codes` is a sorted list of script
  code atoms.

* `{:error, exception}` if the locale data cannot be loaded.

### Examples

    iex> {:ok, codes} = Localize.Script.available_scripts()
    iex> :Latn in codes
    true

# `display_name`

```elixir
@spec display_name(atom() | String.t(), Keyword.t()) ::
  {:ok, String.t()} | {:error, Exception.t()}
```

Returns the localized display name for a script code.

### Arguments

* `script` is a script code atom or string (e.g., `:Latn`,
  `"Cyrl"`).

* `options` is a keyword list of options.

### Options

* `:locale` is a locale identifier. The default is
  `Localize.get_locale()`.

* `:style` is one of `:standard`, `:short`, `:stand_alone`,
  or `:variant`. The default is `:standard`. If the requested
  style is not available for a script, falls back to
  `:standard`.

* `:fallback` is a boolean. When `true` and the script
  is not found in the specified locale, falls back to the
  default locale. The default is `false`.

### Returns

* `{:ok, name}` where `name` is the localized script name.

* `{:error, exception}` if the script code is not found
  in the locale.

### Examples

    iex> Localize.Script.display_name(:Latn)
    {:ok, "Latin"}

    iex> Localize.Script.display_name("Cyrl")
    {:ok, "Cyrillic"}

    iex> Localize.Script.display_name(:Hans, style: :stand_alone)
    {:ok, "Simplified Han"}

    iex> Localize.Script.display_name(:Arab, style: :variant)
    {:ok, "Perso-Arabic"}

# `display_name!`

```elixir
@spec display_name!(atom() | String.t(), Keyword.t()) :: String.t()
```

Same as `display_name/2` but raises on error.

### Examples

    iex> Localize.Script.display_name!(:Latn)
    "Latin"

    iex> Localize.Script.display_name!(:Hans, style: :stand_alone)
    "Simplified Han"

# `known_scripts`

```elixir
@spec known_scripts(Keyword.t()) ::
  {:ok, %{required(atom()) => map()}} | {:error, Exception.t()}
```

Returns a map of all script codes to their localized names
in a locale.

### Arguments

* `options` is a keyword list of options.

### Options

* `:locale` is a locale identifier. The default is
  `Localize.get_locale()`.

### Returns

* `{:ok, scripts_map}` where `scripts_map` is a map of
  `%{script_atom => %{standard: name, ...}}`.

* `{:error, exception}` if the locale data cannot be loaded.

### Examples

    iex> {:ok, scripts} = Localize.Script.known_scripts()
    iex> scripts[:Latn]
    %{standard: "Latin"}

---

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