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

Functions for generating random Gravatar URLs.

Provides utilities to generate Gravatar image and profile URLs with customizable size,
fallback type, rating, and format options, based on the
[Gravatar API](https://docs.gravatar.com/api/avatars/images).

# `email`
*since 0.3.1* 

```elixir
@type email() :: String.t() | nil
```

Email address.

# `default_size`
*since 0.3.1* 

```elixir
@spec default_size() :: pos_integer()
```

Returns the default image size in pixels.

## Examples

    iex> NeoFaker.Gravatar.default_size()
    80

# `display`
*since 0.3.1* 

```elixir
@spec display(email(), Keyword.t()) :: String.t()
```

Generates a Gravatar image URL.

Returns the Gravatar avatar URL for the given email address. If `nil` is passed,
a random email is used.

## Parameters

- `email` - Email address to hash. If `nil`, generates a random email.
- `opts` - Keyword list of options:
  - `:size` - Image size in pixels (`1`–`2048`). Defaults to `80`.
  - `:fallback` - Default image type. Defaults to `:identicon`.
  - `:rating` - Maximum content rating. Defaults to `nil` (no restriction).
  - `:force_default` - When `true`, always returns the fallback image. Defaults to `false`.

## Options

The values for `:fallback` can be:

- `:identicon` - Geometric pattern based on email hash (default).
- `:monsterid` - Generated monster image.
- `:wavatar` - Generated face image.
- `:robohash` - Generated robot image.
- `:retro` - 8-bit arcade-style pixelated face.
- `:blank` - Transparent PNG.
- `:"404"` - HTTP 404 response.
- Custom `http://` or `https://` URL string.

The values for `:rating` can be:

- `:g` - Suitable for all audiences.
- `:pg` - May contain mild profanity or suggestive content.
- `:r` - May contain harsh profanity, violence, or nudity.
- `:x` - May contain explicit sexual imagery or extreme violence.

## Examples

    iex> NeoFaker.Gravatar.display()
    "https://gravatar.com/avatar/<hashed_email>?d=identicon&s=80"

    iex> NeoFaker.Gravatar.display("john.doe@example.com", size: 100)
    "https://gravatar.com/avatar/<hashed_email>?d=identicon&s=100"

    iex> NeoFaker.Gravatar.display("john.doe@example.com", fallback: :monsterid)
    "https://gravatar.com/avatar/<hashed_email>?d=monsterid&s=80"

    iex> NeoFaker.Gravatar.display("user@test.com", rating: :pg)
    "https://gravatar.com/avatar/<hashed_email>?d=identicon&s=80&r=pg"

    iex> NeoFaker.Gravatar.display("user@test.com", force_default: true)
    "https://gravatar.com/avatar/<hashed_email>?d=identicon&s=80&f=y"

# `fallback_types`
*since 0.3.1* 

```elixir
@spec fallback_types() :: [atom()]
```

Returns the list of all valid fallback type atoms.

## Examples

    iex> NeoFaker.Gravatar.fallback_types()
    [:identicon, :monsterid, :wavatar, :robohash, :retro, :blank, :"404"]

# `profile`
*since 0.3.1* 

```elixir
@spec profile(email(), Keyword.t()) :: String.t()
```

Generates a Gravatar profile URL.

Returns the Gravatar profile page URL for the given email address. If `nil` is
passed, a random email is used.

## Parameters

- `email` - Email address to hash. If `nil`, generates a random email.
- `opts` - Keyword list of options:
  - `:format` - Response format. Defaults to `:html`.

## Options

The values for `:format` can be:

- `:html` - HTML profile page (default).
- `:json` - JSON API endpoint.
- `:xml` - XML API endpoint.
- `:php` - PHP serialized data endpoint.
- `:vcf` - vCard/VCF endpoint.
- `:qr` - QR code image endpoint.

## Examples

    iex> NeoFaker.Gravatar.profile()
    "https://gravatar.com/<hash>"

    iex> NeoFaker.Gravatar.profile("user@example.com", format: :json)
    "https://gravatar.com/<hash>.json"

    iex> NeoFaker.Gravatar.profile(nil, format: :xml)
    "https://gravatar.com/<hash>.xml"

# `random`
*since 0.3.1* 

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

Generates a Gravatar image URL with randomly selected size and fallback type.

## Examples

    iex> NeoFaker.Gravatar.random()
    "https://gravatar.com/avatar/<hash>?d=monsterid&s=150"

    iex> NeoFaker.Gravatar.random()
    "https://gravatar.com/avatar/<hash>?d=wavatar&s=64"

# `size_range`
*since 0.3.1* 

```elixir
@spec size_range() :: Range.t()
```

Returns the valid image size range.

## Examples

    iex> NeoFaker.Gravatar.size_range()
    1..2048

---

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