API Reference

UniqueName(words::Vector{String})

Immutable value type representing a generated name as an ordered sequence of selected words. Produced by generate and consumed by render.

The single public field words is always a Vector{String}. A UniqueName carries no rendering state — separator and style are the concern of RenderOptions.

Examples

julia> using UniqueNamesGenerator

julia> name = UniqueName(["swift", "falcon"]);

julia> name.words
2-element Vector{String}:
 "swift"
 "falcon"

julia> string(name)
"Swift Falcon"

RenderOptions(; separator::AbstractString=" ", style::Symbol=:capital)

Immutable rendering configuration for render. Holds the inter-word separator and a word style from the closed set {:capital, :uppercase, :lowercase}. Any other style symbol is rejected at construction time with an ArgumentError.

As an immutable value type, RenderOptions is safe to share as a const module-level value; the package ships three such presets: TITLE, SLUG, and SCREAMING_SNAKE.

Examples

julia> using UniqueNamesGenerator

julia> RenderOptions(; separator = "-", style = :lowercase)
RenderOptions("-", :lowercase)

generate(; rng::AbstractRNG=Random.default_rng())::UniqueName
generate(dictionaries; rng::AbstractRNG=Random.default_rng())::UniqueName

Generate a single random UniqueName by picking one word from each dictionary. The no-arg form uses the built-in [ADJECTIVES, ADJECTIVES, NOUNS] triplet; the explicit form accepts any AbstractVector of non-empty word lists.

Throws ArgumentError if any dictionary is empty.

Use render to turn the returned UniqueName into a String.

Examples

julia> using UniqueNamesGenerator, Random

julia> n = generate([["swift"], ["falcon"]]);

julia> n.words
2-element Vector{String}:
 "swift"
 "falcon"

julia> string(n)
"Swift Falcon"

generate(dictionaries, exclude::AbstractSet{UniqueName};
         rng::AbstractRNG=Random.default_rng())::UniqueName

Generate a single UniqueName whose lowercased word projection is not equal (element-wise) to the lowercased projection of any member of exclude. Throws ExhaustedNameSpaceError when every combination is already excluded.

generate(dictionaries, n::Integer;
         unique::Bool=true,
         rng::AbstractRNG=Random.default_rng())::Vector{UniqueName}

Generate n UniqueName values in one call. When unique=true, all returned names are distinct on their case-insensitive word projection, and ExhaustedNameSpaceError is thrown if n exceeds the number of available combinations. When unique=false, duplicates are allowed.

render(name::UniqueName, opts::RenderOptions)::String
render(name::UniqueName; separator::AbstractString=" ", style::Symbol=:capital)::String

Render a UniqueName to a String using the given rendering configuration. The options-object form is the canonical rendering kernel; the keyword form is a thin wrapper that constructs a RenderOptions and delegates to it, so both forms produce byte-identical output for the same (separator, style) pair.

render is a pure function: no randomness, no I/O, no mutation of its arguments. A zero-word UniqueName renders to ""; a one-word UniqueName renders the single word with style applied and separator has no effect.

Examples

julia> using UniqueNamesGenerator

julia> name = UniqueName(["swift", "falcon"]);

julia> render(name)
"Swift Falcon"

julia> render(name; separator = "-", style = :lowercase)
"swift-falcon"

julia> render(name, SCREAMING_SNAKE)
"SWIFT_FALCON"

TITLE

RenderOptions preset: space-separated, :capital style. Semantically identical to RenderOptions(); use it at call sites to spell the default rendering intent explicitly (render(name, TITLE)).

SLUG

RenderOptions preset: dash-separated, :lowercase style. Suitable for URL-safe slugs (render(name, SLUG) → "swift-falcon").

SCREAMING_SNAKE

RenderOptions preset: underscore-separated, :uppercase style. Suitable for constant names (render(name, SCREAMING_SNAKE) → "SWIFT_FALCON").

load_dictionary(file::AbstractString)::Vector{String}

Load a word list from a CSV file (first column, skipping the header line).

Return the total number of possible combinations for dictionaries.

ExhaustedNameSpaceError(max, excluded)

Thrown when all possible name combinations have been exhausted.