# `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. The plural
functions return a list; join it yourself with `Enum.join/2` if you need a
single string.

# `paragraph`
*since 0.8.0* 

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

Generates a random paragraph.

Returns a randomly selected paragraph from the chosen text source.

## Options

  * `:text` (`:lorem` or `:meditations`) - the text source. Defaults to `:lorem`.
  * `:locale` (atom) - the locale to use. Defaults to the application's configured locale.

## 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()) :: [String.t()]
```

Generates multiple random paragraphs.

Returns a list of paragraphs. `count` sets how many are generated and defaults to `3`.

## Options

  * `:text` (`:lorem` or `:meditations`) - the text source. Defaults to `:lorem`.
  * `:locale` (atom) - the locale to use. Defaults to the application's configured locale.

## Examples

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

# `sentence`
*since 0.8.0* 

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

Generates a random sentence.

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

## Options

  * `:text` (`:lorem` or `:meditations`) - the text source. Defaults to `:lorem`.
  * `:locale` (atom) - the locale to use. Defaults to the application's configured locale.

## 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()) :: [String.t()]
```

Generates multiple random sentences.

Returns a list of sentences. `count` sets how many are generated and defaults to `5`.

## Options

  * `:text` (`:lorem` or `:meditations`) - the text source. Defaults to `:lorem`.
  * `:locale` (atom) - the locale to use. Defaults to the application's configured locale.

## Examples

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

# `word`
*since 0.8.0* 

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

Generates a random word.

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

## Options

  * `:text` (`:lorem` or `:meditations`) - the text source. Defaults to `:lorem`.
  * `:locale` (atom) - the locale to use. Defaults to the application's configured locale.

## Examples

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

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

# `words`
*since 0.8.0* 

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

Generates multiple random words.

Returns a list of words. `count` sets how many are generated and defaults to `10`.

## Options

  * `:text` (`:lorem` or `:meditations`) - the text source. Defaults to `:lorem`.
  * `:locale` (atom) - the locale to use. Defaults to the application's configured locale.

## Examples

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

---

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