A Go library that generates acrostical phrases and secure passphrases from words or random letter combinations.

An acrostic phrase uses the first letter of each word to spell out a word or message. This library generates memorable phrases using curated word lists of over 4,600 adjectives and 9,300 nouns, providing strong entropy for passphrase generation.

• Large word lists with excellent letter distribution
• Flexible options pattern for customization
• Secure passphrase generation with configurable entropy
• Multiple output formats: custom separators, capitalization, number suffixes
• Cryptographically secure random number generation

The library provides strong entropy for secure passphrases:

go get github.com/awoodbeck/acrostic

package main

import (
  "fmt"
  "log"

  "github.com/awoodbeck/acrostic"
)

func main() {
  // Create a new acrostic generator with default word lists
  a, err := acrostic.NewAcrostic(nil, nil)
  if err != nil {
    log.Fatal(err)
  }

  // Generate a single acrostic for a word
  phrase, err := a.GenerateAcrostic("golang")
  if err != nil {
    log.Fatal(err)
  }

  fmt.Println(phrase)
  // Example output: "graceful optimistic lively adorable noble gorilla"
}

// Generate 5 different acrostics for the same word
phrases, err := a.GenerateAcrostics("test", 5)
if err != nil {
  log.Fatal(err)
}

for i, phrase := range phrases {
  fmt.Printf("%d: %s\n", i+1, phrase)
}

// Generate a random 4-word acrostic
phrase, err := a.GenerateRandomAcrostic(4)
if err != nil {
  log.Fatal(err)
}

fmt.Println(phrase)
// Example output: "brave elegant creative dragon"

// Generate multiple random phrases
phrases, err := a.GenerateRandomPhrases(5, 3)
if err != nil {
  log.Fatal(err)
}

// Generate a secure passphrase with custom formatting
phrase, err := a.GenerateAcrostic("secure",
  acrostic.WithSeparator("-"),
  acrostic.WithNumber(0, 9999),
  acrostic.WithCapitalization(acrostic.CapitalizeFirst),
)
// Example output: "Silly-Elegant-Careful-Unusual-Rapid-Elephant-7342"

// Random passphrase with all options
phrase, err = a.GenerateRandomPhrase(5,
  acrostic.WithSeparator("_"),
  acrostic.WithNumber(100, 999),
  acrostic.WithCapitalization(acrostic.CapitalizeFirst),
)
// Example output: "Brave_Quick_Gentle_Modern_Tiger_456"

All generation methods accept optional configuration:

Set a custom separator between words (default: space).

phrase, _ := a.GenerateAcrostic("test", acrostic.WithSeparator("-"))
// Output: "tiny-eager-smart-turtle"

Add a random number to the phrase (adds ~13.3 bits of entropy for 0-9999).

phrase, _ := a.GenerateAcrostic("test", acrostic.WithNumber(0, 9999))
// Output: "tiny eager smart turtle 4782"

Control where the number appears:

• NumberPositionEnd (default)
• NumberPositionBeginning
• NumberPositionRandom

phrase, _ := a.GenerateAcrostic("test",
  acrostic.WithNumber(1000, 9999),
  acrostic.WithNumberPosition(acrostic.NumberPositionBeginning),
)
// Output: "5432 tiny eager smart turtle"

Set capitalization style:

• CapitalizeNone (default)
• CapitalizeFirst - capitalize first letter of each word
• CapitalizeAll - all uppercase
• CapitalizeRandom - randomly capitalize letters

phrase, _ := a.GenerateAcrostic("test",
  acrostic.WithCapitalization(acrostic.CapitalizeFirst),
)
// Output: "Tiny Eager Smart Turtle"

• NewAcrostic(adjWords, nounWords *words.Words) (*Acrostic, error)
  • Creates a new acrostic generator. Pass nil for both arguments to use default word lists (recommended).

All methods accept optional Option parameters for customization.

• GenerateAcrostic(acro string, opts ...Option) (string, error)

  • Generate a single acrostic phrase for the given word.

• GenerateAcrostics(acro string, num int, opts ...Option) ([]string, error)

  • Generate multiple acrostic phrases for the given word.

• GenerateRandomAcrostic(length int, opts ...Option) (string, error)

  • Generate a single random acrostic of the specified length.

• GenerateRandomAcrostics(length, num int, opts ...Option) ([]string, error)

  • Generate multiple random acrostics of the specified length.

• GenerateRandomPhrase(phraseLen int, opts ...Option) (string, error)

  • Generate a single random phrase with the specified number of words.

• GenerateRandomPhrases(phraseLen, phraseNum int, opts ...Option) ([]string, error)

  • Generate multiple random phrases with the specified number of words each.

• WithSeparator(sep string) Option
• WithNumber(min, max int) Option
• WithNumberPosition(pos NumberPosition) Option
• WithCapitalization(mode CapitalizeMode) Option

Run tests with race detection:

go test -race ./...

Run benchmarks:

go test -bench=. ./...

This library uses curated word lists sourced from:

• Adjectives: 5,069 English adjectives (filtered to 4,615)
• Nouns: Top 10,000 English nouns from Google ngrams (filtered to 9,380)

Word lists are filtered to include only 3-12 character words with letters only, ensuring memorable and typeable passphrases.

See LICENSE file for details.

Sources:

• EFF's New Wordlists for Random Passphrases
• EFF Large Wordlist
• Comprehensive adjectives list on GitHub
• Top English word lists by frequency