83 lines
4.2 KiB
Markdown
83 lines
4.2 KiB
Markdown
# nomino - A filename generator
|
|
|
|
The purpose of nomino is to generate (probably random) filenames, for example, if you want to save an uploaded file to storage under a new name.
|
|
|
|
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].
|
|
|
|
## Installation
|
|
|
|
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`.
|
|
|
|
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
|