# `NeoFaker`
[🔗](https://github.com/muzhawir/neo_faker/blob/main/lib/neo_faker.ex#L1)

NeoFaker is a package for generating fake data in Elixir.

This module provides the main interface for starting the application and
managing locale configuration.

## Locale support

Many modules accept a `:locale` option. Use `set_locale/1` to configure a
default locale for the whole application, or pass `locale:` per call.

    iex> NeoFaker.set_locale(:id_id)
    :ok

    iex> NeoFaker.Person.first_name()  # uses :id_id globally
    "Jaka"

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

See the [available locales](https://hexdocs.pm/neo_faker/locales.html)
for the full list of supported locale codes.

# `get_locale`
*since 0.1.0* 

```elixir
@spec get_locale() :: atom()
```

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

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

## Examples

    iex> NeoFaker.set_locale(:en_us)
    :ok

    iex> NeoFaker.get_locale()
    :en_us

    iex> Application.delete_env(:neo_faker, :locale)
    :ok

    iex> NeoFaker.get_locale()
    :default

# `locale`
*since 0.1.0* 

```elixir
@spec locale() :: {:ok, atom()} | :error
```

Returns the current locale configured for the NeoFaker application.

Returns `{:ok, locale}` when a locale is set, or `:error` when none has been
configured. Raises `ArgumentError` if the stored value is not an atom, or is
an unsupported atom (i.e. not `:default` and not in
`NeoFaker.Data.supported_locales/0`).

## Examples

    iex> NeoFaker.set_locale(:en_us)
    :ok

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

    iex> Application.delete_env(:neo_faker, :locale)
    :ok

    iex> NeoFaker.locale()
    :error

# `set_locale`
*since 0.1.0* 

```elixir
@spec set_locale(atom()) :: :ok
```

Sets the locale for the NeoFaker application.

The `locale` must be an atom matching a supported locale code (e.g. `:en_us`,
`:id_id`, `:default`). See the
[available locales](https://hexdocs.pm/neo_faker/locales.html) for
the full list. Raises `ArgumentError` if a non-atom or unsupported locale is
provided.

## Examples

    iex> NeoFaker.set_locale(:id_id)
    :ok

    iex> NeoFaker.set_locale(:en_us)
    :ok

    iex> NeoFaker.set_locale(:default)
    :ok

    iex> NeoFaker.set_locale(: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 generated dynamically
from `priv/data/locale.exs`, so it will always reflect the actual supported
locales (including any added in future releases).

# `start`
*since 0.1.0* 

```elixir
@spec start() :: :ok
```

Starts the NeoFaker application and ensures a locale is configured.

If no locale is set in the application environment, it defaults to `:default`.
Prints the active locale to stdout and returns `:ok`.

## Examples

    iex> NeoFaker.start()
    :ok

---

*Consult [api-reference.md](api-reference.md) for complete listing*