# `Localize.Inflection.PronounConcept`
[🔗](https://github.com/elixir-localize/localize/blob/v1.4.0/lib/localize/inflection/pronoun_concept.ex#L1)

A pronoun with grammatical constraints.

The locale pronoun table (ported from the upstream
`pronoun_XX.csv` resources) maps each pronoun surface form to its
grammatical constraints. Constraints put on the concept select
the matching pronoun; an initial pronoun seeds default
constraints so that reinflection ("they" with `gender=masculine`
becomes "he") preserves unconstrained properties.

This is the equivalent of the upstream `PronounConcept`.

# `t`

```elixir
@type t() :: %Localize.Inflection.PronounConcept{
  constraints: %{optional(binary()) => binary()},
  custom_count: non_neg_integer(),
  default_constraints: %{optional(binary()) => binary()},
  default_index: non_neg_integer() | nil,
  entries: [{binary(), %{optional(binary()) => binary()}}],
  locale: atom(),
  table_locale: binary()
}
```

# `clear_constraint`

Removes a constraint from the concept.

### Arguments

* `concept` is a pronoun concept from `new/2`.

* `name` is the grammatical feature to remove, such as `:person`.

### Returns

* The concept without the constraint, or

* `{:error, exception}` when `concept` is not a pronoun concept.

### Examples

    iex> {:ok, concept} = Localize.Inflection.PronounConcept.new(:en)
    iex> {:ok, concept} = Localize.Inflection.PronounConcept.put_constraint(concept, :person, :first)
    iex> concept |> Localize.Inflection.PronounConcept.clear_constraint(:person) |> Localize.Inflection.PronounConcept.to_speakable_string()
    "they"

# `custom_match?`

Returns true when a custom display-data entry matches the
constraints.

### Arguments

* `concept` is a pronoun concept from `new/2`.

### Returns

* `true` when an entry of the concept's `:display_data` matches,
  and `false` otherwise or when `concept` is not a pronoun concept.

### Examples

    iex> {:ok, concept} =
    ...>   Localize.Inflection.PronounConcept.new(:en,
    ...>     display_data: [{"xe", %{person: :third, number: :singular}}]
    ...>   )
    iex> {:ok, third} = Localize.Inflection.PronounConcept.put_constraint(concept, :person, :third)
    iex> Localize.Inflection.PronounConcept.custom_match?(third)
    true
    iex> {:ok, first} = Localize.Inflection.PronounConcept.put_constraint(concept, :person, :first)
    iex> Localize.Inflection.PronounConcept.custom_match?(first)
    false

# `exists?`

Returns true when a pronoun matches the constraints without
falling back to the default entry.

### Arguments

* `concept` is a pronoun concept from `new/2`.

### Returns

* `true` when a pronoun matches, and `false` otherwise or when
  `concept` is not a pronoun concept.

### Examples

    iex> {:ok, concept} = Localize.Inflection.PronounConcept.new(:en)
    iex> {:ok, concept} = Localize.Inflection.PronounConcept.put_constraint(concept, :person, :first)
    iex> Localize.Inflection.PronounConcept.exists?(concept)
    true

# `feature_value`

Returns the value of a feature for the currently selected
pronoun, or nil.

### Arguments

* `concept` is a pronoun concept from `new/2`.

* `name` is a feature name such as "gender".

### Returns

* The feature value string, or nil when the selected pronoun does
  not constrain the feature.

### Examples

    iex> {:ok, concept} = Localize.Inflection.PronounConcept.new(:en)
    iex> Localize.Inflection.PronounConcept.feature_value(concept, :case)
    :nominative

    iex> {:ok, concept} = Localize.Inflection.PronounConcept.new(:en)
    iex> Localize.Inflection.PronounConcept.feature_value(concept, :gender)
    nil

# `new`

Creates a pronoun concept for a locale.

### Arguments

* `locale` is a locale atom or string, canonically in BCP47 form
  (`:"zh-TW"`, `"zh-TW"`); the underscore form is also accepted.
  Regional locales fall back to their parent language for the
  feature model, and for the pronoun table unless the region has
  one of its own: `zh-TW` uses the Traditional Chinese table that
  ships with `zh`, and `zh-HK` the Cantonese (`yue`) table.

* `options` is a keyword list of options.

### Options

* `:initial_pronoun` is a pronoun surface form whose grammatical
  properties seed the default constraints (unambiguous properties
  only).

* `:display_data` is a list of `{word, constraints}` custom
  pronoun entries searched before the locale table.

* `:default_constraints` is a map of feature name to value used
  to break ties between otherwise equal matches.

### Returns

* `{:ok, concept}` on success.

* `{:error, reason}` when the locale has no pronoun table, the
  inflection data it needs (its own, or that of the language
  whose table it uses) has not been downloaded, or the initial
  pronoun is unknown.

### Examples

    iex> {:ok, concept} = Localize.Inflection.PronounConcept.new(:en)
    iex> Localize.Inflection.PronounConcept.to_speakable_string(concept)
    "they"

    iex> {:ok, concept} = Localize.Inflection.PronounConcept.new(:en, initial_pronoun: "him")
    iex> {:ok, concept} = Localize.Inflection.PronounConcept.put_constraint(concept, :case, :nominative)
    iex> Localize.Inflection.PronounConcept.to_speakable_string(concept)
    "he"

# `put_constraint`

Puts a constraint on the concept.

### Arguments

* `concept` is a pronoun concept from `new/2`.

* `name` is a feature name such as "person" or "case".

* `value` is the constraint value such as "third".

### Returns

* `{:ok, concept}` or `{:error, reason}` when the feature is
  unknown or the value is not valid for a bounded feature.

### Examples

    iex> {:ok, concept} = Localize.Inflection.PronounConcept.new(:en)
    iex> {:ok, concept} = Localize.Inflection.PronounConcept.put_constraint(concept, :person, :first)
    iex> Localize.Inflection.PronounConcept.to_speakable_string(concept)
    "I"

# `reset`

Removes all constraints from the concept.

### Arguments

* `concept` is a pronoun concept from `new/2`.

### Returns

* The concept without constraints, or

* `{:error, exception}` when `concept` is not a pronoun concept.

### Examples

    iex> {:ok, concept} = Localize.Inflection.PronounConcept.new(:en)
    iex> {:ok, concept} = Localize.Inflection.PronounConcept.put_constraint(concept, :person, :first)
    iex> concept |> Localize.Inflection.PronounConcept.reset() |> Localize.Inflection.PronounConcept.to_speakable_string()
    "they"

# `to_speakable_string`

Renders the selected pronoun.

### Arguments

* `concept` is a pronoun concept from `new/2`.

* `referenced_concept` is an optional `Localize.Inflection.Concept`
  the pronoun depends on (a possessee), used to satisfy
  `dependency=` constraints such as the French elision before a
  vowel.

### Returns

* A speakable string (a binary, or `{print, speak}`), or nil when
  no pronoun matches or `concept` is not a pronoun concept.

### Examples

    iex> {:ok, concept} = Localize.Inflection.PronounConcept.new(:en)
    iex> {:ok, concept} = Localize.Inflection.PronounConcept.put_constraint(concept, :person, :first)
    iex> Localize.Inflection.PronounConcept.to_speakable_string(concept)
    "I"

---

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