# 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