# `Localize.Ecto.TextSearch`
[🔗](https://github.com/elixir-localize/localize_sql/blob/v1.0.1/lib/localize/ecto/text_search.ex#L1)

Resolves a locale to the best matching PostgreSQL text search configuration.

PostgreSQL's full-text search stems and filters words per language via a `regconfig` such as `'french'` or `'german'`. This module maps a `t:Localize.LanguageTag.t/0` (or any locale identifier accepted by `Localize.validate_locale/1`) to the built-in configuration for its language, falling back to the language-agnostic `'simple'` configuration when PostgreSQL has no stemmer for the language.

The mapping is by the language subtag after locale validation, so regional and script variants resolve to their language's configuration — `"pt-BR"` to `'portuguese'`, `"zh-Hant-TW"` to `'simple'` (PostgreSQL has no Chinese stemmer).

The primary public API is `config_for/2` and `config_for!/2`, used by the `Localize.Ecto.ts_match/2,3` query macro.

# `config_for`

```elixir
@spec config_for(Localize.locale() | String.t(), Keyword.t()) ::
  {:ok, String.t()} | {:error, Exception.t()}
```

Returns the PostgreSQL text search configuration for a locale.

### Arguments

* `locale` is a `t:Localize.LanguageTag.t/0`, or any locale identifier accepted by `Localize.validate_locale/1`. The default is `Localize.get_locale/0`.

* `options` is a keyword list of options.

### Options

* `:available` is a list of configuration names to restrict resolution to — for example the rows of `SELECT cfgname FROM pg_ts_config` when custom configurations replace the built-ins. A language whose configuration is not in the list falls back to `"simple"`.

### Returns

* `{:ok, config_name}` such as `{:ok, "german"}`, or

* `{:error, exception}` if `locale` is not a valid locale.

### Examples

    iex> Localize.Ecto.TextSearch.config_for("de-AT")
    {:ok, "german"}

    iex> Localize.Ecto.TextSearch.config_for("pt-BR")
    {:ok, "portuguese"}

    iex> Localize.Ecto.TextSearch.config_for("ja")
    {:ok, "simple"}

    iex> Localize.Ecto.TextSearch.config_for("en", available: ["simple"])
    {:ok, "simple"}

# `config_for!`

```elixir
@spec config_for!(Localize.locale() | String.t(), Keyword.t()) :: String.t()
```

Returns the PostgreSQL text search configuration for a locale or raises.

### Arguments

* `locale` is a `t:Localize.LanguageTag.t/0`, or any locale identifier accepted by `Localize.validate_locale/1`. The default is `Localize.get_locale/0`.

* `options` is a keyword list of options. See `config_for/2`.

### Returns

* A configuration name string such as `"german"`.

### Examples

    iex> Localize.Ecto.TextSearch.config_for!("fr-CA")
    "french"

---

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