diff --git a/CHANGELOG.md b/CHANGELOG.md index 9020008..5ec72e7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,20 +1,5 @@ # Changelog -### [1.0.0] - 2025-03-31 - 🚀 Stable release! - -#### Support - -- 📝 Vastly improved [go docs](https://pkg.go.dev/codeberg.org/danjones000/nomino). -- 📝 Fill out README with examples and links. - -#### Tools - -- 🛠 Replace all linting with golangci-lint - -#### Code quality - -- 🚨 A bunch of small improvements from new linter - ### [0.5.0] - 2025-03-19 - ✨ Different types of UUIDs #### Features diff --git a/README.md b/README.md index e0b3f51..09b7bb7 100644 --- a/README.md +++ b/README.md @@ -4,80 +4,10 @@ The purpose of nomino is to generate (probably random) filenames, for example, i It takes a lot of inspiration (although no actual code) from [Onym](https://github.com/Blaspsoft/onym). -Make sure to check out the [official documentation][docs]. +Note that this is still not at a stable release. There will be breaking changes between minor releases until it reaches 1.0.0. Patch releases shouldn't contain breaking changes however. Once it reaches 1.0.0, breaking changes will only happen between major releases. -## Installation +## TODO -Add `codeberg.org/danjones000/nomino` to your project. You can do `go get codeberg.org/danjones000/nomino`, or simply add it to an import and run `go mod tidy`. +I'll fill this out more in depth later. -But, you probably already know this. - -## Usage - -There are **a lot** of examples in the [official documentation][examples]. Take a look through these to get an idea. - -The main concept in `nomino` is the [Generator][]. The simplest way to generate a random filename, is to use the [Generator][] directly, in this way: - -```go -import ( - "fmt" - "codeberg.org/danjones000/nomino" -) - -func main() { - name, _ := nomino.Random().Make() - fmt.Println(name) // Du3Sfh8p.txt -} -``` - -The second argument is an error. Most of the generators are always successful, and that error will be `nil`, but you should check the errors if you're not sure. - -The second way to generate a new filename is using the [Make][] function. - -```go -import ( - "fmt" - "codeberg.org/danjones000/nomino" -) - -func main() { - config := nomino.NewConfig(nomino.WithGenerator(nomino.Random())) - name, _ := nomino.Make(config) - fmt.Println(name) // Du3Sfh8p.txt -} -``` - -Although in these examples, `nomino.Make` is more verbose, it can be beneficial to using that function if you have some customizations to how you generate the filenames. - -### Configuration - -The [Config][] allows you to customize how the generated filename works with various [Options][Option]. The [options][Option] allows you to customize things like [adding a prefix](https://pkg.go.dev/codeberg.org/danjones000/nomino#WithPrefix), or changing the [extension](https://pkg.go.dev/codeberg.org/danjones000/nomino#WithExtension) of the generated filename (by default, it uses `.txt`). - -Have a look at [all the Options][Option]. - -### Generator - -The [Generator][] is the piece that returns the "random" portion of the generated filename, although, it doesn't actually have to be random. - -Here are the built-in [Generators][Generator]: - -- [UUID](https://pkg.go.dev/codeberg.org/danjones000/nomino#UUID) generates a UUID. This is the default if none is specified. -- [Random](https://pkg.go.dev/codeberg.org/danjones000/nomino#Random) generates a random string. By default, it's 8 characters long, but can be whatever length you provide. -- [Incremental](https://pkg.go.dev/codeberg.org/danjones000/nomino#Incremental) will generate just a series of integers, starting at 0. -- [Timestamp](https://pkg.go.dev/codeberg.org/danjones000/nomino#Timestamp) generates a string from the current time. It will look like "2009-11-10T23-00-00+0000.txt", although this can be customized. -- Both [Slug](https://pkg.go.dev/codeberg.org/danjones000/nomino#Slug) and [Hash](https://pkg.go.dev/codeberg.org/danjones000/nomino#Hash) work on the original name provided by [WithOriginal](https://pkg.go.dev/codeberg.org/danjones000/nomino#WithOriginal). Slug generats a slug from the name, while Hash hashes it. By default, it uses MD5. - -You can also use multiple generators, either [in order](https://pkg.go.dev/codeberg.org/danjones000/nomino#MultiGeneratorInOrder), or [in a random order](https://pkg.go.dev/codeberg.org/danjones000/nomino#MultiGeneratorRandomOrder). - -Finally, you can create a [custom generator](https://pkg.go.dev/codeberg.org/danjones000/nomino#example-WithGenerator-CustomGenerator) as well. - -## RTFM (Read the fabulous manual) - -[Official docs][docs], especially the [examples][]. Especially check out the [full example](https://pkg.go.dev/codeberg.org/danjones000/nomino#example-package), which includes how to use a global configuration. - -[docs]: https://pkg.go.dev/codeberg.org/danjones000/nomino -[examples]: https://pkg.go.dev/codeberg.org/danjones000/nomino#pkg-examples -[Generator]: https://pkg.go.dev/codeberg.org/danjones000/nomino#Generator -[Config]: https://pkg.go.dev/codeberg.org/danjones000/nomino#Config -[Option]: https://pkg.go.dev/codeberg.org/danjones000/nomino#Option -[Make]: https://pkg.go.dev/codeberg.org/danjones000/nomino#Make +For now, check [official documentation](https://pkg.go.dev/codeberg.org/danjones000/nomino). diff --git a/config.go b/config.go index 54456bf..0c06449 100644 --- a/config.go +++ b/config.go @@ -10,7 +10,7 @@ type Config struct { generator Generator } -// NewConfig returns a new [Config] with each [Option] specified. +// NewConfig returns a new [Config] with the specified [Option]s. // With no Options, the Config uses an extension of .txt, a separator // of _, and the [UUID] [Generator]. func NewConfig(options ...Option) Config { @@ -25,7 +25,7 @@ func NewConfig(options ...Option) Config { return conf } -// AddOptions creates a new [Config] with each [Option] added. +// AddOptions creates a new [Config] with the given [Option]s added. func (c Config) AddOptions(options ...Option) Config { for _, opt := range options { opt(&c) diff --git a/gen_rand.go b/gen_rand.go index 69f0487..7a9e9ea 100644 --- a/gen_rand.go +++ b/gen_rand.go @@ -8,7 +8,7 @@ import ( "github.com/google/uuid" ) -// UUIDer is an interface for generating UUIDs, by the [UUID] [Generator]. +// UUIDer is an interface for generating UUIDs. // It is recommended that you use either the [UUIDv4] or [UUIDv7] variables. type UUIDer interface { UUID() (uuid.UUID, error) diff --git a/generators.go b/generators.go index 28b666b..fe7b59d 100644 --- a/generators.go +++ b/generators.go @@ -28,7 +28,7 @@ func WithGenerator(g Generator) Option { } } -// ErrMissingGenerators is returned by a multi-generator if a [Generator] isn't supplied. +// ErrMissingGenerators is returned by a multi-generator if no [Generator]s are supplied. var ErrMissingGenerators = errors.New("no generators supplied") func missingGen(*Config) (string, error) {