Literature (literature v0.3.4)

Provides the core functions to retrieve and manage the CLDR data that supports formatting and localisation.

It provides the core functions to access formatted CLDR data, set and retrieve a current locale and validate certain core data types such as locales, currencies and territories.

Summary

Functions

Returns an %Ecto.Changeset{} for tracking author changes.

Returns an %Ecto.Changeset{} for tracking post changes.

Returns an %Ecto.Changeset{} for tracking publication changes.

Returns an %Ecto.Changeset{} for tracking redirect changes.

Returns an %Ecto.Changeset{} for tracking tag changes.

Creates an author.

Creates a post.

Creates a publication.

Creates a redirect.

Creates a tag.

Returns the default locale.

Returns the default territory when a locale does not specify one and none can be inferred.

Deletes an author.

Deletes a post.

Deletes a publication.

Deletes a redirect.

Deletes a tag.

Add locale-specific ellipsis to a string.

Gets a single author.

Return the current locale to be used for Cldr functions that take an optional locale parameter for which a locale is not supplied.

Gets a single post.

Gets a single publication.

Gets a single redirect.

Gets a single tag.

Returns either the Gettext locale_name in Cldr format or false based upon whether the locale name is configured in Gettext.

Returns a boolean indicating if the specified locale name is configured and available in Gettext.

Returns a list of Gettext locale names but in CLDR format with underscore replaced by hyphen in order to facilitate comparisons with Cldr locale names.

Returns either the locale_name or false based upon whether the locale name is configured in Cldr.

Returns a boolean indicating if the specified locale name is configured and available in Cldr.

Returns a list of the known locale names.

Returns a list of atoms representing the number systems types known to Cldr.

Returns either the RBNF locale_name or false based upon whether the locale name is configured in Cldr and has RBNF rules defined.

Returns a boolean indicating if the specified locale name is configured and available in Cldr and supports rules based number formats (RBNF).

Returns a list of locale names which have rules-based number formats (RBNF).

Returns the list of authors.

Returns the list of posts.

Returns the list of publications.

Returns the list of redirects.

Returns the list of tags.

Normalizes a string by applying transliteration of common symbols in numbers, currencies and dates

Returns the paginate list of authors.

Returns the paginate list of posts.

Returns the paginate list of redirects.

Returns the paginate list of tags.

Set the current process's Gettext locale from a t:Cldr.LanguageTag.

Set the current locale to be used for Cldr functions that take an optional locale parameter for which a locale is not supplied.

Add locale-specific quotation marks around a string.

Returns a list of the locales names that are configured, but not known in CLDR.

Updates an author.

Updates a post.

Updates a redirect.

Updates a tag.

Normalise and validate a locale name.

Normalise and validate a number system type.

Execute a function with a locale ensuring that the current locale is restored after the function.

Functions

Link to this function

available_locale_name?(locale_name)

See Cldr.available_locale_name?/1.

Link to this function

build_params(map)

Link to this function

change_author(author, attrs \\ %{})

Returns an %Ecto.Changeset{} for tracking author changes.

Examples

iex> change_author(author)
%Ecto.Changeset{data: %Author{}}
Link to this function

change_post(post, attrs \\ %{})

Returns an %Ecto.Changeset{} for tracking post changes.

Examples

iex> change_post(post)
%Ecto.Changeset{data: %Post{}}
Link to this function

change_publication(publication, attrs \\ %{})

Returns an %Ecto.Changeset{} for tracking publication changes.

Examples

iex> change_publication(publication)
%Ecto.Changeset{data: %Publication{}}
Link to this function

change_redirect(redirect, attrs \\ %{})

Returns an %Ecto.Changeset{} for tracking redirect changes.

Examples

iex> change_redirect(redirect)
%Ecto.Changeset{data: %Redirect{}}
Link to this function

change_tag(tag, attrs \\ %{})

Returns an %Ecto.Changeset{} for tracking tag changes.

Examples

iex> change_tag(tag)
%Ecto.Changeset{data: %Tag{}}
Link to this function

create_author(attrs \\ %{})

Creates an author.

Examples

iex> create_author(%{field: value})
{:ok, %Author{}}

iex> create_author(%{field: bad_value})
{:error, %Ecto.Changeset{}}
Link to this function

create_post(attrs \\ %{})

Creates a post.

Examples

iex> create_post(%{field: value})
{:ok, %Post{}}

iex> create_post(%{field: bad_value})
{:error, %Ecto.Changeset{}}
Link to this function

create_publication(attrs \\ %{})

Creates a publication.

Examples

iex> create_publication(%{field: value})
{:ok, %Publication{}}

iex> create_publication(%{field: bad_value})
{:error, %Ecto.Changeset{}}
Link to this function

create_redirect(attrs \\ %{})

Creates a redirect.

Examples

iex> create_redirect(%{field: value})
{:ok, %Redirect{}}

iex> create_redirect(%{field: bad_value})
{:error, %Ecto.Changeset{}}
Link to this function

create_tag(attrs \\ %{})

Creates a tag.

Examples

iex> create_tag(%{field: value})
{:ok, %Tag{}}

iex> create_tag(%{field: bad_value})
{:error, %Ecto.Changeset{}}
Link to this function

default_locale()

@spec default_locale() :: Cldr.LanguageTag.t() | no_return()

Returns the default locale.

Example

iex> Literature.default_locale()
%Cldr.LanguageTag{
  backend: Literature,
  canonical_locale_name: "en-001",
  cldr_locale_name: :"en-001",
  language_subtags: [],
  extensions: %{},
  gettext_locale_name: "en",
  language: "en",
  locale: %{},
  private_use: [],
  rbnf_locale_name: :en,
  requested_locale_name: "en-001",
  script: :Latn,
  territory: :"001",
  transform: %{},
  language_variants: []
}
Link to this function

default_territory()

@spec default_territory() :: Cldr.Locale.territory_code()

Returns the default territory when a locale does not specify one and none can be inferred.

Example

iex> Literature.default_territory()
:"001"
Link to this function

delete_author(author)

Deletes an author.

Examples

iex> delete_author(author)
{:ok, %Author{}}

iex> delete_author(author)
{:error, %Ecto.Changeset{}}
Link to this function

delete_post(post)

Deletes a post.

Examples

iex> delete_post(post)
{:ok, %Post{}}

iex> delete_post(post)
{:error, %Ecto.Changeset{}}
Link to this function

delete_publication(publication)

Deletes a publication.

Examples

iex> delete_publication(publication)
{:ok, %Publication{}}

iex> delete_publication(publication)
{:error, %Ecto.Changeset{}}
Link to this function

delete_redirect(redirect)

Deletes a redirect.

Examples

iex> delete_redirect(redirect)
{:ok, %Redirect{}}

iex> delete_redirect(redirect)
{:error, %Ecto.Changeset{}}
Link to this function

delete_tag(tag)

Deletes a tag.

Examples

iex> delete_tag(tag)
{:ok, %Tag{}}

iex> delete_tag(tag)
{:error, %Ecto.Changeset{}}
Link to this function

ellipsis(string, options \\ [])

@spec ellipsis(String.t() | [String.t()], Keyword.t()) :: String.t()

Add locale-specific ellipsis to a string.

Arguments

  • string is any String.t or a 2-element list of String.t between which the ellipsis is inserted.

  • backend is any module that includes use Cldr and therefore is a Cldr backend module. The default is Cldr.default_backend!/0. Note that Cldr.default_backend!/0 will raise an exception if no :default_backend is configured under the :ex_cldr key in config.exs.

  • options is a keyword list of options

Options

  • :locale is any valid locale name returned by Cldr.known_locale_names/1. The default is Cldr.get_locale/0.

  • :location determines where to place the ellipsis. The options are :after (the default for a single string argument), :between (the default and only valid location for an argument that is a list of two strings) and :before.

  • :format formats based upon whether the ellipsis is inserted between words or sentences. The valid options are :word or :sentence. The default is :sentence.

Examples

iex> Literature.ellipsis("And furthermore")
"And furthermore…"

iex> Literature.ellipsis(["And furthermore", "there is much to be done"], locale: :ja)
"And furthermore…there is much to be done"

iex> Literature.ellipsis("And furthermore", format: :word)
"And furthermore …"

iex> Literature.ellipsis(["And furthermore", "there is much to be done"], locale: :ja, format: :word)
"And furthermore … there is much to be done"
Link to this function

get_author!(id)

Gets a single author.

Raises Ecto.NoResultsError if the Author does not exist.

Examples

iex> get_author!(123)
%Author{}

iex> get_author!(456)
** (Ecto.NoResultsError)
@spec get_locale() :: Cldr.LanguageTag.t()

Return the current locale to be used for Cldr functions that take an optional locale parameter for which a locale is not supplied.

Example

iex> Literature.put_locale("pl")
iex> Literature.get_locale()
%Cldr.LanguageTag{
   backend: Elixir.Literature,
   canonical_locale_name: "pl",
   cldr_locale_name: :pl,
   extensions: %{},
   language: "pl",
   locale: %{},
   private_use: [],
   rbnf_locale_name: :pl,
   territory: :PL,
   requested_locale_name: "pl",
   script: :Latn,
   transform: %{},
   language_variants: []
 }

Gets a single post.

Raises Ecto.NoResultsError if the Post does not exist.

Examples

iex> get_post!(123)
%Post{}

iex> get_post!(456)
** (Ecto.NoResultsError)
Link to this function

get_publication!(id)

Gets a single publication.

Raises Ecto.NoResultsError if the Publication does not exist.

Examples

iex> get_publication!(123)
%Publication{}

iex> get_publication!(456)
** (Ecto.NoResultsError)
Link to this function

get_redirect!(id)

Gets a single redirect.

Raises Ecto.NoResultsError if the Redirect does not exist.

Examples

iex> get_redirect!(123)
%Redirect{}

iex> get_redirect!(456)
** (Ecto.NoResultsError)

Gets a single tag.

Raises Ecto.NoResultsError if the Tag does not exist.

Examples

iex> get_tag!(123)
%Tag{}

iex> get_tag!(456)
** (Ecto.NoResultsError)
Link to this function

known_calendars()

See Cldr.known_calendars/0.

Link to this function

known_currencies()

See Cldr.known_currencies/0.

Link to this function

known_gettext_locale_name(locale_name)

@spec known_gettext_locale_name(String.t()) :: String.t() | false

Returns either the Gettext locale_name in Cldr format or false based upon whether the locale name is configured in Gettext.

Arguments

Examples

iex> Literature.known_gettext_locale_name("en")
"en"

iex> Literature.known_gettext_locale_name("en-SA")
false
Link to this function

known_gettext_locale_name?(locale_name)

@spec known_gettext_locale_name?(String.t()) :: boolean()

Returns a boolean indicating if the specified locale name is configured and available in Gettext.

Arguments

Examples

iex> Literature.known_gettext_locale_name?("en")
true

iex> Literature.known_gettext_locale_name?("!!")
false
Link to this function

known_gettext_locale_names()

@spec known_gettext_locale_names() :: [String.t()]

Returns a list of Gettext locale names but in CLDR format with underscore replaced by hyphen in order to facilitate comparisons with Cldr locale names.

Link to this function

known_locale_name(locale_name)

@spec known_locale_name(Cldr.Locale.locale_name()) :: String.t() | false

Returns either the locale_name or false based upon whether the locale name is configured in Cldr.

This is helpful when building a list of or expressions to return the first known locale name from a list.

Arguments

Examples

iex> Literature.known_locale_name(:"en-AU")
:"en-AU"

iex> Literature.known_locale_name(:"en-SA")
false
Link to this function

known_locale_name?(locale_name)

@spec known_locale_name?(Cldr.Locale.locale_name()) :: boolean()

Returns a boolean indicating if the specified locale name is configured and available in Cldr.

Arguments

Examples

iex> Literature.known_locale_name?(:en)
true

iex> Literature.known_locale_name?(:"!!")
false
Link to this function

known_locale_names()

Returns a list of the known locale names.

Known locales are those locales which are the subset of all CLDR locales that have been configured for use either in this module or in Gettext.

Link to this function

known_number_system_types()

Returns a list of atoms representing the number systems types known to Cldr.

Example

iex> Literature.known_number_system_types()
[:default, :finance, :native, :traditional]
Link to this function

known_number_systems()

See Cldr.known_number_systems/0.

Link to this function

known_rbnf_locale_name(locale_name)

@spec known_rbnf_locale_name(Cldr.Locale.locale_name()) :: String.t() | false

Returns either the RBNF locale_name or false based upon whether the locale name is configured in Cldr and has RBNF rules defined.

Arguments

Examples

iex> Literature.known_rbnf_locale_name(:en)
:en

iex> Literature.known_rbnf_locale_name(:"en-SA")
false
Link to this function

known_rbnf_locale_name?(locale_name)

@spec known_rbnf_locale_name?(Cldr.Locale.locale_name()) :: boolean()

Returns a boolean indicating if the specified locale name is configured and available in Cldr and supports rules based number formats (RBNF).

Arguments

Examples

iex> Literature.known_rbnf_locale_name?(:en)
true

iex> Literature.known_rbnf_locale_name?(:"!!")
false
Link to this function

known_rbnf_locale_names()

@spec known_rbnf_locale_names() :: [Cldr.Locale.locale_name()]

Returns a list of locale names which have rules-based number formats (RBNF).

Link to this function

known_territories()

See Cldr.known_territories/0.

Link to this function

list_authors(attrs \\ [])

Returns the list of authors.

Examples

iex> list_authors()
[%Author{}, ...]
Link to this function

list_posts(attrs \\ [])

Returns the list of posts.

Examples

iex> list_posts()
[%Post{}, ...]
Link to this function

list_publications(attrs \\ [])

Returns the list of publications.

Examples

iex> list_publications()
[%Publication{}, ...]
Link to this function

list_redirects(attrs \\ [])

Returns the list of redirects.

Examples

iex> list_redirects()
[%Redirect{}, ...]
Link to this function

list_tags(attrs \\ [])

Returns the list of tags.

Examples

iex> list_tags()
[%Tag{}, ...]
Link to this function

normalize_lenient_parse(string, scope, locale \\ get_locale())

Normalizes a string by applying transliteration of common symbols in numbers, currencies and dates

Link to this function

paginate_authors(attrs \\ [])

Returns the paginate list of authors.

Examples

iex> paginate_authors()
%Scrivener.Page{entries: [%Author{}, ...], ...}
Link to this function

paginate_posts(attrs \\ [])

Returns the paginate list of posts.

Examples

iex> paginate_posts()
%Scrivener.Page{entries: [%Post{}, ...], ...}
Link to this function

paginate_redirects(attrs \\ [])

Returns the paginate list of redirects.

Examples

iex> paginate_redirects()
%Scrivener.Page{entries: [%Redirect{}, ...], ...}
Link to this function

paginate_tags(attrs \\ [])

Returns the paginate list of tags.

Examples

iex> paginate_tags()
%Scrivener.Page{entries: [%Tag{}, ...], ...}
Link to this function

preload_tag_posts_with_position(tag_ids, status \\ nil)

Link to this function

put_gettext_locale(locale)

(since 2.38.0)
@spec put_gettext_locale(Cldr.LanguageTag.t()) ::
  {:ok, binary() | nil} | {:error, {module(), String.t()}}

Set the current process's Gettext locale from a t:Cldr.LanguageTag.

Arguments

Returns

  • {:ok, gettext_locale_name} or

  • {:error, {exception, reason}}

Behaviour

  1. If the locale.gettext_locale_name is nil then an error is returned.

  2. The gettext locale for the gettext_backend configured for the CLDR backend defined by the t:Cldr.LanguageTag is set.

Examples

iex> import Cldr.LanguageTag.Sigil
iex> Literature.put_gettext_locale(~l"en")
{:ok, "en"}

iex> import Cldr.LanguageTag.Sigil
iex> Literature.put_gettext_locale(~l"de")
{
  :error,
  {
    Cldr.UnknownLocaleError,
    "Locale TestBackend.Cldr.Locale.new!(\"de-DE\") does not map to a known gettext locale name"
  }
}
Link to this function

put_locale(locale_name)

@spec put_locale(Cldr.Locale.locale_reference()) ::
  {:ok, Cldr.LanguageTag.t()} | {:error, {module(), String.t()}}

Set the current locale to be used for Cldr functions that take an optional locale parameter for which a locale is not supplied.

Arguments

See rfc5646 for the specification of a language tag.

Examples

iex> Literature.put_locale("en")
{:ok,
 %Cldr.LanguageTag{
   backend: Literature,
   canonical_locale_name: "en",
   cldr_locale_name: :en,
   language_subtags: [],
   extensions: %{},
   gettext_locale_name: "en",
   language: "en",
   locale: %{},
   private_use: [],
   rbnf_locale_name: :en,
   requested_locale_name: "en",
   script: :Latn,
   territory: :US,
   transform: %{},
   language_variants: []
 }}

iex> Literature.put_locale("invalid-locale!")
{:error, {Cldr.LanguageTag.ParseError,
  "Expected a BCP47 language tag. Could not parse the remaining \"!\" starting at position 15"}}
Link to this function

quote(string, options \\ [])

@spec quote(String.t(), Keyword.t()) :: String.t()

Add locale-specific quotation marks around a string.

Arguments

  • string is any valid Elixir string

  • options is a keyword list of options

Options

Examples

iex> Literature.quote("Quoted String")
"“Quoted String”"

iex> Literature.quote("Quoted String", locale: :ja)
"「Quoted String」"
Link to this function

sort_tag_posts(post_ids, tag_id)

Link to this function

unknown_locale_names()

@spec unknown_locale_names() :: [Cldr.Locale.locale_name()]

Returns a list of the locales names that are configured, but not known in CLDR.

Since there is a compile-time exception raised if there are any unknown locales this function should always return an empty list.

Link to this function

update_author(author, attrs)

Updates an author.

Examples

iex> update_author(author, %{field: new_value})
{:ok, %Author{}}

iex> update_author(author, %{field: bad_value})
{:error, %Ecto.Changeset{}}
Link to this function

update_post(post, attrs)

Updates a post.

Examples

iex> update_post(post, %{field: new_value})
{:ok, %Post{}}

iex> update_post(post, %{field: bad_value})
{:error, %Ecto.Changeset{}}
Link to this function

update_publication(publication, attrs)

Updates a publication.

Examples

iex> update_publication(publication, %{field: new_value})
{:ok, %Publication{}}

iex> update_publication(publication, %{field: bad_value})
{:error, %Ecto.Changeset{}}
Link to this function

update_redirect(redirect, attrs)

Updates a redirect.

Examples

iex> update_redirect(redirect, %{field: new_value})
{:ok, %Redirect{}}

iex> update_redirect(redirect, %{field: bad_value})
{:error, %Ecto.Changeset{}}
Link to this function

update_tag(tag, attrs)

Updates a tag.

Examples

iex> update_tag(tag, %{field: new_value})
{:ok, %Tag{}}

iex> update_tag(tag, %{field: bad_value})
{:error, %Ecto.Changeset{}}
Link to this function

validate_calendar(calendar)

See Cldr.validate_calendar/1.

Link to this function

validate_currency(currency)

See Cldr.validate_currency/1.

Link to this function

validate_locale(locale)

@spec validate_locale(Cldr.Locale.locale_name() | Cldr.LanguageTag.t() | String.t()) ::
  {:ok, Cldr.LanguageTag.t()} | {:error, {module(), String.t()}}

Normalise and validate a locale name.

Arguments

Returns

  • {:ok, language_tag}

  • {:error, reason}

Notes

See rfc5646 for the specification of a language tag.

Examples

iex> Literature.validate_locale(:en)
{:ok,
%Cldr.LanguageTag{
  backend: Literature,
  canonical_locale_name: "en",
  cldr_locale_name: :en,
  extensions: %{},
  gettext_locale_name: "en",
  language: "en",
  locale: %{},
  private_use: [],
  rbnf_locale_name: :en,
  requested_locale_name: "en",
  script: :Latn,
  territory: :US,
  transform: %{},
  language_variants: []
}}


iex> Literature.validate_locale Literature.default_locale()
{:ok,
%Cldr.LanguageTag{
  backend: Literature,
  canonical_locale_name: "en-001",
  cldr_locale_name: :"en-001",
  extensions: %{},
  gettext_locale_name: "en",
  language: "en",
  locale: %{},
  private_use: [],
  rbnf_locale_name: :en,
  requested_locale_name: "en-001",
  script: :Latn,
  territory: :"001",
  transform: %{},
  language_variants: []
}}

iex> Literature.validate_locale("zzz")
{:error, {Cldr.InvalidLanguageError, "The language \"zzz\" is invalid"}}
Link to this function

validate_number_system(number_system)

See Cldr.validate_number_system/1.

Link to this function

validate_number_system_type(number_system_type)

@spec validate_number_system_type(String.t() | atom()) ::
  {:ok, atom()} | {:error, {module(), String.t()}}

Normalise and validate a number system type.

Arguments

Returns

  • {:ok, normalized_number_system_type} or

  • {:error, {exception, message}}

Examples

iex> Literature.validate_number_system_type(:default)
{:ok, :default}

iex> Literature.validate_number_system_type(:traditional)
{:ok, :traditional}

iex> Literature.validate_number_system_type(:latn)
{
  :error,
  {Cldr.UnknownNumberSystemTypeError, "The number system type :latn is unknown"}
}

iex> Literature.validate_number_system_type("bork")
{
  :error,
  {Cldr.UnknownNumberSystemTypeError, "The number system type \"bork\" is invalid"}
}
Link to this function

validate_params(params)

Link to this function

validate_territory(territory)

See Cldr.validate_territory/1.

Link to this function

with_locale(locale, fun)

(since 2.32.0)
@spec with_locale(Cldr.Locale.locale_reference(), (-> any())) :: any()

Execute a function with a locale ensuring that the current locale is restored after the function.

Arguments

Returns

  • The value returned by the function fun/0 or

  • {:error, {exception, reason}} if the locale is invalid or

  • raises an exception if the current locale cannot be identified.