nicename

README

Nicename 🐶🧀

A lightweight, concurrency-safe Go library and CLI for generating delightful, human-friendly random names, URL slugs, and unique task identifiers.

Now refreshed with full support for Wallace & Gromit and the Aardman Animations filmography (Chicken Run, Shaun the Sheep, Morph, Creature Comforts, Flushed Away, The Pirates!, and more).

---

✨ Features

• Zero External Dependencies: Pure Go standard library (using modern math/rand/v2 and crypto/rand).
• High Performance & Thread-Safe: Sub-microsecond execution, zero regex overhead, and fully concurrency-safe for high-throughput goroutines and servers.
• Aardman Universe Support: Over 100+ iconic characters, inventions, cheeses, and British adjectives:
  • Characters: Gromit, Wallace, Feathers McGraw, Wendolene Ramsbottom, Shaun the Sheep, Preston, Rocky Rhodes, Ginger, Morph, Chas, Bitzer, The Pirate Captain...
  • Inventions & Cheeses: Techno Trousers, Knit-o-matic, Snoozatron, Bun-vac 6000, Wensleydale, Stinking Bishop, Cracking Toast...
  • Adjectives: Cracking, Smashing, Plucky, Cheesy, Grand, Gallant, Clever, Feathered, Eccentric...
• Kebab-Case Slugs & Task IDs: Ready-made for Docker container names, Git worktree branches, and background jobs.
• CLI Utility Included: Generate names directly from the command line or shell scripts.
• 100% Backward Compatible: Retains the classic First and Second name lists and GeneratePair().

---

📦 Installation

As a Go Library

go get github.com/dreh23/nicename

Requires Go 1.22 or newer.

As a CLI Tool

go install github.com/dreh23/nicename/cmd/nicename@latest

---

💻 CLI Usage

# Default: Spirited Aardman pair
$ nicename
Cracking Gromit

# URL- and Git-branch-friendly kebab-case slug
$ nicename -slug
cracking-gromit

# Unique collision-resistant task ID (slug + 4-hex random suffix)
$ nicename -task-id
cracking-gromit-8f2a

# Specific Aardman character pair
$ nicename -character
Clever Feathers McGraw

# Classic original dataset
$ nicename -classic
Adventurous Mary

# Generate multiple names
$ nicename -count 3 -slug
plucky-feathers-mcgraw
cheesy-techno-trousers
grand-wendolene-ramsbottom

---

🚀 Quick Start (Go Code)

package main

import (
	"fmt"
	"github.com/dreh23/nicename"
)

func main() {
	// 1. Classic generation (Backward compatible)
	fmt.Println(nicename.GeneratePair())
	// Output: "Adventurous Mary"

	// 2. Aardman / Wallace & Gromit generation
	fmt.Println(nicename.GenerateAardman())
	// Output: "Cracking Gromit"
	// Output: "Cheesy Techno Trousers"

	// 3. Specific Aardman character pair
	fmt.Println(nicename.GenerateAardmanCharacter())
	// Output: "Clever Feathers McGraw"

	// 4. URL and Git branch slugs
	fmt.Println(nicename.GenerateAardmanSlug())
	// Output: "cracking-gromit"
	// Output: "plucky-shaun-the-sheep"

	// 5. Unique, collision-resistant task IDs
	fmt.Println(nicename.GenerateTaskID())
	// Output: "cracking-gromit-8f2a"
	// Output: "feathers-mcgraw-4e1b"
}

---

🛠️ API Reference

Function	Returns	Example	Description
GeneratePair()	string	"Adventurous Mary"	Classic adjective + name from the original 4,000+ name dictionary.
GeneratePairSlug()	string	"adventurous-mary"	Lowercase kebab-cased slug from the original dictionary.
GenerateAardman()	string	"Cracking Gromit"	Spirited Aardman pair (character, invention, or cheese).
GenerateAardmanCharacter()	string	"Clever Feathers McGraw"	Adjective paired strictly with an Aardman character.
GenerateAardmanSlug()	string	"cracking-gromit"	URL- and branch-safe kebab-cased Aardman slug.
GenerateTaskID()	string	"cracking-gromit-8f2a"	Aardman slug with a 4-hex crypto-random suffix.
FormatTaskID(slug string)	string	"custom-task-8f2a"	Appends a 4-hex crypto-random suffix to any slug.
Slugify(s string)	string	"feathers-mcgraw"	Cleans and normalizes any string into a lowercase slug.
GenerateCustom(...)	string	"Custom Pair"	Generates pairs from arbitrary custom word slices.

---

⚡ Performance

Benchmarks executed on Intel Core i5-12400 (Linux amd64, pure Go):

BenchmarkGeneratePair-12          22,729,735     51.2 ns/op     18 B/op    1 allocs/op
BenchmarkGenerateAardmanSlug-12   10,013,353    117.2 ns/op     47 B/op    2 allocs/op
BenchmarkGenerateTaskID-12         2,188,717    546.7 ns/op     83 B/op    5 allocs/op

---

🧪 Testing

go test -v -race ./...

Statement coverage: 100.0%.

---

📜 License

MIT License. See LICENSE for details.

Documentation

Overview

Package nicename provides lightweight, thread-safe generators for memorable, human-friendly random names, URL slugs, and unique task identifiers.

Index

• Variables
• func FormatTaskID(slug string) string
• func GenerateAardman() string
• func GenerateAardmanCharacter() string
• func GenerateAardmanSlug() string
• func GenerateCustom(adjectives []string, nouns []string, separator string, toSlug bool) string
• func GeneratePair() string
• func GeneratePairSlug() string
• func GenerateTaskID() string
• func Slugify(s string) string

Examples

• FormatTaskID
• GenerateAardman
• GenerateAardmanSlug
• GenerateCustom
• GeneratePair
• GenerateTaskID
• Slugify

Variables

var AardmanAdjectives = []string{
	"Astute",
	"Audacious",
	"Barmy",
	"Brave",
	"Breezy",
	"Brilliant",
	"Bumbling",
	"Cheesy",
	"Chirpy",
	"Chubby",
	"Clever",
	"Crafty",
	"Cracking",
	"Daft",
	"Dapper",
	"Daring",
	"Dashing",
	"Eccentric",
	"Fearless",
	"Feathered",
	"Gallant",
	"Grand",
	"Gullible",
	"Heroic",
	"Industrious",
	"Ingenious",
	"Inventive",
	"Jolly",
	"Loyal",
	"Mechanical",
	"Mellow",
	"Mischievous",
	"Nifty",
	"Noble",
	"Plucky",
	"Posh",
	"Quirky",
	"Resilient",
	"Resourceful",
	"Shifty",
	"Smashing",
	"Snazzy",
	"Spiffy",
	"Spirited",
	"Splendid",
	"Sprightly",
	"Stealthy",
	"Ticklish",
	"Tireless",
	"Toasty",
	"Tricky",
	"Unflappable",
	"Valiant",
	"Vigilant",
	"Whimsical",
	"Wobbly",
	"Woolly",
	"Zippy",
}

AardmanAdjectives contains spirited, eccentric, and charming adjectives celebrating Wallace & Gromit and classic British colloquialisms.

var AardmanCharacters = []string{

	"Wallace",
	"Gromit",
	"Feathers McGraw",
	"Wendolene Ramsbottom",
	"Shaun the Sheep",
	"Preston the Cyberdog",
	"Lady Campanula Tottington",
	"Lord Victor Quartermaine",
	"Philip the Dog",
	"Piella Bakewell",
	"Fluffles",
	"The Cooker",
	"PC Mackintosh",
	"Hutch the Rabbit",
	"Reverend Clement Hedges",
	"Norbot the Smart Gnome",
	"Major Crum",
	"Mr Caliche",

	"Ginger",
	"Rocky Rhodes",
	"Fowler",
	"Babs",
	"Bunty",
	"Mac",
	"Nick and Fetcher",
	"Mrs Tweedy",
	"Mr Tweedy",
	"Molly",
	"Frizzle",

	"Morph",
	"Chas",
	"Delilah",
	"Grandmorph",
	"Gillespie",
	"Nailbrush",

	"Bitzer",
	"The Farmer",
	"Shirley",
	"Timmy",
	"The Naughty Pigs",
	"Slip",
	"Agent Trumper",
	"Lu-La",

	"Frank the Tortoise",
	"Rex the Dog",
	"Pickles the Pug",
	"Trixie",

	"Roddy St James",
	"Rita Malone",
	"The Toad",
	"Whitey",
	"Spike",
	"Le Frog",
	"Sid",

	"The Pirate Captain",
	"Pirate with a Scarf",
	"Albino Pirate",
	"Pirate with Gout",
	"Surprisingly Curvaceous Pirate",
	"Polly the Dodo",
	"Charles Darwin",
	"Mr Bobo",
	"Queen Victoria",

	"Dug",
	"Hognob",
	"Goona",
	"Lord Nooth",
	"Treebor",

	"Robin",
	"Magpie",
	"Cat",
	"Dad Mouse",
}

AardmanCharacters contains memorable characters from the Wallace & Gromit and Aardman Animations filmography (Chicken Run, Morph, Shaun the Sheep, etc.).

var AardmanInventions = []string{
	"Techno Trousers",
	"Knit-o-matic",
	"Snoozatron",
	"Bun-vac 6000",
	"Anti-Pesto Van",
	"Rocket Ship",
	"Porridge Gun",
	"Autochef",
	"Tellyscope",
	"Wensleydale",
	"Red Leicester",
	"Stinking Bishop",
	"Smashing Cheddar",
	"Cracking Toast",
	"West Wallaby Street",
	"Top Bun Bakery",
	"The Wrong Trousers",
	"A Grand Day Out",
	"A Close Shave",
	"A Matter of Loaf and Death",
	"The Curse of the Were-Rabbit",
	"Vengeance Most Fowl",
}

AardmanInventions contains famous contraptions, locations, and iconic cheeses from 62 West Wallaby Street and beyond.

var AardmanNouns = append(append([]string{}, AardmanCharacters...), AardmanInventions...)

AardmanNouns combines all Aardman characters and inventions.

var First = []string{}/* 393 elements not displayed */

First contains a classic list of adjectives used for GeneratePair and GeneratePairSlug.

var Second = []string{}/* 4275 elements not displayed */

Second contains a classic list of names used for GeneratePair and GeneratePairSlug.

Functions

func FormatTaskID

func FormatTaskID(slug string) string

FormatTaskID appends a 4-hex collision-resistant suffix to any given slug. If slug is empty, only the random hex suffix is returned without leading hyphens.

Example

package main

import (
	"fmt"
	"strings"

	"github.com/dreh23/nicename"
)

func main() {
	taskID := nicename.FormatTaskID("custom-worker-task")
	// Output will be something like "custom-worker-task-8f2a"
	fmt.Println(strings.HasPrefix(taskID, "custom-worker-task-"))
}

Output:
true

func GenerateAardman

func GenerateAardman() string

GenerateAardman generates a spirited Aardman / Wallace & Gromit themed pair (e.g. "Cracking Gromit", "Cheesy Techno Trousers").

Example

package main

import (
	"fmt"

	"github.com/dreh23/nicename"
)

func main() {
	aardman := nicename.GenerateAardman()
	// Output will be something like "Cracking Gromit"
	fmt.Println(aardman != "")
}

Output:
true

func GenerateAardmanCharacter

func GenerateAardmanCharacter() string

GenerateAardmanCharacter generates a pair pairing an adjective with a specific character from the Aardman universe (e.g. "Clever Feathers McGraw").

func GenerateAardmanSlug

func GenerateAardmanSlug() string

GenerateAardmanSlug generates a URL- and Git-branch-friendly slug from the Aardman dataset (e.g. "cracking-gromit", "plucky-feathers-mcgraw").

Example

package main

import (
	"fmt"
	"strings"

	"github.com/dreh23/nicename"
)

func main() {
	slug := nicename.GenerateAardmanSlug()
	// Output will be something like "cracking-gromit"
	fmt.Println(strings.Contains(slug, "-"))
}

Output:
true

func GenerateCustom

func GenerateCustom(adjectives []string, nouns []string, separator string, toSlug bool) string

GenerateCustom picks an adjective and a noun from custom slices, joining them with separator.

Example

package main

import (
	"fmt"
	"strings"

	"github.com/dreh23/nicename"
)

func main() {
	adjectives := []string{"Grand", "Smashing"}
	nouns := []string{"Contraption", "Rocket"}

	name := nicename.GenerateCustom(adjectives, nouns, "-", true)
	// Returns lowercase slug joined by hyphen
	fmt.Println(strings.HasPrefix(name, "grand-") || strings.HasPrefix(name, "smashing-"))
}

Output:
true

func GeneratePair

func GeneratePair() string

GeneratePair generates a classic random adjective + name pair from the original dataset (e.g. "Adventurous Mary"). Preserves full backwards compatibility.

Example

package main

import (
	"fmt"
	"strings"

	"github.com/dreh23/nicename"
)

func main() {
	pair := nicename.GeneratePair()
	// Output will be something like "Adventurous Mary"
	fmt.Println(len(strings.Split(pair, " ")) >= 2)
}

Output:
true

func GeneratePairSlug

func GeneratePairSlug() string

GeneratePairSlug generates a lowercase, kebab-cased slug from the original dataset (e.g. "adventurous-mary").

func GenerateTaskID

func GenerateTaskID() string

GenerateTaskID returns a unique, collision-resistant identifier ideal for worker tasks, git branches, and container names (e.g. "cracking-gromit-8f2a").

Example

package main

import (
	"fmt"

	"github.com/dreh23/nicename"
)

func main() {
	taskID := nicename.GenerateTaskID()
	// Output will be something like "cracking-gromit-8f2a"
	fmt.Println(len(taskID) > 5)
}

Output:
true

func Slugify

func Slugify(s string) string

Slugify converts any string into a clean lowercase, hyphen-separated slug, stripping special punctuation while preserving alphanumeric words.

Example

package main

import (
	"fmt"

	"github.com/dreh23/nicename"
)

func main() {
	fmt.Println(nicename.Slugify("Feathers McGraw"))
	fmt.Println(nicename.Slugify("Bun-vac 6000"))
	fmt.Println(nicename.Slugify("  Cracking   Toast!  "))
}

Output:
feathers-mcgraw
bun-vac-6000
cracking-toast