Localize.Inflection.PronounConcept (Localize v1.4.0)

Copy Markdown View Source

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.

Summary

Types

t()

Functions

clear_constraint(concept, name)

Removes a constraint from the concept.

custom_match?(concept)

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

exists?(concept)

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

feature_value(concept, name)

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

new(locale, options \\ [])

Creates a pronoun concept for a locale.

put_constraint(concept, name, value)

Puts a constraint on the concept.

reset(concept)

Removes all constraints from the concept.

to_speakable_string(concept, referenced_concept \\ nil)

Renders the selected pronoun.

Types

t()

@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()
}

Functions

clear_constraint(concept, name)

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?(concept)

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?(concept)

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(concept, name)

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(locale, options \\ [])

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(concept, name, value)

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(concept)

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(concept, referenced_concept \\ nil)

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"