Localize.Inflection.ConceptList (Localize v1.4.0)

An and/or list of concepts rendered with locale-correct conjunctions.

This is the port of the upstream SemanticConceptList and the createAndList/createOrList factories. Separators derive from Localize's own CLDR list patterns, and language-specific conjunction rules are applied on top: Spanish y becomes e before an i-sound (with the diphthong exception), Italian e becomes ed before a vowel, Hebrew prefixes ו directly to Hebrew words but hyphenates Latin ones, and the Korean particle 과/와 follows the sound of the preceding word.

Constraints put on the list propagate to every member, so an and-list of nouns can be pluralized or case-marked as a unit. Lists nest: a ConceptList can be a member of another ConceptList.

Summary

Types

t()

Functions

and_list(locale, concepts)

Builds an and-list of concepts.

exists?(arg1)

Returns true when the list has at least one member.

feature_value(list, name)

Returns the value of a feature for the list.

or_list(locale, concepts)

Builds an or-list of concepts.

plain_list(locale, concepts)

Builds a plain list of concepts, with no conjunction and no separators, as the upstream SemanticConceptList constructor does. Separators are then set with put_separator/3.

put_avoid_affix_redundancy(list, avoid?)

Sets whether an item that already starts with the item prefix, or ends with the item suffix, is left without another.

put_constraint(list, name, value)

Puts a constraint on every member and records it on the list.

put_separator(list, field, value)

Sets a separator field.

size(list)

Returns the number of members.

to_speakable_string(list)

Renders the list with locale-correct separators.

Types

t()

@type t() :: %Localize.Inflection.ConceptList{
  after_first: term(),
  after_last: term(),
  avoid_affix_redundancy: term(),
  before_first: term(),
  before_last: term(),
  concepts: term(),
  conjunction: term(),
  conjunction_kind: term(),
  item_delimiter: term(),
  item_prefix: term(),
  item_suffix: term(),
  locale: term()
}

Functions

and_list(locale, concepts)

Builds an and-list of concepts.

Arguments

locale is a locale atom or string, canonically BCP47.
concepts is a list of Localize.Inflection.Concept or nested Localize.Inflection.ConceptList members; nil members are dropped.

Returns

{:ok, list} or {:error, exception} when the locale's list patterns are unavailable.

Examples

iex> {:ok, jane} = Localize.Inflection.Concept.new(:es, "Jane")
iex> {:ok, ivan} = Localize.Inflection.Concept.new(:es, "Ivan")
iex> {:ok, list} = Localize.Inflection.ConceptList.and_list(:es, [jane, ivan])
iex> Localize.Inflection.ConceptList.to_speakable_string(list)
"Jane e Ivan"

iex> concepts =
...>   for word <- ["gato", "gata"] do
...>     {:ok, concept} = Localize.Inflection.Concept.new(:es, word)
...>     concept
...>   end
iex> {:ok, list} = Localize.Inflection.ConceptList.and_list(:es, concepts)
iex> {:ok, list} = Localize.Inflection.ConceptList.put_constraint(list, :number, :plural)
iex> Localize.Inflection.ConceptList.to_speakable_string(list)
"gatos y gatas"

exists?(arg1)

Returns true when the list has at least one member.

Arguments

list is a concept list.

Returns

true when the list has a member, and false when it is empty or is not a concept list.

Examples

iex> {:ok, list} = Localize.Inflection.ConceptList.and_list(:es, [])
iex> Localize.Inflection.ConceptList.exists?(list)
false

feature_value(list, name)

Returns the value of a feature for the list.

A grammatical category (number, gender, case, ...) returns the first member's value; a display feature renders the whole list with each member replaced by its feature value.

Arguments

list is a concept list.
name is the feature, such as :number.

Returns

The feature's value, or nil when the list is empty or is not a concept list.

Examples

iex> concepts =
...>   for word <- ["Jane", "Omar"] do
...>     {:ok, concept} = Localize.Inflection.Concept.new(:es, word)
...>     concept
...>   end
iex> {:ok, list} = Localize.Inflection.ConceptList.and_list(:es, concepts)
iex> Localize.Inflection.ConceptList.feature_value(list, :number)
:singular

or_list(locale, concepts)

Builds an or-list of concepts.

Arguments

locale is a locale atom or string, canonically BCP47.
concepts is a list of Localize.Inflection.Concept or nested Localize.Inflection.ConceptList members; nil members are dropped.

Returns

{:ok, list} or {:error, exception} when the locale's list patterns are unavailable.

Examples

iex> concepts =
...>   for word <- ["Jane", "Omar"] do
...>     {:ok, concept} = Localize.Inflection.Concept.new(:es, word)
...>     concept
...>   end
iex> {:ok, list} = Localize.Inflection.ConceptList.or_list(:es, concepts)
iex> Localize.Inflection.ConceptList.to_speakable_string(list)
"Jane u Omar"

plain_list(locale, concepts)

Builds a plain list of concepts, with no conjunction and no separators, as the upstream SemanticConceptList constructor does. Separators are then set with put_separator/3.

Arguments

locale is a locale atom or string, canonically BCP47.
concepts is a list of Localize.Inflection.Concept or nested Localize.Inflection.ConceptList members; nil members are dropped.

Returns

{:ok, list} or {:error, exception} when a member is not a concept.

Examples

iex> concepts =
...>   for word <- ["gatos", "idiomas"] do
...>     {:ok, concept} = Localize.Inflection.Concept.new(:es, word)
...>     concept
...>   end
iex> {:ok, list} = Localize.Inflection.ConceptList.plain_list(:es, concepts)
iex> Localize.Inflection.ConceptList.to_speakable_string(list)
"gatosidiomas"

put_avoid_affix_redundancy(list, avoid?)

Sets whether an item that already starts with the item prefix, or ends with the item suffix, is left without another.

Arguments

list is a concept list.
avoid? is true, the default for every list, or false.

Returns

The updated list, or {:error, exception} when list is not a concept list or avoid? is not a boolean.

Examples

iex> concepts =
...>   for word <- ["[gato]", "gata"] do
...>     {:ok, concept} = Localize.Inflection.Concept.new(:es, word)
...>     concept
...>   end
iex> {:ok, list} = Localize.Inflection.ConceptList.plain_list(:es, concepts)
iex> list =
...>   list
...>   |> Localize.Inflection.ConceptList.put_separator(:item_prefix, "[")
...>   |> Localize.Inflection.ConceptList.put_separator(:item_suffix, "]")
iex> Localize.Inflection.ConceptList.to_speakable_string(list)
"[gato][gata]"
iex> list
...> |> Localize.Inflection.ConceptList.put_avoid_affix_redundancy(false)
...> |> Localize.Inflection.ConceptList.to_speakable_string()
"[[gato]][gata]"

put_constraint(list, name, value)

Puts a constraint on every member and records it on the list.

Arguments

list is a concept list.
name is a grammatical feature, such as :number or :gender.
value is the feature's value, such as :plural.

Returns

{:ok, list} with every member constrained, or
{:error, exception} when a member cannot take the constraint or list is not a concept list.

Examples

iex> concepts =
...>   for word <- ["Jane", "Omar"] do
...>     {:ok, concept} = Localize.Inflection.Concept.new(:es, word)
...>     concept
...>   end
iex> {:ok, list} = Localize.Inflection.ConceptList.and_list(:es, concepts)
iex> {:ok, list} = Localize.Inflection.ConceptList.put_constraint(list, :number, :plural)
iex> Localize.Inflection.ConceptList.to_speakable_string(list)
"Janes y Omares"

put_separator(list, field, value)

Sets a separator field.

Arguments

list is a concept list.
field is one of :before_first, :after_first, :item_delimiter, :before_last, :after_last, :item_prefix or :item_suffix.
value is the separator as a speakable string; the empty string unsets the field, re-enabling any language-specific dynamic conjunction.

Returns

The concept list with the field set, or
{:error, exception} when field is not a separator field or list is not a concept list.

Examples

iex> concepts =
...>   for word <- ["Jane", "Omar"] do
...>     {:ok, concept} = Localize.Inflection.Concept.new(:es, word)
...>     concept
...>   end
iex> {:ok, list} = Localize.Inflection.ConceptList.plain_list(:es, concepts)
iex> list = Localize.Inflection.ConceptList.put_separator(list, :item_delimiter, " / ")
iex> Localize.Inflection.ConceptList.to_speakable_string(list)
"Jane / Omar"

size(list)

Returns the number of members.

Arguments

list is a concept list.

Returns

The number of members, or
{:error, exception} when list is not a concept list.

Examples

iex> concepts =
...>   for word <- ["Jane", "Omar"] do
...>     {:ok, concept} = Localize.Inflection.Concept.new(:es, word)
...>     concept
...>   end
iex> {:ok, list} = Localize.Inflection.ConceptList.and_list(:es, concepts)
iex> Localize.Inflection.ConceptList.size(list)
2

to_speakable_string(list)

Renders the list with locale-correct separators.

Arguments

list is a concept list.

Returns

A speakable string, or nil when the list is empty, or
{:error, exception} when list is not a concept list.

Examples

iex> concepts =
...>   for word <- ["Jane", "Omar"] do
...>     {:ok, concept} = Localize.Inflection.Concept.new(:es, word)
...>     concept
...>   end
iex> {:ok, list} = Localize.Inflection.ConceptList.and_list(:es, concepts)
iex> Localize.Inflection.ConceptList.to_speakable_string(list)
"Jane y Omar"