NeoFaker.Internet (neo_faker v0.15.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

Generates a random domain name.

Generates a random email address.

Generates a random IPv4 address.

Generates a random IPv6 address.

Generates a random MAC address.

Generates a random URL-friendly slug.

Generates a random top-level domain (TLD).

Generates a random URL.

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.

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

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

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

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

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

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

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

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

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