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

Generates a Gravatar image URL.

Returns the Gravatar avatar URL for the given `email`. If `nil` is passed (the default),
a random email is used instead.

## Options

  * `:size` (integer, `1`–`2048`) - the image size in pixels. Defaults to `80`.
  * `:fallback` (an atom below, or a custom `http://`/`https://` URL string) - the default
    image returned when no Gravatar is set for the email. Defaults to `:identicon`.
    * `:identicon` - a geometric pattern based on the email hash.
    * `:monsterid` - a generated monster image.
    * `:wavatar` - a generated face image.
    * `:robohash` - a generated robot image.
    * `:retro` - an 8-bit arcade-style pixelated face.
    * `:blank` - a transparent PNG.
    * `:"404"` - an HTTP 404 response instead of an image.
  * `:rating` (`:g`, `:pg`, `:r`, `:x`, or `nil`) - the maximum content rating to allow.
    Defaults to `nil` (no restriction).
    * `: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.
  * `:force_default` (boolean) - when `true`, always returns the fallback image instead of
    the real Gravatar. Defaults to `false`.

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

Generates a Gravatar profile URL.

Returns the Gravatar profile page URL for the given `email`. If `nil` is passed (the
default), a random email is used instead.

## Options

  * `:format` (`:html`, `:json`, `:xml`, `:php`, `:vcf`, or `:qr`) - the response format.
    Defaults to `:html`.
    * `:html` - the HTML profile page.
    * `:json` - the JSON API endpoint.
    * `:xml` - the XML API endpoint.
    * `:php` - the PHP serialized data endpoint.
    * `:vcf` - the vCard/VCF endpoint.
    * `:qr` - the 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_display`
*since 0.15.0* 

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

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

## Examples

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

    iex> NeoFaker.Gravatar.random_display()
    "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*
