NeoFaker.Internet (neo_faker v0.14.0)

Copy Markdown View Source

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.

Summary

Functions

domain_name(opts \\ [])

Generates a random domain name.

email(opts \\ [])

Generates a random email address.

ipv4(opts \\ [])

Generates a random IPv4 address.

ipv6(opts \\ [])

Generates a random IPv6 address.

mac_address(opts \\ [])

Generates a random MAC address.

slug(word_count \\ 3, opts \\ [])

Generates a random URL-friendly slug.

tld(opts \\ [])

Generates a random top-level domain (TLD).

url(opts \\ [])

Generates a random URL.

username(opts \\ [])

Generates a random username.

Functions

domain_name(opts \\ [])

(since 0.13.0) 
@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.

Parameters

  • opts - Keyword list of options:
    • :word_count - Number of words in a random domain name. Defaults to 1.
    • :type - Domain name strategy. Defaults to :random.
    • :popular_type - Popular domain category when :type is :popular. Defaults to :all.
    • :domain_name - Custom domain string when :type is :custom. Defaults to "example.com".

Options

The values for :type can be:

  • :random - Random word-based domain name (default).
  • :popular - Domain name from a list of popular real-world domains.
  • :custom - User-supplied domain name via :domain_name.

The values for :popular_type can be:

  • :all - All popular domains (default).
  • :ecommerce - Popular e-commerce domains.
  • :email - Popular email service domains.
  • :search - Popular search engine domains.
  • :social - Popular social media domains.

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(opts \\ [])

(since 0.13.0) 
@spec email(Keyword.t()) :: 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, prefixed by their context.

Username Options

  • :username_word_count - Number of words in the username. Defaults to 2.
  • :joiner - Separator between username words. Defaults to :all.
  • :username_type - Word source. Defaults to :person.
  • :number - When true, appends a random number to the username. Defaults to false.
  • :number_range - Range for the appended number. Defaults to 1..1000.

Domain Name Options

  • :domain_name_word_count - Number of words in the domain name. Defaults to 1.
  • :domain_type - Domain name strategy. Defaults to :random.
  • :popular_type - Popular domain category when :domain_type is :popular. Defaults to :all.
  • :domain_name - Custom domain when :domain_type is :custom. Defaults to "example.com".

TLD Options

  • :tld_type - 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(opts \\ [])

(since 0.13.0) 
@spec ipv4(Keyword.t()) :: String.t()

Generates a random IPv4 address.

Returns a dotted-decimal IPv4 address string. Pass private: true to generate an address from a RFC 1918 private range.

Parameters

  • opts - Keyword list of options:
    • :private - When true, generates a private IP address. Defaults to false.
    • :class - Private IP class when :private is true. Randomly selected by default.

Options

The values for :class can be:

  • :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(opts \\ [])

(since 0.13.0) 
@spec ipv6(Keyword.t()) :: String.t()

Generates a random IPv6 address.

Returns a colon-separated hexadecimal IPv6 address string. Supports uppercase and compressed (::) notation.

Parameters

  • opts - Keyword list of options:
    • :uppercase - When true, returns the address in uppercase. Defaults to true.
    • :compressed - 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(opts \\ [])

(since 0.13.0) 
@spec mac_address(Keyword.t()) :: String.t()

Generates a random MAC address.

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

Parameters

  • opts - Keyword list of options:
    • :uppercase - When true, returns the address in uppercase. Defaults to true.
    • :separator - Separator between octets. Defaults to ":".

Options

The values for :separator can be:

  • ":" - Colon (default).
  • "-" - Dash.
  • "" - No separator.

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(word_count \\ 3, opts \\ [])

(since 0.13.0) 
@spec slug(pos_integer(), Keyword.t()) :: String.t()

Generates a random URL-friendly slug.

Returns a lowercase, word-joined string suitable for use in URLs.

Parameters

  • word_count - Number of words in the slug. Defaults to 3.
  • opts - Keyword list of options:
    • :separator - 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(opts \\ [])

(since 0.13.0) 
@spec tld(Keyword.t()) :: String.t()

Generates a random top-level domain (TLD).

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

Parameters

  • opts - Keyword list of options:
    • :dot - When true, prepends a dot to the TLD. Defaults to true.
    • :type - TLD category. Defaults to :all_except_safe.

Options

The values for :type can be:

  • :all_except_safe - All TLD categories except safe TLDs (default).
  • :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(opts \\ [])

(since 0.13.0) 
@spec url(Keyword.t()) :: 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.

Parameters

  • opts - Keyword list of options:
    • :protocol - URL scheme. Defaults to :https.
    • :domain_type - Domain name strategy. Defaults to :random.
    • :path - When true, appends a random path. Defaults to false.
    • :query - When true, appends random query parameters. Defaults to false.

Options

The values for :protocol can be:

  • :https - HTTPS (default).
  • :http - HTTP.

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(opts \\ [])

(since 0.13.0) 
@spec username(Keyword.t()) :: String.t()

Generates a random username.

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

Parameters

  • opts - Keyword list of options:
    • :word_count - Number of words in the username. Defaults to 2.
    • :joiner - Separator between words. Defaults to :all.
    • :username_type - Word source for the username. Defaults to :person.
    • :number - When true, appends a random number. Defaults to false.
    • :number_range - Range to sample the appended number from. Defaults to 1..1000.

Options

The values for :joiner can be:

  • :all - Any of the available joiners (default).
  • :dot - Dot (.).
  • :underscore - Underscore (_).
  • :dash - Dash (-).

The values for :username_type can be:

  • :person - Random first or last names (default).
  • :word - Random words.

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"