Expo.Message (expo v1.1.1)

Functions to work on message structs (Expo.Message.Singular and Expo.Message.Plural).

A message is a single PO singular or plural message. For example:

msgid "Hello"
msgstr ""

Message structs are used both to represent reference messages (where the msgstr is empty) in POT files as well as actual translations.

Summary

Types

key()

The key that can be used to identify a message.

msgctxt()

The msgctxt of a message.

msgid()

The msgid of a message.

msgstr()

The msgstr of a message.

split_string()

A list of strings representing lines.

t()

A type for either a singular or a plural message.

Functions

append_flag(message, flag)

Appends the given flag to the given message.

has_flag?(message, flag)

Tells whether the given message has the given flag specified.

key(message)

Returns a "key" that can be used to identify a message.

merge(message1, message2)

Merges two messages.

same?(message1, message2)

Tells whether two messages are the same message according to their msgid.

source_line_number(message, block, default \\ nil)

Get the source line number of the message.

Types

key()

@opaque key()

The key that can be used to identify a message.

See key/1.

msgctxt()

@type msgctxt() :: split_string()

The msgctxt of a message.

msgid()

@type msgid() :: split_string()

The msgid of a message.

msgstr()

@type msgstr() :: split_string()

The msgstr of a message.

split_string()

(since 0.5.0)

@type split_string() :: [String.t(), ...]

A list of strings representing lines.

This type is used for types such as msgid/0. The list of strings represents the message split into multiple lines, as parsed from a PO(T) file.

t()

@type t() :: Expo.Message.Singular.t() | Expo.Message.Plural.t()

A type for either a singular or a plural message.

Functions

append_flag(message, flag)

@spec append_flag(t(), String.t()) :: t()

Appends the given flag to the given message.

Keeps the line formatting intact.

Examples

iex> message = %Expo.Message.Singular{msgid: [], flags: []}
iex> Expo.Message.append_flag(message, "foo")
%Expo.Message.Singular{msgid: [], flags: [["foo"]]}

has_flag?(message, flag)

@spec has_flag?(t(), String.t()) :: boolean()

Tells whether the given message has the given flag specified.

Examples

iex> Expo.Message.has_flag?(%Expo.Message.Singular{msgid: [], flags: [["foo"]]}, "foo")
true

iex> Expo.Message.has_flag?(%Expo.Message.Singular{msgid: [], flags: [["foo"]]}, "bar")
false

key(message)

@spec key(t()) :: key()

Returns a "key" that can be used to identify a message.

This function returns a "key" that can be used to uniquely identify a message assuming that no "same" messages exist; for what "same" means, look at the documentation for same?/2.

The purpose of this function is to be used in situations where we'd like to group or sort messages but where we don't need the whole structs.

Examples

iex> t1 = %Expo.Message.Singular{msgid: ["foo"]}
iex> t2 = %Expo.Message.Singular{msgid: ["", "foo"]}
iex> Expo.Message.key(t1) == Expo.Message.key(t2)
true

iex> t1 = %Expo.Message.Singular{msgid: ["foo"]}
iex> t2 = %Expo.Message.Singular{msgid: ["bar"]}
iex> Expo.Message.key(t1) == Expo.Message.key(t2)
false

merge(message1, message2)

(since 0.5.0)

@spec merge(Expo.Message.Singular.t(), Expo.Message.Singular.t()) ::
  Expo.Message.Singular.t()

@spec merge(t(), Expo.Message.Plural.t()) :: Expo.Message.Plural.t()

@spec merge(Expo.Message.Plural.t(), t()) :: Expo.Message.Plural.t()

Merges two messages.

If both messages are Expo.Message.Singular, the result is a singular message. If one of the two messages is a Expo.Message.Plural, the result is a plural message. This is consistent with the behavior of GNU Gettext.

Examples

iex> msg1 = %Expo.Message.Singular{msgid: ["test"], flags: [["one"]]}
...> msg2 = %Expo.Message.Singular{msgid: ["test"], flags: [["one", "two"]]}
...> Expo.Message.merge(msg1, msg2)
%Expo.Message.Singular{msgid: ["test"], flags: [["one", "two"]]}

iex> msg1 = %Expo.Message.Singular{msgid: ["test"]}
...> msg2 = %Expo.Message.Plural{msgid: ["test"], msgid_plural: ["tests"]}
...> Expo.Message.merge(msg1, msg2)
%Expo.Message.Plural{msgid: ["test"], msgid_plural: ["tests"]}

same?(message1, message2)

@spec same?(t(), t()) :: boolean()

Tells whether two messages are the same message according to their msgid.

This function returns true if message1 and message2 are the same message, where "the same" means they have the same msgid or the same msgid and msgid_plural.

Examples

iex> t1 = %Expo.Message.Singular{msgid: ["foo"]}
iex> t2 = %Expo.Message.Singular{msgid: ["", "foo"]}
iex> Expo.Message.same?(t1, t2)
true

iex> t1 = %Expo.Message.Singular{msgid: ["foo"]}
iex> t2 = %Expo.Message.Singular{msgid: ["bar"]}
iex> Expo.Message.same?(t1, t2)
false

source_line_number(message, block, default \\ nil)

@spec source_line_number(
  Expo.Message.Singular.t(),
  Expo.Message.Singular.block(),
  default
) ::
  non_neg_integer() | default
when default: term()

@spec source_line_number(
  Expo.Message.Plural.t(),
  Expo.Message.Plural.block(),
  default
) ::
  non_neg_integer() | default
when default: term()

Get the source line number of the message.

Examples

iex> %Expo.Messages{messages: [message]} = Expo.PO.parse_string!("""
...> msgid "foo"
...> msgstr "bar"
...> """)
iex> Expo.Message.source_line_number(message, :msgid)
1