feat: Generate names as a JSON array.

- Support custom dictionary.
- Various code cleanup.

Author: Splode

README.md

@@ -108,6 +108,16 @@ pleasant-joy
 eligible-tenant
 ```
 
+Generate names as a JSON array (useful for scripting):
+
+```sh
+$ fname --format json --quantity 3
+["influential-length","direct-ear","cultural-storage"]
+
+$ fname -f json
+["extinct-green"]
+```
+
 ### Library
 
 #### Install
@@ -147,13 +157,42 @@ import (
 )
 
 func main() {
-  rng := fname.NewGenerator(fname.WithDelimiter("__"), fname.WithSize(3))
+  sizeOpt, err := fname.WithSize(3)
+  if err != nil {
+    panic(err)
+  }
+  rng := fname.NewGenerator(fname.WithDelimiter("__"), sizeOpt)
   phrase, err := rng.Generate()
   fmt.Println(phrase)
   // => "established__shark__destroyed"
 }
 ```
 
+#### Custom Dictionary
+
+```go
+package main
+
+import (
+  "fmt"
+
+  "github.com/splode/fname"
+)
+
+func main() {
+  dict := fname.NewCustomDictionary(
+    []string{"blazing", "frozen"},  // adjectives
+    nil,                             // adverbs (uses default)
+    []string{"comet", "nebula"},    // nouns
+    nil,                             // verbs (uses default)
+  )
+  rng := fname.NewGenerator(fname.WithDictionary(dict))
+  phrase, err := rng.Generate()
+  fmt.Println(phrase)
+  // => "blazing-nebula"
+}
+```
+
 ## Disclaimers
 
 fname is not cryptographically secure, and should not be used for anything that requires a truly unique identifier. It is meant to be a fun, human-friendly alternative to UUIDs.

cmd/fname/fname.go

@@ -2,6 +2,7 @@ package main
 
 import (
 	_ "embed"
+	"encoding/json"
 	"fmt"
 	"log"
 	"os"
@@ -45,6 +46,7 @@ func main() {
 	var (
 		casing    string = "lower"
 		delimiter string = "-"
+		format    string = "plain"
 		help      bool
 		ver       bool
 		quantity  int  = 1
@@ -54,6 +56,7 @@ func main() {
 
 	pflag.StringVarP(&casing, "casing", "c", casing, "set the casing of the generated name <title|upper|lower>")
 	pflag.StringVarP(&delimiter, "delimiter", "d", delimiter, "set the delimiter used to join words")
+	pflag.StringVarP(&format, "format", "f", format, "set the output format <plain|json>")
 	pflag.IntVarP(&quantity, "quantity", "q", quantity, "set the number of names to generate")
 	pflag.UintVarP(&size, "size", "z", size, "set the number of words in the generated name (minimum 2, maximum 4)")
 	pflag.Int64VarP(&seed, "seed", "s", 0, "random generator seed")
@@ -71,7 +74,15 @@ func main() {
 		os.Exit(0)
 	}
 
-	c, err := fname.CasingFromString(casing)
+	if quantity <= 0 {
+		log.Fatalf("error: quantity must be greater than 0, got %d", quantity)
+	}
+
+	if format != "plain" && format != "json" {
+		log.Fatalf("error: invalid format %q, must be plain or json", format)
+	}
+
+	c, err := fname.ParseCasing(casing)
 	handleError(err)
 
 	opts := []fname.GeneratorOption{
@@ -83,15 +94,29 @@ func main() {
 		opts = append(opts, fname.WithSeed(seed))
 	}
 	if size != 2 {
-		opts = append(opts, fname.WithSize(size))
+		sizeOpt, err := fname.WithSize(size)
+		handleError(err)
+		opts = append(opts, sizeOpt)
 	}
 
 	rng := fname.NewGenerator(opts...)
 
+	names := make([]string, 0, quantity)
 	for i := 0; i < quantity; i++ {
 		name, err := rng.Generate()
 		handleError(err)
-		fmt.Println(name)
+		names = append(names, name)
+	}
+
+	switch format {
+	case "json":
+		out, err := json.Marshal(names)
+		handleError(err)
+		fmt.Println(string(out))
+	default:
+		for _, name := range names {
+			fmt.Println(name)
+		}
 	}
 }
 

dictionary.go

@@ -2,7 +2,6 @@
 package fname
 
 import (
-	"bufio"
 	_ "embed"
 	"strings"
 )
@@ -31,9 +30,9 @@ type Dictionary struct {
 	verbs      []string
 }
 
-// NewDictionary creates a new dictionary.
+// NewDictionary creates a new Dictionary backed by the default embedded word lists.
+// To use custom word lists, use NewCustomDictionary and pass it via WithDictionary.
 func NewDictionary() *Dictionary {
-	// TODO: allow for custom dictionary
 	return &Dictionary{
 		adjectives: adjective,
 		adverbs:    adverb,
@@ -42,6 +41,25 @@ func NewDictionary() *Dictionary {
 	}
 }
 
+// NewCustomDictionary creates a Dictionary with caller-supplied word lists.
+// Any nil slice falls back to the corresponding default embedded word list.
+func NewCustomDictionary(adjectives, adverbs, nouns, verbs []string) *Dictionary {
+	d := NewDictionary()
+	if adjectives != nil {
+		d.adjectives = adjectives
+	}
+	if adverbs != nil {
+		d.adverbs = adverbs
+	}
+	if nouns != nil {
+		d.nouns = nouns
+	}
+	if verbs != nil {
+		d.verbs = verbs
+	}
+	return d
+}
+
 // LengthAdjective returns the number of adjectives in the dictionary.
 func (d *Dictionary) LengthAdjective() int {
 	return len(d.adjectives)
@@ -63,11 +81,5 @@ func (d *Dictionary) LengthVerb() int {
 }
 
 func split(s string) []string {
-	scanner := bufio.NewScanner(strings.NewReader(s))
-	scanner.Split(bufio.ScanLines)
-	var lines []string
-	for scanner.Scan() {
-		lines = append(lines, scanner.Text())
-	}
-	return lines
+	return strings.Split(strings.TrimRight(s, "\n"), "\n")
 }

generator.go

@@ -31,7 +31,8 @@ func (c Casing) String() string {
 	}
 }
 
-func CasingFromString(casing string) (Casing, error) {
+// ParseCasing parses a casing string and returns the corresponding Casing value.
+func ParseCasing(casing string) (Casing, error) {
 	switch strings.ToLower(casing) {
 	case Lower.String():
 		return Lower, nil
@@ -44,6 +45,13 @@ func CasingFromString(casing string) (Casing, error) {
 	}
 }
 
+// Deprecated: Use ParseCasing instead.
+func CasingFromString(casing string) (Casing, error) {
+	return ParseCasing(casing)
+}
+
+// Generator generates random name phrases. It is not safe for concurrent use
+// from multiple goroutines; create a separate Generator per goroutine instead.
 type Generator struct {
 	casing    Casing
 	dict      *Dictionary
@@ -69,6 +77,16 @@ func WithDelimiter(delimiter string) GeneratorOption {
 	}
 }
 
+// WithDictionary sets a custom Dictionary on the Generator.
+// If d is nil, the default embedded Dictionary is used.
+func WithDictionary(d *Dictionary) GeneratorOption {
+	return func(g *Generator) {
+		if d != nil {
+			g.dict = d
+		}
+	}
+}
+
 // WithSeed sets the seed used to generate random numbers.
 func WithSeed(seed int64) GeneratorOption {
 	return func(g *Generator) {
@@ -77,10 +95,14 @@ func WithSeed(seed int64) GeneratorOption {
 }
 
 // WithSize sets the number of words in the generated name.
-func WithSize(size uint) GeneratorOption {
+// Returns an error if size is outside the valid range [2, 4].
+func WithSize(size uint) (GeneratorOption, error) {
+	if size < 2 || size > 4 {
+		return nil, fmt.Errorf("invalid size: %d", size)
+	}
 	return func(g *Generator) {
 		g.size = size
-	}
+	}, nil
 }
 
 // NewGenerator creates a new Generator.
@@ -100,16 +122,9 @@ func NewGenerator(opts ...GeneratorOption) *Generator {
 
 // Generate generates a random name.
 func (g *Generator) Generate() (string, error) {
-	if g.size < 2 || g.size > 4 {
-		return "", fmt.Errorf("invalid size: %d", g.size)
-	}
-
 	words := make([]string, 0, g.size)
 	adjectiveIndex := g.rand.Intn(g.dict.LengthAdjective())
 	nounIndex := g.rand.Intn(g.dict.LengthNoun())
-	for adjectiveIndex == nounIndex {
-		nounIndex = g.rand.Intn(g.dict.LengthNoun())
-	}
 
 	words = append(words, g.dict.adjectives[adjectiveIndex], g.dict.nouns[nounIndex])
 
@@ -124,19 +139,18 @@ func (g *Generator) Generate() (string, error) {
 	return strings.Join(g.applyCasing(words), g.delimiter), nil
 }
 
+var titleCaser = cases.Title(language.English)
+
 func (g *Generator) applyCasing(words []string) []string {
-	if fn, ok := casingMap[g.casing]; ok {
-		for i, word := range words {
-			words[i] = fn(word)
+	for i, word := range words {
+		switch g.casing {
+		case Lower:
+			words[i] = strings.ToLower(word)
+		case Upper:
+			words[i] = strings.ToUpper(word)
+		case Title:
+			words[i] = titleCaser.String(word)
 		}
 	}
 	return words
 }
-
-var titleCaser = cases.Title(language.English)
-
-var casingMap = map[Casing]func(string) string{
-	Lower: strings.ToLower,
-	Upper: strings.ToUpper,
-	Title: titleCaser.String,
-}

generator_test.go

@@ -24,7 +24,11 @@ func TestNewGenerator(t *testing.T) {
 
 		t.Log("\tWhen creating a new Generator with custom values")
 		{
-			g := NewGenerator(WithCasing(Title), WithDelimiter("_"), WithSize(3), WithSeed(12345))
+			sizeOpt, err := WithSize(3)
+			if err != nil {
+				t.Fatal("\t\tShould be able to create a size option without error.")
+			}
+			g := NewGenerator(WithCasing(Title), WithDelimiter("_"), sizeOpt, WithSeed(12345))
 			if g == nil {
 				t.Fatal("\t\tShould be able to create a Generator instance.")
 			}
@@ -114,7 +118,11 @@ func TestGenerate(t *testing.T) {
 
 		t.Log("\tWhen generating a phrase with a custom size")
 		{
-			g3 := NewGenerator(WithSize(3))
+			size3Opt, err := WithSize(3)
+			if err != nil {
+				t.Fatal("\t\tShould be able to create a size-3 option without error.")
+			}
+			g3 := NewGenerator(size3Opt)
 			phrase, err := g3.Generate()
 			if err != nil {
 				t.Fatal("\t\tShould be able to generate a phrase without error.")
@@ -132,7 +140,11 @@ func TestGenerate(t *testing.T) {
 			}
 			t.Log("\t\tShould be able to generate a phrase with 3 parts.")
 
-			g4 := NewGenerator(WithSize(4))
+			size4Opt, err := WithSize(4)
+			if err != nil {
+				t.Fatal("\t\tShould be able to create a size-4 option without error.")
+			}
+			g4 := NewGenerator(size4Opt)
 			phrase, err = g4.Generate()
 			if err != nil {
 				t.Fatal("\t\tShould be able to generate a phrase without error.")
@@ -175,12 +187,50 @@ func TestGenerate(t *testing.T) {
 
 		t.Log("\tWhen generating a phrase with an invalid size")
 		{
-			g := NewGenerator(WithSize(1))
-			_, err := g.Generate()
+			_, err := WithSize(1)
 			if err == nil {
-				t.Fatal("\t\tShould not be able to generate a phrase with an invalid size.")
+				t.Fatal("\t\tShould not be able to create a size option with an invalid size.")
+			}
+			t.Log("\t\tShould not be able to create a size option with an invalid size.")
+		}
+	}
+}
+
+func TestWithDictionary(t *testing.T) {
+	t.Log("Given the need to test the WithDictionary option")
+	{
+		t.Log("\tWhen generating with a custom dictionary")
+		{
+			custom := NewCustomDictionary(
+				[]string{"fast"},
+				nil,
+				[]string{"rocket"},
+				nil,
+			)
+			g := NewGenerator(WithDictionary(custom), WithSeed(1))
+			phrase, err := g.Generate()
+			if err != nil {
+				t.Fatal("\t\tShould be able to generate a phrase without error.")
+			}
+			t.Log("\t\tShould be able to generate a phrase without error.")
+
+			if phrase != "fast-rocket" {
+				t.Fatalf("\t\tShould generate phrase from custom words, got: %s", phrase)
+			}
+			t.Log("\t\tShould generate phrase from custom words.")
+		}
+
+		t.Log("\tWhen passing nil dictionary")
+		{
+			g := NewGenerator(WithDictionary(nil))
+			phrase, err := g.Generate()
+			if err != nil {
+				t.Fatal("\t\tShould fall back to default dictionary without error.")
+			}
+			if len(phrase) == 0 {
+				t.Fatal("\t\tShould produce a non-empty phrase with default dictionary.")
 			}
-			t.Log("\t\tShould not be able to generate a phrase with an invalid size.")
+			t.Log("\t\tShould fall back to default dictionary.")
 		}
 	}
 }