Localize.Inflection.Concept (Localize v1.4.0)

An inflectable string with grammatical constraints.

A concept wraps a word or phrase for a locale. Constraints (such as number=plural or definiteness=definite) are applied with put_constraint/3; grammatical properties are queried with feature_value/2; and to_speakable_string/1 renders the phrase with all constraints applied.

A concept can also carry forms of its own for sets of constraints, given as :display_data to new/3. It then renders as the first of its forms that holds every constraint put on it, and otherwise as the locale's rules inflect the phrase.

This is the equivalent of the upstream InflectableStringConcept, and with display data of the upstream SemanticConcept.

Summary

Types

t()

Functions

exists?(concept)

Returns true when the concept can be rendered with its constraints without guessing.

feature_value(concept, name)

Returns the value of a feature for this concept.

new(locale, value, options \\ [])

Creates a concept for a word or phrase.

put_constraint(concept, name, value)

Puts a constraint on the concept.

to_speakable_string(concept)

Renders the concept with all constraints applied.

Types

t()

@type t() :: %Localize.Inflection.Concept{
  constraints: %{optional(binary()) => binary()},
  display_data: [
    {Localize.Inflection.SpeakableString.t(), %{optional(binary()) => binary()}}
  ],
  guess: boolean(),
  initial: %{optional(binary()) => binary()},
  locale: atom(),
  value: Localize.Inflection.SpeakableString.t()
}

Functions

exists?(concept)

Returns true when the concept can be rendered with its constraints without guessing.

Rendering without guessing includes the synthesizers' unchanged passthrough: a word the dictionary does not know may still render as itself, so exists?/1 answers "does rendering produce something?", not "is the requested form attested in the dictionary?". Use Localize.Inflection.known?/2 to test dictionary membership.

Arguments

concept is a concept from new/3.

Returns

true when rendering produces a form, and false otherwise or when concept is not a concept.

Examples

iex> {:ok, concept} = Localize.Inflection.Concept.new(:en, "cat", constraints: %{number: :plural})
iex> Localize.Inflection.Concept.exists?(concept)
true

feature_value(concept, name)

Returns the value of a feature for this concept.

A stored constraint takes precedence. A concept with display data next takes the value its rendered form has; otherwise the locale's default feature function computes the value from the (possibly inflected) display string.

Arguments

concept is a concept from new/3.
name is a feature name such as :number or "gender".

Returns

A speakable string, or nil when the feature has no value.

Examples

iex> {:ok, concept} = Localize.Inflection.Concept.new(:en, "light")
iex> Localize.Inflection.Concept.feature_value(concept, :number)
:singular

new(locale, value, options \\ [])

Creates a concept for a word or phrase.

Arguments

locale is a locale atom or string, canonically BCP47 (:en, "zh-TW"), for which data has been generated.
value is the word or phrase, either a binary or a {print, speak} tuple.
options is a keyword list of options.

Options

:constraints is a map of feature constraints to apply, as if set with put_constraint/3.
:initial is a map of features known to hold for the value itself (for example a known grammatical gender), used when deriving other features rather than requested for rendering.
:display_data is a list of {form, constraints} entries, forms of the concept and the features each has, such as {"octopodes", %{number: :plural}}. A form is a binary or a {print, speak} tuple. The concept renders as the first form, starting with value and its :initial features, that holds every constraint put on it, and takes its features from that form; when no form does, the locale's rules inflect value.

Returns

{:ok, concept} or {:error, reason} when the locale data is unavailable, or a constraint or display data entry is invalid.

Examples

iex> {:ok, concept} = Localize.Inflection.Concept.new(:en, "cat", constraints: %{number: :plural})
iex> Localize.Inflection.Concept.to_speakable_string(concept)
"cats"

iex> {:error, error} = Localize.Inflection.Concept.new(:en, "cat", constraints: %{number: :dual})
iex> error.value
"dual"
iex> error.allowed_values
["plural", "singular"]

iex> display_data = [{"octopodes", %{number: :plural}}]
iex> {:ok, concept} = Localize.Inflection.Concept.new(:en, "octopus", display_data: display_data)
iex> {:ok, concept} = Localize.Inflection.Concept.put_constraint(concept, :number, :plural)
iex> Localize.Inflection.Concept.to_speakable_string(concept)
"octopodes"

put_constraint(concept, name, value)

Puts a constraint on the concept.

Arguments

concept is a concept from new/3.
name is a feature name such as "number" or "definiteness".
value is the constraint value such as "plural".

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.Concept.new(:en, "light")
iex> {:ok, concept} = Localize.Inflection.Concept.put_constraint(concept, :number, :plural)
iex> Localize.Inflection.Concept.to_speakable_string(concept)
"lights"

to_speakable_string(concept)

Renders the concept with all constraints applied.

The synthesizers may fall back to suffix-exemplar guessing for words the dictionary does not know. Setting the concept's guess field to false disables guessing: forms then change only through attested dictionary paths, and a failed render returns the value unchanged.

Arguments

concept is a t/0, as new/3 returns it.

Returns

A speakable string (a binary, or {print, speak} when the spoken form differs).

Examples

iex> {:ok, concept} = Localize.Inflection.Concept.new(:en, "cat", constraints: %{case: :genitive})
iex> Localize.Inflection.Concept.to_speakable_string(concept)
"cat’s"