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

Functions for generating random text.

Provides utilities to generate single characters, multi-character strings,
emojis, and words from common word lists. All character generators support
type filtering (alphabet, digits, or mixed alphanumeric).

# `character`
*since 0.8.0* 

```elixir
@spec character(Keyword.t()) :: String.t()
```

Generates a single random character.

Returns a single character from the alphanumeric set by default. Use the
`:type` option to restrict the pool.

## Options

- `:type` - Character pool to draw from. Defaults to the full alphanumeric set.
  - `:alphabet_lower` - Lowercase letters only.
  - `:alphabet_upper` - Uppercase letters only.
  - `:alphabet` - Any letter (lower or upper).
  - `:digit` - A digit (`0`–`9`).

## Examples

    iex> NeoFaker.Text.character()
    "a"

    iex> NeoFaker.Text.character(type: :digit)
    "0"

    iex> NeoFaker.Text.character(type: :alphabet_lower)
    "z"

    iex> NeoFaker.Text.character(type: :alphabet_upper)
    "A"

    iex> NeoFaker.Text.character(type: :alphabet)
    "X"

# `characters`
*since 0.8.0* 

```elixir
@spec characters(pos_integer(), Keyword.t()) :: String.t()
```

Generates a string of random characters.

Calls `character/1` `number` times and joins the results into a single string.

## Parameters

- `number` - Number of characters to generate. Defaults to `11`.

## Options

- `:type` - Character pool to draw from (see `character/1`). Defaults to alphanumeric.

## Examples

    iex> NeoFaker.Text.characters()
    "XfELJU1mRMg"

    iex> NeoFaker.Text.characters(20, type: :alphabet_upper)
    "BVAJHRGSCEVJFNYSWCJE"

    iex> NeoFaker.Text.characters(5, type: :digit)
    "74392"

    iex> NeoFaker.Text.characters(10, type: :alphabet_lower)
    "xyzabcdefg"

# `emoji`
*since 0.8.0* 

```elixir
@spec emoji(Keyword.t()) :: String.t()
```

Generates a random emoji.

Returns a random emoji from the specified category, or from all categories
when `:all` is used (default).

## Options

- `:category` - Emoji category. Defaults to `:all`.
  - `:all` - Any category.
  - `:activities` - Activities.
  - `:animals_and_nature` - Animals and nature.
  - `:food_and_drink` - Food and drink.
  - `:objects` - Objects.
  - `:people_and_body` - People and body.
  - `:smileys_and_emotion` - Smileys and emotion.
  - `:symbols` - Symbols.
  - `:travel_and_places` - Travel and places.

## Examples

    iex> NeoFaker.Text.emoji()
    "✨"

    iex> NeoFaker.Text.emoji(category: :activities)
    "🎉"

    iex> NeoFaker.Text.emoji(category: :smileys_and_emotion)
    "😀"

    iex> NeoFaker.Text.emoji(category: :animals_and_nature)
    "🐶"

# `word`
*since 0.8.0* 

```elixir
@spec word() :: String.t()
```

Generates a random word from a common English word list.

## Examples

    iex> NeoFaker.Text.word()
    "computer"

# `words`
*since 0.8.0* 

```elixir
@spec words(pos_integer(), Keyword.t()) :: [String.t()] | String.t()
```

Generates multiple random words.

Returns a list of words by default. Pass `join: true` to get a single string.

## Parameters

- `count` - Number of words to generate. Defaults to `5`.

## Options

- `:join` - When `true`, joins the words into a string. Defaults to `false`.
- `:separator` - Separator used when joining. Defaults to `" "`.

## Examples

    iex> NeoFaker.Text.words(3)
    ["computer", "elixir", "phoenix"]

    iex> NeoFaker.Text.words(3, join: true)
    "computer elixir phoenix"

    iex> NeoFaker.Text.words(3, join: true, separator: "-")
    "computer-elixir-phoenix"

---

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