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

Functions for generating Lorem Ipsum text.

Provides utilities to generate random paragraphs, sentences, and words sourced
from either the classic Lorem Ipsum text or Marcus Aurelius' *Meditations*.
All functions accept a `text:` option to switch between sources.

# `paragraph`
*since 0.8.0* 

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

Generates a random paragraph.

Returns a randomly selected paragraph from the chosen text source.

## Options

- `:text` - Text source. Either `:lorem` (default) or `:meditations`.

## Examples

    iex> NeoFaker.Lorem.paragraph()
    "Suspendisse ac justo venenatis, tincidunt sapien nec, accumsan augue. Vestibulum urna
    risus, egestas ut ultrices non, aliquet eget massa. Mauris id diam eget augue sagittis
    convallis sit amet nec diam. Morbi ut blandit est, et placerat neque."

    iex> NeoFaker.Lorem.paragraph(text: :meditations)
    "Do the things external which fall upon thee distract thee? Give thyself time to learn
    something new and good, and cease to be whirled around."

# `paragraphs`
*since 0.8.0* 

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

Generates multiple random paragraphs.

Returns a list of paragraphs. Pass `join: true` to get a single newline-separated string.

## Parameters

- `count` - Number of paragraphs to generate. Defaults to `3`.

## Options

- `:text` - Text source. Either `:lorem` (default) or `:meditations`.
- `:join` - When `true`, joins paragraphs with `"\n\n"`. Defaults to `false`.

## Examples

    iex> NeoFaker.Lorem.paragraphs(2)
    ["First paragraph...", "Second paragraph..."]

    iex> NeoFaker.Lorem.paragraphs(2, join: true)
    "First paragraph...\n\nSecond paragraph..."

# `sentence`
*since 0.8.0* 

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

Generates a random sentence.

Extracts a single sentence from a randomly chosen paragraph of the given
text source.

## Options

- `:text` - Text source. Either `:lorem` (default) or `:meditations`.

## Examples

    iex> NeoFaker.Lorem.sentence()
    "Suspendisse ac justo venenatis, tincidunt sapien nec, accumsan augue."

    iex> NeoFaker.Lorem.sentence(text: :meditations)
    "Do the things external which fall upon thee distract thee?"

# `sentences`
*since 0.8.0* 

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

Generates multiple random sentences.

Returns a list of sentences. Pass `join: true` to get a single space-separated string.

## Parameters

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

## Options

- `:text` - Text source. Either `:lorem` (default) or `:meditations`.
- `:join` - When `true`, joins sentences with `" "`. Defaults to `false`.

## Examples

    iex> NeoFaker.Lorem.sentences(3)
    ["First sentence.", "Second sentence.", "Third sentence."]

    iex> NeoFaker.Lorem.sentences(3, join: true)
    "First sentence. Second sentence. Third sentence."

# `word`
*since 0.8.0* 

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

Generates a random word.

Extracts a single lowercase word from a randomly chosen sentence, stripped of
punctuation.

## Options

- `:text` - Text source. Either `:lorem` (default) or `:meditations`.

## Examples

    iex> NeoFaker.Lorem.word()
    "suspendisse"

    iex> NeoFaker.Lorem.word(text: :meditations)
    "distract"

# `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. Pass `join: true` to get a single space-separated string.

## Parameters

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

## Options

- `:text` - Text source. Either `:lorem` (default) or `:meditations`.
- `:join` - When `true`, joins words with `" "`. Defaults to `false`.

## Examples

    iex> NeoFaker.Lorem.words(5)
    ["suspendisse", "justo", "venenatis", "sapien", "accumsan"]

    iex> NeoFaker.Lorem.words(5, join: true)
    "suspendisse justo venenatis sapien accumsan"

---

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