Redirected from 
README
¶
fname
Generate random, human-friendly names, like determined-pancake or sinister discovery. fname is like a grammatically aware diceware generator for unique names or identifiers.
fname isn't meant to provide a secure, globally unique identifier, but with over 500 billion possible combinations, it's good enough for most non-critical use cases.
Table of Contents
Installation
Download
Download the latest release from the releases page.
Go
go install github.com/splode/fname/cmd/fname@latest
Source
git clone https://github.com/splode/fname.git
cd fname
go install ./cmd/fname
Usage
CLI
Generate a single, random name phrase:
$ fname
extinct-green
Generate multiple name phrases, passing the number of names as an argument:
$ fname --quantity 3
influential-length
direct-ear
cultural-storage
Generate a name phrase with a custom delimiter:
$ fname --delimiter "__"
glaring__perception
Generate a name phrase with more words:
$ fname --size 3
vengeful-toy-identified
$ fname --size 4
spellbinding-project-presented-fully
Note: the minimum phrase size is 2 (default), and the maximum is 4.
Generate a name phrase with a specific casing:
$ fname --casing upper
TRAGIC-MOUNTAIN
$ fname --casing title
Whimsical-Party
Specify the seed for generating names:
$ fname --seed 123 --quantity 2
pleasant-joy
eligible-tenant
$ fname --seed 123 --quantity 2
pleasant-joy
eligible-tenant
Generate names as a JSON array (useful for scripting):
$ fname --format json --quantity 3
["influential-length","direct-ear","cultural-storage"]
$ fname -f json
["extinct-green"]
Library
Install
go get github.com/splode/fname
Basic Usage
package main
import (
"fmt"
"github.com/splode/fname"
)
func main() {
rng := fname.NewGenerator()
phrase, err := rng.Generate()
fmt.Println(phrase)
// => "influential-length"
}
Customization
package main
import (
"fmt"
"github.com/splode/fname"
)
func main() {
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
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.
fname's dictionary is curated to exclude words that are offensive, or could be considered offensive, either alone or when generated in a phrase. Nevertheless, all cases are not and cannot be covered. If you find a word that you think should be removed, please open an issue.
Contributing
We welcome contributions to the fname project! Whether it's reporting bugs, suggesting improvements, or submitting new features, your input is valuable to us. Here's how you can get started:
- Fork the repository on GitHub.
- Clone your fork and create a new branch for your changes.
- Make your changes and commit them to your branch.
- Create a pull request, and provide a clear description of your changes.
Before submitting a pull request, please make sure your changes are well-tested and adhere to the code style used throughout the project. If you are unsure how to proceed or need help, feel free to open an issue or ask a question in the discussions section.
Reporting Issues
If you encounter a bug or any issue, please open an issue on GitHub. When reporting a bug, try to include as much information as possible, such as the steps to reproduce the issue, the expected behavior, and the actual behavior. This will help us diagnose and fix the issue more efficiently.
Suggesting Improvements
We are always looking for ways to improve fname. If you have a suggestion for a new feature or an enhancement to an existing feature, please open an issue or start a discussion in the discussions section. Be sure to explain your idea in detail, and if possible, provide examples or use cases.
Thank you for your interest in contributing to fname!
License
Related Projects
Documentation
¶
Overview ¶
Package fname contains functions for generating random, human-friendly names.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Casing ¶ added in v0.2.0
type Casing int
func CasingFromString
deprecated
added in
v0.4.0
func ParseCasing ¶ added in v0.2.0
ParseCasing parses a casing string and returns the corresponding Casing value.
type Dictionary ¶
type Dictionary struct {
// contains filtered or unexported fields
}
Dictionary is a collection of words.
func NewCustomDictionary ¶ added in v0.5.0
func NewCustomDictionary(adjectives, adverbs, nouns, verbs []string) *Dictionary
NewCustomDictionary creates a Dictionary with caller-supplied word lists. Any nil slice falls back to the corresponding default embedded word list.
func NewDictionary ¶
func NewDictionary() *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 (*Dictionary) LengthAdjective ¶
func (d *Dictionary) LengthAdjective() int
LengthAdjective returns the number of adjectives in the dictionary.
func (*Dictionary) LengthAdverb ¶
func (d *Dictionary) LengthAdverb() int
LengthAdverb returns the number of adverbs in the dictionary.
func (*Dictionary) LengthNoun ¶
func (d *Dictionary) LengthNoun() int
LengthNoun returns the number of nouns in the dictionary.
func (*Dictionary) LengthVerb ¶
func (d *Dictionary) LengthVerb() int
LengthVerb returns the number of verbs in the dictionary.
type Generator ¶
type Generator struct {
// contains filtered or unexported fields
}
Generator generates random name phrases. It is not safe for concurrent use from multiple goroutines; create a separate Generator per goroutine instead.
func NewGenerator ¶
func NewGenerator(opts ...GeneratorOption) *Generator
NewGenerator creates a new Generator.
type GeneratorOption ¶
type GeneratorOption func(*Generator)
GeneratorOption is a function that configures a Generator.
func WithCasing ¶ added in v0.2.0
func WithCasing(casing Casing) GeneratorOption
WithCasing sets the casing used to format the generated name.
func WithDelimiter ¶
func WithDelimiter(delimiter string) GeneratorOption
WithDelimiter sets the delimiter used to join words.
func WithDictionary ¶ added in v0.5.0
func WithDictionary(d *Dictionary) GeneratorOption
WithDictionary sets a custom Dictionary on the Generator. If d is nil, the default embedded Dictionary is used.
func WithSeed ¶
func WithSeed(seed int64) GeneratorOption
WithSeed sets the seed used to generate random numbers.
func WithSize ¶
func WithSize(size uint) (GeneratorOption, error)
WithSize sets the number of words in the generated name. Returns an error if size is outside the valid range [2, 4].
Source Files
Directories