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

Functions for generating internet-related data.

Provides utilities to generate random usernames, email addresses, domain names, URLs,
IP addresses, MAC addresses, and slugs with flexible formatting and validation options.

# `domain_name`
*since 0.13.0* 

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

Generates a random domain name.

Returns a domain name string based on the specified type. Can produce random
word-based names, popular real-world domains, or a user-supplied custom domain.

## Options

  * `:word_count` (positive integer) - the number of words in a random domain name.
    Defaults to `1`.
  * `:type` (`:random`, `:popular`, or `:custom`) - the domain name strategy. Defaults
    to `:random`.
    * `:random` - a random word-based domain name.
    * `:popular` - a domain name from a list of popular real-world domains.
    * `:custom` - the user-supplied domain name given via `:domain_name`.
  * `:popular_type` (`:all`, `:ecommerce`, `:email`, `:search`, or `:social`) - the popular
    domain category, used when `:type` is `:popular`. Defaults to `:all`.
  * `:domain_name` (string) - the custom domain, used when `:type` is `:custom`. Defaults
    to `"example.com"`.

## Examples

    iex> NeoFaker.Internet.domain_name()
    "example"

    iex> NeoFaker.Internet.domain_name(word_count: 3)
    "alpha-beta-gamma"

    iex> NeoFaker.Internet.domain_name(type: :popular, popular_type: :email)
    "gmail.com"

    iex> NeoFaker.Internet.domain_name(type: :custom, domain_name: "elixir-lang.org")
    "elixir-lang.org"

# `email`
*since 0.13.0* 

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

Generates a random email address.

Combines username, domain name, and TLD generation into a single email address string.
Accepts all the same options as `username/1`, `domain_name/1`, and `tld/1`, each prefixed
by its context below.

## Username options

  * `:username_word_count` (positive integer) - the number of words in the username.
    Defaults to `2`.
  * `:joiner` (`:all`, `:dot`, `:underscore`, or `:dash`) - the separator between username
    words. Defaults to `:all`.
  * `:username_type` (`:person` or `:word`) - the word source. Defaults to `:person`.
  * `:number` (boolean) - when `true`, appends a random number to the username. Defaults
    to `false`.
  * `:number_range` (`Range`) - the range for the appended number. Defaults to `1..1000`.

## Domain name options

  * `:domain_name_word_count` (positive integer) - the number of words in the domain name.
    Defaults to `1`.
  * `:domain_type` (`:random`, `:popular`, or `:custom`) - the domain name strategy.
    Defaults to `:random`.
  * `:popular_type` (`:all`, `:ecommerce`, `:email`, `:search`, or `:social`) - the popular
    domain category, used when `:domain_type` is `:popular`. Defaults to `:all`.
  * `:domain_name` (string) - the custom domain, used when `:domain_type` is `:custom`.
    Defaults to `"example.com"`.

## TLD options

  * `:tld_type` (an atom accepted by `tld/1`'s `:type` option) - the TLD category.
    Defaults to `:all_except_safe`.

## Examples

    iex> NeoFaker.Internet.email()
    "josé@example.com"

    iex> NeoFaker.Internet.email(username_word_count: 3, joiner: :dot, number: true)
    "abigail.bethany.crawford_202@example.com"

    iex> NeoFaker.Internet.email(domain_type: :popular, popular_type: :email)
    "jane.doe@gmail.com"

    iex> NeoFaker.Internet.email(domain_type: :custom, domain_name: "elixir-lang.org")
    "josé@elixir-lang.org"

# `ipv4`
*since 0.13.0* 

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

Generates a random IPv4 address.

Returns a dotted-decimal IPv4 address string.

## Options

  * `:private` (boolean) - when `true`, generates an address from an RFC 1918 private
    range instead of a public one. Defaults to `false`.
  * `:class` (`:a`, `:b`, `:c`, or `nil`) - the private IP class, used when `:private` is
    `true`. Defaults to `nil` (randomly selected).
    * `:a` - Class A range (`10.0.0.0/8`).
    * `:b` - Class B range (`172.16.0.0/12`).
    * `:c` - Class C range (`192.168.0.0/16`).

## Examples

    iex> NeoFaker.Internet.ipv4()
    "183.235.34.108"

    iex> NeoFaker.Internet.ipv4(private: true)
    "192.168.1.42"

    iex> NeoFaker.Internet.ipv4(private: true, class: :a)
    "10.25.30.100"

# `ipv6`
*since 0.13.0* 

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

Generates a random IPv6 address.

Returns a colon-separated hexadecimal IPv6 address string.

## Options

  * `:uppercase` (boolean) - when `false`, returns the address in lowercase. Defaults
    to `true`.
  * `:compressed` (boolean) - when `true`, uses compressed `::` notation. Defaults
    to `false`.

## Examples

    iex> NeoFaker.Internet.ipv6()
    "E0E6:7E24:EC6E:E44C:FC69:9C25:CD85:CE08"

    iex> NeoFaker.Internet.ipv6(uppercase: false)
    "e0e6:7e24:ec6e:e44c:fc69:9c25:cd85:ce08"

    iex> NeoFaker.Internet.ipv6(compressed: true)
    "2001:db8::8a2e:370:7334"

# `mac_address`
*since 0.13.0* 

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

Generates a random MAC address.

Returns a hexadecimal MAC address string with configurable separator and casing.

## Options

  * `:uppercase` (boolean) - when `false`, returns the address in lowercase. Defaults
    to `true`.
  * `:separator` (`":"`, `"-"`, or `""`) - the separator between octets. Defaults to `":"`.

## Examples

    iex> NeoFaker.Internet.mac_address()
    "74:4E:44:B0:D0:93"

    iex> NeoFaker.Internet.mac_address(uppercase: false)
    "74:4e:44:b0:d0:93"

    iex> NeoFaker.Internet.mac_address(separator: "-")
    "74-4E-44-B0-D0-93"

    iex> NeoFaker.Internet.mac_address(separator: "", uppercase: false)
    "744e44b0d093"

# `slug`
*since 0.13.0* 

```elixir
@spec slug(pos_integer(), keyword()) :: String.t()
```

Generates a random URL-friendly slug.

Returns a lowercase, word-joined string suitable for use in URLs. `word_count` sets the
number of words and defaults to `3`.

## Options

  * `:separator` (string) - the separator between words. Defaults to `"-"`.

## Examples

    iex> NeoFaker.Internet.slug()
    "neo-faker-elixir"

    iex> NeoFaker.Internet.slug(5)
    "the-quick-brown-fox-jumps"

    iex> NeoFaker.Internet.slug(2, separator: "_")
    "hello_world"

# `tld`
*since 0.13.0* 

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

Generates a random top-level domain (TLD).

Returns a TLD string, with a leading dot by default.

## Options

  * `:dot` (boolean) - when `false`, omits the leading dot. Defaults to `true`.
  * `:type` (an atom below) - the TLD category. Defaults to `:all_except_safe`.
    * `:all_except_safe` - all TLD categories except safe TLDs.
    * `:all` - all TLD categories, including safe TLDs.
    * `:safe` - safe TLDs, e.g. `.example`.
    * `:generic` - generic TLDs, e.g. `.com`.
    * `:sponsored` - sponsored TLDs, e.g. `.edu`.
    * `:country_code` - country code TLDs, e.g. `.id`.

## Examples

    iex> NeoFaker.Internet.tld()
    ".com"

    iex> NeoFaker.Internet.tld(dot: false)
    "org"

    iex> NeoFaker.Internet.tld(type: :safe)
    ".example"

    iex> NeoFaker.Internet.tld(type: :generic, dot: false)
    "net"

# `url`
*since 0.13.0* 

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

Generates a random URL.

Returns a URL string built from a protocol, domain name, and TLD. Optionally
appends a random path and/or query string.

## Options

  * `:protocol` (`:https` or `:http`) - the URL scheme. Defaults to `:https`.
  * `:domain_type` (`:random`, `:popular`, or `:custom`) - the domain name strategy, as in
    `domain_name/1`. Defaults to `:random`.
  * `:path` (boolean) - when `true`, appends a random path. Defaults to `false`.
  * `:query` (boolean) - when `true`, appends random query parameters. Defaults to `false`.

## Examples

    iex> NeoFaker.Internet.url()
    "https://example.com"

    iex> NeoFaker.Internet.url(protocol: :http)
    "http://neo-faker.org"

    iex> NeoFaker.Internet.url(path: true)
    "https://example.com/users/profile"

    iex> NeoFaker.Internet.url(path: true, query: true)
    "https://example.com/api/v1?key=value&id=123"

# `username`
*since 0.13.0* 

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

Generates a random username.

Returns a username string composed of words joined by a separator, with an optional
numeric suffix.

## Options

  * `:word_count` (positive integer) - the number of words in the username. Defaults
    to `2`.
  * `:joiner` (`:all`, `:dot`, `:underscore`, or `:dash`) - the separator between words.
    `:all` picks any of the available joiners at random. Defaults to `:all`.
  * `:username_type` (`:person` or `:word`) - the word source. `:person` draws from random
    first or last names; `:word` draws from random words. Defaults to `:person`.
  * `:number` (boolean) - when `true`, appends a random number. Defaults to `false`.
  * `:number_range` (`Range`) - the range to sample the appended number from. Defaults
    to `1..1000`.

## Examples

    iex> NeoFaker.Internet.username()
    "josé_valim"

    iex> NeoFaker.Internet.username(word_count: 3, joiner: :dot)
    "abigail.bethany.crawford"

    iex> NeoFaker.Internet.username(username_type: :word, number: true, number_range: 1..2025)
    "elixir_alchemist_2012"

    iex> NeoFaker.Internet.username(number: true)
    "jane_smith_42"

---

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