View Source Cldr for Lists
Introduction and Getting Started
ex_cldr_lists
is an add-on library for ex_cldr that provides localisation and formatting for lists.
Cldr
interprets the CLDR rules for list formatting in a locale-specific way.
Configuration
From ex_cldr version 2.0, a backend module must be defined into which the public API and the CLDR data is compiled. See the ex_cldr documentation for further information on configuration.
In the following examples we assume the presence of a module called MyApp.Cldr
defined as:
defmodule MyApp.Cldr do
use Cldr, locales: ["en", "fr"], default_locale: "en"
end
Installation
Note that :ex_cldr_lists
requires Elixir 1.5 or later.
Add ex_lists
as a dependency to your mix
project:
defp deps do
[
{:ex_cldr_lists, "~> 2.0"}
]
end
then retrieve ex_cldr_lists
from hex:
mix deps.get
mix deps.compile
Public API & Examples
There are two common public API functions:
MyApp.Cldr.List.to_string/2
&MyApp.Cldr.List.to_string!/2
which take a list of terms and returns a string. Each item in the list must be understood byKernel.to_string/1
MyApp.Cldr.List.intersperse/2
&MyApp.Cldr.List.intersperse!/2
which takes a list of terms and returns a list interspersed within the list format. This function can be helpful when creating a list fromPhoenix
safe strings which are of the format{:safe, "some string"}
For help in iex
:
iex> h MyApp.Cldr.List.to_string
iex> h MyApp.Cldr.List.intersperse
List Formatting
iex> MyApp.Cldr.List.list_formats_for "en"
[:or, :standard, :standard_short, :unit, :unit_narrow, :unit_short]
iex> MyApp.Cldr.List.to_string(["a", "b", "c"], locale: "en")
{:ok, "a, b, and c"}
iex> MyApp.Cldr.List.to_string(["a", "b", "c"], locale: "en", format: :or)
{:ok, "a, b, or c"}
iex> MyApp.Cldr.List.to_string(["a", "b", "c"], locale: "en", format: :unit)
{:ok, "a, b, c"}
iex> MyApp.Cldr.List.to_string!(["a", "b", "c"], locale: "en", format: :unit)
"a, b, c"
iex> MyApp.Cldr.List.intersperse(["a", "b", "c"], locale: "en")
{:ok, ["a", ", ", "b", ", and ", "c"]}
List Formats
List formats are referred to by a pattern style the standardises the way to reference different formats in a locale. See MyApp.Cldr.List.list_formats_for/1
. For example:
iex> MyApp.Cldr.List.list_formats_for "en"
[:standard, :standard_short, :unit, :unit_narrow, :unit_short]
iex> MyApp.Cldr.List.list_formats_for "ru"
[:standard, :standard_short, :unit, :unit_narrow, :unit_short]
iex> MyApp.Cldr.List.list_formats_for "th"
[:standard, :standard_short, :unit, :unit_narrow, :unit_short]
Known formats
The common formats for a locale are:
- :or,
- :or_narrow,
- :or_short,
- :standard,
- :standard_narrow,
- :standard_short,
- :unit,
- :unit_narrow,
- :unit_short
This list is not fixed or definitive, other formats may be present for a locale.
The definitions of these formats can be explored through MyApp.Cldr.List.list_patterns_for/1
. For example:
iex> MyApp.Cldr.List.list_patterns_for "fr"
%{standard: %{"2": "{0} et {1}", end: "{0} et {1}", middle: "{0}, {1}",
start: "{0}, {1}"},
standard_short: %{"2": "{0} et {1}", end: "{0} et {1}", middle: "{0}, {1}",
start: "{0}, {1}"},
unit: %{"2": "{0} et {1}", end: "{0} et {1}", middle: "{0}, {1}",
start: "{0}, {1}"},
unit_narrow: %{"2": "{0} {1}", end: "{0} {1}", middle: "{0} {1}",
start: "{0} {1}"},
unit_short: %{"2": "{0} et {1}", end: "{0} et {1}", middle: "{0}, {1}",
start: "{0}, {1}"}}