NeoFaker.Locale (neo_faker v0.15.0)

Copy Markdown View Source

Functions for managing and inspecting the active locale.

This is the single owner of locale state and the list of supported locale codes. Every other module (including NeoFaker.Data) reads locale state through this module rather than managing it independently.

Locale support

Many modules accept a :locale option. Use set/1 to override the locale for the calling process, or pass locale: per call. To set a locale for the whole application instead (e.g. for a Phoenix app), configure config :neo_faker, locale: ..., then see Getting Started.

iex> NeoFaker.Locale.set(:id_id)
:ok

iex> NeoFaker.Person.first_name()  # uses :id_id for this process
"Jaka"

iex> NeoFaker.Person.first_name(locale: :en_us)  # overrides per call
"José"

See the available locales for the full list of supported locale codes.

Summary

Functions

Returns true when locale is one of the supported codes, false otherwise.

Returns the current locale, preferring a process-scoped override over the application-wide default.

Returns the active locale, falling back to :default when none is set.

Sets the locale for the calling process.

Returns the sorted list of all supported locale atoms.

Functions

available?(locale)

(since 0.15.0)
@spec available?(atom()) :: boolean()

Returns true when locale is one of the supported codes, false otherwise.

:default is not treated as "available" here; check for it explicitly.

Examples

iex> NeoFaker.Locale.available?(:id_id)
true

iex> NeoFaker.Locale.available?(:bogus)
false

fetch()

(since 0.15.0)
@spec fetch() :: {:ok, atom()} | :error

Returns the current locale, preferring a process-scoped override over the application-wide default.

Checks, in order: a locale set for the calling process via set/1, then config :neo_faker, locale: .... Returns {:ok, locale} when either source has a value, or :error when neither does. Raises ArgumentError if the application-configured value is not an atom, or is an unsupported atom (i.e. not :default and not in supported/0), which can happen if config :neo_faker, locale: ... is set directly instead of going through set/1, which validates before storing.

Examples

iex> NeoFaker.Locale.set(:en_us)
:ok

iex> NeoFaker.Locale.fetch()
{:ok, :en_us}

get()

(since 0.15.0)
@spec get() :: atom()

Returns the active locale, falling back to :default when none is set.

Unlike fetch/0, this function always returns an atom and never returns :error, making it convenient for use inside generator functions.

Examples

iex> NeoFaker.Locale.set(:en_us)
:ok

iex> NeoFaker.Locale.get()
:en_us

set(locale)

(since 0.15.0)
@spec set(atom()) :: :ok

Sets the locale for the calling process.

The override is process-scoped (stored in the process dictionary), so concurrent processes, including async: true ExUnit tests, never interfere with each other. It does not touch config :neo_faker, locale: ..., which remains the fallback for any process that hasn't called this function. See the available locales for the full list of supported codes. Raises ArgumentError if a non-atom or unsupported locale is provided.

Examples

iex> NeoFaker.Locale.set(:id_id)
:ok

iex> NeoFaker.Locale.set(:en_us)
:ok

iex> NeoFaker.Locale.set(:default)
:ok

iex> NeoFaker.Locale.set(:bogus)
** (ArgumentError) Unsupported locale :bogus. Expected one of [:default, :en_us, :id_id] or see the available locales documentation.

The list of supported locales in the error message is built from supported/0, so it always reflects the actual supported set.

supported()

(since 0.15.0)
@spec supported() :: [atom()]

Returns the sorted list of all supported locale atoms.

The :default sentinel is not included; use available?/1 or check for :default explicitly.

Examples

iex> NeoFaker.Locale.supported()
[:en_us, :id_id]