View Source Cldr.Message (Cldr Messages v1.0.0)

Implements the ICU Message Format with functions to parse and interpolate messages.

Summary

Functions

Extract the binding names from an ICU message.

Formats a message into a canonical form.

Formats a message into a canonical form or raises if the message cannot be parsed.

Returns the Jaro distance between two messages or raises.

Returns the translation of the given ICU-formatted message string.

Returns the translation of the given ICU-formatted message string.

Types

@type arguments() :: bindings()
@type bindings() :: list() | map()
@type message() :: binary()
@type options() :: Keyword.t()

Functions

Extract the binding names from an ICU message.

Arguments

  • message is a CLDR message in binary or parsed form.

Returns

  • A list of binding names as strings or

  • {:error, {exception, reason}}

Examples

 iex> Cldr.Message.bindings "This {variable} is in the message"
 ["variable"]
Link to this function

canonical_message(message, options \\ [])

View Source

Formats a message into a canonical form.

This allows for messages to be compared directly, or using Cldr.Message.jaro_distance/3.

Arguments

  • message is a CLDR message in binary form.

  • options is a keyword list of options. The default is [].

Options

  • :trim determines if the message is trimmed of whitespace before formatting. The default is true.

  • :pretty determines if the message if formatted with indentation to aid readability. The default is false.

Returns

  • {ok, canonical_message} where canonical_message is a string or

  • {:error, {exception, reason}}

Examples

iex> Cldr.Message.canonical_message "{greeting } to you!"
{:ok, "{greeting} to you!"}
Link to this function

canonical_message!(message, options \\ [])

View Source

Formats a message into a canonical form or raises if the message cannot be parsed.

This allows for messages to be compared directly, or using Cldr.Message.jaro_distance/3.

Arguments

  • message is a CLDR message in binary form.

  • options is a keyword list of options. The default is [].

Options

  • :trim determines if the message is trimmed of whitespace before formatting. The default is true.

  • :pretty determines if the message if formatted with indentation to aid readability. The default is false.

Returns

  • canonical_message as a string or

  • raises an exception

Examples

iex> Cldr.Message.canonical_message! "{greeting } to you!"
"{greeting} to you!"
Link to this function

format(message, bindings \\ [], options \\ [])

View Source
@spec format(String.t(), bindings(), options()) ::
  {:ok, String.t()} | {:error, {module(), String.t()}}

Format a message in the ICU Message Format into a string.

The ICU Message Format uses message "pattern" strings with variable-element placeholders enclosed in {curly braces}. The argument syntax can include formatting details, otherwise a default format is used.

Arguments

  • bindings is a list or map of arguments that are used to replace placeholders in the message.

  • options is a keyword list of options.

Options

  • backend is any Cldr backend. That is, any module that contains use Cldr.

  • :locale is any valid locale name returned by Cldr.known_locale_names/0 or a t:Cldr.LanguageTag struct. The default is Cldr.get_locale/0.

  • :trim determines if the message is trimmed of whitespace before formatting. The default is false.

  • :allow_positional_args determines if position arguments are permitted. Positional arguments are in the format {0} in the message. The default is true.

  • All other aptions are passed to the to_string/2 function of a formatting module.

Returns

  • {:ok, formatted_mesasge} or

  • {:error, {module, reason}}

Examples

iex> Cldr.Message.format "{greeting} to you!", greeting: "Good morning"
{:ok, "Good morning to you!"}
Link to this function

format!(message, args \\ [], options \\ [])

View Source
@spec format!(String.t(), bindings(), options()) :: String.t() | no_return()
Link to this function

format_list(message, args, options)

View Source

See Cldr.Message.Interpreter.format_list/3.

Link to this function

format_list!(message, args, options)

View Source

See Cldr.Message.Interpreter.format_list!/3.

Link to this function

format_to_iolist(message, bindings \\ [], options \\ [])

View Source
@spec format_to_iolist(String.t(), bindings(), options()) ::
  {:ok, list(), list(), list()}
  | {:error, list(), list(), list()}
  | {:error, {module(), binary()}}

Format a message in the ICU Message Format into an iolist.

The ICU Message Format uses message "pattern" strings with variable-element placeholders enclosed in {curly braces}. The argument syntax can include formatting details, otherwise a default format is used.

Arguments

  • bindings is a list or map of arguments that are used to replace placeholders in the message.

  • options is a keyword list of options.

Options

  • backend is any Cldr backend. That is, any module that contains use Cldr.

  • :locale is any valid locale name returned by Cldr.known_locale_names/0 or a t:Cldr.LanguageTag struct. The default is Cldr.get_locale/0.

  • :trim determines if the message is trimmed of whitespace before formatting. The default is false.

  • :allow_positional_args determines if position arguments are permitted. Positional arguments are in the format {0} in the message. The default is true.

  • All other aptions are passed to the to_string/2 function of a formatting module.

Returns

  • {:ok, formatted_mesasge} or

  • {:error, {module, reason}}

Examples

iex> Cldr.Message.format_to_iolist "{greeting} to you!", greeting: "Good morning"
{:ok, ["Good morning", " to you!"], ["greeting"], []}
Link to this function

jaro_distance(message1, message2, options \\ [])

View Source

Returns the Jaro distance between two messages.

This allows for fuzzy matching of message which can be helpful when a message string is changed but the semantics remain the same.

Arguments

  • message1 is a CLDR message in binary form.

  • message2 is a CLDR message in binary form.

  • options is a keyword list of options. The default is [].

Options

  • :trim determines if the message is trimmed of whitespace before formatting. The default is false.

Returns

  • {ok, distance} where distance is a float value between 0.0 (equates to no similarity) and 1.0 (is an exact match) representing Jaro distance between message1 and message2 or

  • {:error, {exception, reason}}

Examples

iex> Cldr.Message.jaro_distance "{greetings} to you!", "{greeting} to you!"
{:ok, 0.9824561403508771}
Link to this function

jaro_distance!(message1, message2, options \\ [])

View Source

Returns the Jaro distance between two messages or raises.

This allows for fuzzy matching of message which can be helpful when a message string is changed but the semantics remain the same.

Arguments

  • message1 is a CLDR message in binary form.

  • message2 is a CLDR message in binary form.

  • options is a keyword list of options. The default is [].

Options

  • :trim determines if the message is trimmed of whitespace before formatting. The default is false.

Returns

  • distance where distance is a float value between 0.0 (equates to no similarity) and 1.0 (is an exact match) representing Jaro distance between message1 and message2 or

  • raises an exception

Examples

iex> Cldr.Message.jaro_distance! "{greetings} to you!", "{greeting} to you!"
0.9824561403508771

Returns the translation of the given ICU-formatted message string.

Any placeholders are replaced with the value of variables already in scope at the time of compilation.

t/1 is a wrapper around the gettext/2 macro which should therefore be imported from a Gettext backend prior to calling t/1.

Arguments

  • message is an ICU format message string.

Returns

  • A translated string.
Link to this macro

t(message, bindings)

View Source (macro)

Returns the translation of the given ICU-formatted message string.

t/2 is a wrapper around the gettext/2 macro which should therefore be imported from a Gettext backend prior to calling t/2.

Arguments

  • message is an ICU format message string.

  • bindings is a keyword list or map of bindings used to replace placeholders in the message.

Returns

  • A translated string.