# `Localize.Locale.Provider.Cache`
[🔗](https://github.com/elixir-localize/localize/blob/v0.6.0/lib/localize/locale/provider/cache.ex#L1)

On-disk cache for downloaded locale data files.

This module is responsible for reading and writing locale ETF
files under the directory returned by
`Localize.Locale.Provider.locale_cache_dir/0`, and for detecting
when a cached file is stale relative to `Localize.version/0`.

## Primary API

* `get/1` — returns cached locale data, or an error tuple if the
  file is missing or stale.

* `store/2` — writes locale data to the cache directory.

* `stale?/1` — checks whether a cached locale file is stale.

* `path/1` — returns the absolute path for a locale's cache file.

# `locale_id`

```elixir
@type locale_id() :: atom()
```

A locale identifier as an atom.

# `get`

```elixir
@spec get(locale_id()) :: {:ok, map()} | {:error, Exception.t()}
```

Retrieves locale data from the cache directory.

Reads the locale's cache file, decodes it, and validates that
its `:version` field matches `Localize.version/0`.

### Arguments

* `locale_id` is a locale identifier atom.

### Returns

* `{:ok, locale_data}` if the cache file is present and its
  version matches the current version.

* `{:error, Localize.LocaleIsStaleError.t()}` if the cache file
  is present but its version does not match.

* `{:error, Localize.LocaleNotFoundInCacheError.t()}` if the
  cache file is not present.

# `path`

```elixir
@spec path(locale_id()) :: String.t()
```

Returns the absolute cache file path for the given locale.

### Arguments

* `locale_id` is a locale identifier atom.

### Returns

* A string path to the locale's cache file.

### Examples

    iex> path = Localize.Locale.Provider.Cache.path(:en)
    iex> String.ends_with?(path, "en.etf")
    true

# `stale?`

```elixir
@spec stale?(locale_id()) :: boolean()
```

Returns whether a cached locale file is stale.

A cache file is considered stale if its `:version` field does
not equal `Localize.version/0`. A file that is missing or
unreadable is also considered stale.

### Arguments

* `locale_id` is a locale identifier atom.

### Returns

* `true` if the cache file is missing, unreadable, or its
  version does not match `Localize.version/0`.

* `false` if the cache file is present and its version matches.

# `store`

```elixir
@spec store(locale_id(), binary()) :: {:ok, String.t()} | {:error, Exception.t()}
```

Stores locale content in the cache directory.

Creates the cache directory if it does not already exist and
writes `content` to the locale's cache file. `content` should
be the raw binary form of the locale ETF file.

### Arguments

* `locale_id` is a locale identifier atom.

* `content` is a binary containing the encoded locale data.

### Returns

* `{:ok, path}` where `path` is the absolute path the content
  was written to.

* `{:error, Localize.LocaleCacheWriteError.t()}` on failure.

---

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