Documentation
¶
Overview ¶
Package nomino is a utility that allows us to generate random filenames.
There are two main methods of using nomino.
- Using the Make function.
- Creating a generator, and using its Generator.Make method.
Example ¶
This example shows how to use nomino.
package main
import (
"fmt"
"codeberg.org/danjones000/nomino"
)
// Define a global Config.
func NominoConfig() nomino.Config {
return nomino.NewConfig(
nomino.WithSeparator("-"),
nomino.WithPrefix("upload"),
nomino.WithGenerator(nomino.UUID(
nomino.UUIDv7,
)),
)
}
// HandleImgUploads generates new filenames for images with a png extension.
func HandleImgUploads(orig string) string {
// Here, we use nomino.Make function to generate the filename.
// We use our global config, and add in a few extra Options specific to this.
newName, _ := nomino.Make(
NominoConfig(),
nomino.WithExtension("png"),
nomino.WithOriginalSlug(orig),
)
return newName
}
// HandleVidUploads generates a new filename for videos.
// We ignore the original filename and use a timestamp for the generated part
// with a webm extension.
func HandleVidUploads() string {
// Because we're using a different Generator, we chose to use the Make method on the Generator.
// We add in additional Options with the `AddOptions` method on the `Config`
newName, _ := nomino.Timestamp(nomino.TimestampUTC()).
MakeWithConfig(NominoConfig().AddOptions(
nomino.WithExtension("webm"),
))
return newName
}
// This example shows how to use nomino.
func main() {
// Pretend we have an image upload
filename := "George"
uploadImgName := HandleImgUploads(filename)
// Upload to storage
fmt.Println(uploadImgName)
// New Video Upload
uploadVidName := HandleVidUploads()
// Upload to storage
fmt.Println(uploadVidName)
}
Index ¶
- Constants
- Variables
- func Make(conf Config, opts ...Option) (string, error)
- type Config
- type Generator
- func Hash(h Hasher) Generator
- func Incremental(opts ...IncrementalOption) Generator
- func MultiGeneratorInOrder(gens ...Generator) Generator
- func MultiGeneratorRandomOrder(gens ...Generator) Generator
- func Random(opts ...RandomOption) Generator
- func Slug(lang ...string) Generator
- func Timestamp(opts ...TimestampOption) Generator
- func UUID(u UUIDer) Generator
- type Hasher
- type HashingFunc
- type IncrementalOption
- type Option
- func WithExtension(ext string) Option
- func WithGenerator(g Generator) Option
- func WithOriginal(o string) Option
- func WithOriginalSlug(o string) Option
- func WithOriginalSlugLang(o, lang string) Option
- func WithPrefix(p string) Option
- func WithSeparator(sep string) Option
- func WithSuffix(s string) Option
- func WithoutExtension() Option
- type RandomOption
- type TimestampOption
- type UUIDFunc
- type UUIDer
Examples ¶
- Package
- Generator.Make
- Hash (MD5)
- Hash (SHA1)
- Hash (SHA256)
- HashingFunc (HMAC)
- Incremental
- Incremental (WithStartAndStep)
- IncrementalFormat
- IncrementalStart
- IncrementalStep
- Make (Basic)
- Make (WithExtraOptions)
- MultiGeneratorInOrder
- MultiGeneratorRandomOrder
- Random
- RandomLength
- Slug
- Slug (WithLang)
- Timestamp
- TimestampFormat
- TimestampTime
- TimestampUTC
- UUID
- UUID (V7)
- WithExtension
- WithGenerator (CustomGenerator)
- WithOriginal
- WithOriginalSlug
- WithOriginalSlugLang
- WithPrefix
- WithSeparator
- WithSuffix
- WithoutExtension
Constants ¶
const FileTimestamp string = "2006-01-02T15-04-05-0700"
FileTimestamp is the default format for Timestamp.
const FileTimestampNoTZ string = "2006-01-02T15-04-05"
FileTimestampNoTZ is the default format when using the TimestampUTC TimestampOption.
Variables ¶
var ( // UUIDv1. You probably don't want to use this. It is included for completeness sake. UUIDv1 = UUIDFunc(uuid.NewUUID) // UUIDv4 is the default. UUIDv4 = UUIDFunc(uuid.NewRandom) // UUIDv6 is primarily a replacement for UUIDv1. You probably should use 4 or 7. UUIDv6 = UUIDFunc(uuid.NewV6) // UUIDv7 should be used if you want it sortable by time. UUIDv7 = UUIDFunc(uuid.NewV7) )
var ErrInvalidHash = errors.New("invalid hash type")
ErrInvalidHash is returned by the Hash Generator when an invalid Hasher is passed.
var ErrMissingGenerators = errors.New("no generators supplied")
ErrMissingGenerators is returned by a multi-generator if a Generator isn't supplied.
var ErrMissingOriginal = errors.New("missing original filename")
ErrMissingOriginal is the error returned by Slug if there is no filename.
Functions ¶
func Make ¶
Make generates a random filename. The behavior can be controlled by specifying Options. In general, the final filename will be [prefix]_[generated_string]_[original_filename]_[suffix].[extension]. If the name generator returns an error (generally, it shouldn't), that error will be returned instead.
Example (Basic) ¶
package main
import (
"fmt"
"codeberg.org/danjones000/nomino"
)
func main() {
// Use default config
out, _ := nomino.Make(nomino.NewConfig())
fmt.Println(out)
}
Example (WithExtraOptions) ¶
package main
import (
"fmt"
"codeberg.org/danjones000/nomino"
)
func main() {
gen := nomino.Incremental()
conf := nomino.NewConfig(
nomino.WithGenerator(gen),
nomino.WithPrefix("pre"),
)
st, _ := nomino.Make(conf, nomino.WithOriginal("foobar"))
fmt.Println(st)
st, _ = nomino.Make(conf, nomino.WithOriginal("baz"))
fmt.Println(st)
}
Output: pre_0_foobar.txt pre_1_baz.txt
Types ¶
type Config ¶
type Config struct {
// contains filtered or unexported fields
}
Config controls how the generatred filename is created.
type Generator ¶
Generator is a function that returns the "random" portion of the returned filename. Technically, it doesn't necessarily need to be random, and could be based on time, or a counter, for example.
func Hash ¶ added in v0.2.1
Hash generates a name from a hash of the filename. When this is used, the original filename will be removed from the final filename.
Example (MD5) ¶
package main
import (
"crypto"
"fmt"
"codeberg.org/danjones000/nomino"
)
func main() {
str, _ := nomino.Hash(crypto.MD5).
Make(nomino.WithOriginal("foobar"))
fmt.Println(str)
}
Output: 3858f62230ac3c915f300c664312c63f.txt
Example (SHA1) ¶
package main
import (
"crypto"
"fmt"
"codeberg.org/danjones000/nomino"
)
func main() {
str, _ := nomino.Hash(crypto.SHA1).
Make(nomino.WithOriginal("foobar"))
fmt.Println(str)
}
Output: 8843d7f92416211de9ebb963ff4ce28125932878.txt
Example (SHA256) ¶
package main
import (
"crypto"
"fmt"
"codeberg.org/danjones000/nomino"
)
func main() {
str, _ := nomino.Hash(crypto.SHA256).
Make(nomino.WithOriginal("foobar"))
fmt.Println(str)
}
Output: c3ab8ff13720e8ad9047dd39466b3c8974e592c2fa383d4a3960714caef0c4f2.txt
func Incremental ¶ added in v0.2.0
func Incremental(opts ...IncrementalOption) Generator
Incremental generates a name that is a series of integers. By default it begins at 0 and increments by 1 each time.
Example ¶
package main
import (
"fmt"
"codeberg.org/danjones000/nomino"
)
func main() {
conf := nomino.NewConfig(
nomino.WithPrefix("foo"),
nomino.WithGenerator(nomino.Incremental()),
)
str, _ := nomino.Make(conf)
fmt.Println(str)
str, _ = nomino.Make(conf)
fmt.Println(str)
str, _ = nomino.Make(conf)
fmt.Println(str)
}
Output: foo_0.txt foo_1.txt foo_2.txt
Example (WithStartAndStep) ¶
package main
import (
"fmt"
"codeberg.org/danjones000/nomino"
)
func main() {
conf := nomino.NewConfig(
nomino.WithPrefix("foo"),
nomino.WithGenerator(nomino.Incremental(
nomino.IncrementalStart(42),
nomino.IncrementalStep(2),
)),
)
str, _ := nomino.Make(conf)
fmt.Println(str)
str, _ = nomino.Make(conf)
fmt.Println(str)
str, _ = nomino.Make(conf)
fmt.Println(str)
}
Output: foo_42.txt foo_44.txt foo_46.txt
func MultiGeneratorInOrder ¶
MultiGeneratorInOrder allows the use of multiple generators. Each new invokation will use the next generator in turn. If none are passed, the generator will always return ErrMissingGenerators.
Example ¶
package main
import (
"fmt"
"codeberg.org/danjones000/nomino"
)
func main() {
gen1 := func(*nomino.Config) (string, error) {
return "bonjour", nil
}
gen2 := func(*nomino.Config) (string, error) {
return "goodbye", nil
}
gen := nomino.MultiGeneratorInOrder(gen1, gen2)
str, _ := gen.Make()
fmt.Println(str)
str, _ = gen.Make()
fmt.Println(str)
str, _ = gen.Make()
fmt.Println(str)
}
Output: bonjour.txt goodbye.txt bonjour.txt
func MultiGeneratorRandomOrder ¶ added in v0.4.0
MultiGeneratorRandomOrder allows the use of multiple generators. Each new invokation will use one of the generators randomly. If none are passed, the generator will always return ErrMissingGenerators.
Example ¶
package main
import (
"fmt"
"codeberg.org/danjones000/nomino"
)
func main() {
gen1 := func(*nomino.Config) (string, error) {
return "guten-tag", nil
}
gen2 := func(*nomino.Config) (string, error) {
return "wiedersehen", nil
}
gen := nomino.MultiGeneratorRandomOrder(gen1, gen2)
str, _ := gen.Make()
fmt.Println(str)
str, _ = gen.Make()
fmt.Println(str)
str, _ = gen.Make()
fmt.Println(str)
}
func Random ¶ added in v0.4.0
func Random(opts ...RandomOption) Generator
Random generates a random string containing the characters A-Za-z0-9. By default, it will be eight characters long.
Example ¶
package main
import (
"fmt"
"codeberg.org/danjones000/nomino"
)
func main() {
str, _ := nomino.Random().Make()
fmt.Println(str)
}
func Slug ¶ added in v0.2.0
Slug generates a name from the original filename. When this is used, the original filename will be removed from the final filename. If a language is specified, that may affect the resulting slug.
Example ¶
package main
import (
"fmt"
"codeberg.org/danjones000/nomino"
)
func main() {
str, _ := nomino.Slug().Make(nomino.WithOriginal("My name is Jimmy"))
fmt.Println(str)
}
Output: my-name-is-jimmy.txt
Example (WithLang) ¶
package main
import (
"fmt"
"codeberg.org/danjones000/nomino"
)
func main() {
str, _ := nomino.Slug("de").
Make(nomino.WithOriginal("Diese & Dass"))
fmt.Println(str)
}
Output: diese-und-dass.txt
func Timestamp ¶
func Timestamp(opts ...TimestampOption) Generator
Timestamp generates a a date and time. By default, it uses the current time, and will. be formatted accourding to FileTimestamp.
Example ¶
package main
import (
"fmt"
"codeberg.org/danjones000/nomino"
)
func main() {
gen := nomino.Timestamp()
s, _ := gen.Make()
fmt.Println(s)
}
func UUID ¶
UUID generates a UUID. If nil is passed as an argument, a UUIDv4 is generated.
Example ¶
package main
import (
"fmt"
"codeberg.org/danjones000/nomino"
)
func main() {
gen := nomino.UUID(nil)
str, _ := gen.Make()
fmt.Println(str)
str, _ = gen.Make()
fmt.Println(str)
}
Example (V7) ¶
package main
import (
"fmt"
"codeberg.org/danjones000/nomino"
)
func main() {
gen := nomino.UUID(nomino.UUIDv7)
str, _ := gen.Make()
fmt.Println(str)
str, _ = gen.Make()
fmt.Println(str)
str, _ = gen.Make()
fmt.Println(str)
}
func (Generator) Make ¶ added in v0.4.0
Make allows you to generate a new string directly from a Generator.
Example ¶
package main
import (
"fmt"
"codeberg.org/danjones000/nomino"
)
func main() {
g := nomino.Incremental()
st, _ := g.Make()
fmt.Println(st)
st, _ = g.Make(nomino.WithPrefix("foo"))
fmt.Println(st)
}
Output: 0.txt foo_1.txt
type Hasher ¶ added in v0.4.0
Hasher is a type returns a hash.Hash. All crypto.Hash may be used.
type HashingFunc ¶ added in v0.2.1
HashingFunc is a function that generates a hash.Hash.
Example (HMAC) ¶
package main
import (
"crypto"
"crypto/hmac"
"fmt"
"hash"
"codeberg.org/danjones000/nomino"
)
func main() {
var hasher nomino.HashingFunc = func() hash.Hash {
return hmac.New(crypto.SHA1.New, []byte("hello"))
}
g := nomino.Hash(hasher)
str, _ := g.Make(nomino.WithOriginal("foobar"))
fmt.Println(str)
}
Output: 85f767c284c80a3a59a9635194321d20dd90f31b.txt
func (HashingFunc) New ¶ added in v0.4.0
func (hf HashingFunc) New() hash.Hash
New allows HashingFunc to be used as a Hasher.
type IncrementalOption ¶ added in v0.3.0
type IncrementalOption func(c *incConf)
IncrementalOption sets an option for the Incremental Generator.
func IncrementalFormat ¶ added in v0.2.0
func IncrementalFormat(format string) IncrementalOption
IncrementalFormatsets the format for the number generated by Incremental. It will be formatted with Printf. This is mostly likely useful with a format like "%02d".
Example ¶
package main
import (
"fmt"
"codeberg.org/danjones000/nomino"
)
func main() {
conf := nomino.NewConfig(
nomino.WithPrefix("foo"),
nomino.WithGenerator(nomino.Incremental(
nomino.IncrementalFormat("%03d"),
)),
)
str, _ := nomino.Make(conf)
fmt.Println(str)
str, _ = nomino.Make(conf)
fmt.Println(str)
str, _ = nomino.Make(conf)
fmt.Println(str)
}
Output: foo_000.txt foo_001.txt foo_002.txt
func IncrementalStart ¶ added in v0.3.0
func IncrementalStart(start int) IncrementalOption
IncrementalStart sets the starting integer for Incremental.
Example ¶
package main
import (
"fmt"
"codeberg.org/danjones000/nomino"
)
func main() {
conf := nomino.NewConfig(
nomino.WithPrefix("foo"),
nomino.WithGenerator(nomino.Incremental(
nomino.IncrementalStart(42),
)),
)
str, _ := nomino.Make(conf)
fmt.Println(str)
str, _ = nomino.Make(conf)
fmt.Println(str)
str, _ = nomino.Make(conf)
fmt.Println(str)
}
Output: foo_42.txt foo_43.txt foo_44.txt
func IncrementalStep ¶ added in v0.3.0
func IncrementalStep(step int) IncrementalOption
IncrementalStepsets the step by which Incremental increases with each invocation.
Example ¶
package main
import (
"fmt"
"codeberg.org/danjones000/nomino"
)
func main() {
conf := nomino.NewConfig(
nomino.WithPrefix("foo"),
nomino.WithGenerator(nomino.Incremental(
nomino.IncrementalStep(2),
)),
)
str, _ := nomino.Make(conf)
fmt.Println(str)
str, _ = nomino.Make(conf)
fmt.Println(str)
str, _ = nomino.Make(conf)
fmt.Println(str)
}
Output: foo_0.txt foo_2.txt foo_4.txt
type Option ¶
type Option func(c *Config)
Option sets configuration parameters for Config.
func WithExtension ¶
WithExtension sets the extension for the generated filename.
Example ¶
package main
import (
"fmt"
"codeberg.org/danjones000/nomino"
)
func main() {
st, _ := nomino.Make(nomino.NewConfig(
nomino.WithExtension("xml"),
nomino.WithGenerator(nomino.Incremental()),
))
fmt.Println(st)
}
Output: 0.xml
func WithGenerator ¶
WithGenerator sets the specified Generator.
Example (CustomGenerator) ¶
package main
import (
"fmt"
"codeberg.org/danjones000/nomino"
)
func main() {
var gen nomino.Generator = func(*nomino.Config) (string, error) {
return "hello", nil
}
str, _ := gen.Make()
fmt.Println(str)
str, _ = gen.Make(nomino.WithoutExtension())
fmt.Println(str)
}
Output: hello.txt hello
func WithOriginal ¶
WithOriginal sets the original filename. This will be included in the generated name after the generated string and before the suffix.
Example ¶
package main
import (
"fmt"
"codeberg.org/danjones000/nomino"
)
func main() {
st, _ := nomino.Make(nomino.NewConfig(
nomino.WithOriginal("Hello, World"),
nomino.WithGenerator(nomino.Incremental()),
))
fmt.Println(st)
}
Output: 0_Hello, World.txt
func WithOriginalSlug ¶ added in v0.2.0
WithOriginal sets the original filename as a slug. This should not be used with the Slug Generator (as it would be redundant).
Example ¶
package main
import (
"fmt"
"codeberg.org/danjones000/nomino"
)
func main() {
st, _ := nomino.Make(nomino.NewConfig(
nomino.WithOriginalSlug("Hello, World"),
nomino.WithGenerator(nomino.Incremental()),
))
fmt.Println(st)
}
Output: 0_hello-world.txt
func WithOriginalSlugLang ¶ added in v0.2.0
WithOriginal sets the original filename as a slug, taking the language into account. This should not be used with the Slug Generator (as it would be redundant).
Example ¶
package main
import (
"fmt"
"codeberg.org/danjones000/nomino"
)
func main() {
st, _ := nomino.Make(nomino.NewConfig(
nomino.WithOriginalSlugLang("Diese & Dass", "de"),
nomino.WithGenerator(nomino.Incremental()),
))
fmt.Println(st)
}
Output: 0_diese-und-dass.txt
func WithPrefix ¶
WithPrefix sets a prefix for the generated name.
Example ¶
package main
import (
"fmt"
"codeberg.org/danjones000/nomino"
)
func main() {
conf := nomino.NewConfig(
nomino.WithPrefix("pref"),
nomino.WithGenerator(nomino.Incremental()),
)
st, _ := nomino.Make(conf)
fmt.Println(st)
st, _ = nomino.Make(conf)
fmt.Println(st)
}
Output: pref_0.txt pref_1.txt
func WithSeparator ¶ added in v0.0.3
WithSeparator sets the separator for the generated filename.
Example ¶
package main
import (
"fmt"
"codeberg.org/danjones000/nomino"
)
func main() {
conf := nomino.NewConfig(
nomino.WithPrefix("pref"),
nomino.WithSeparator("---"),
nomino.WithGenerator(nomino.Incremental()),
)
st, _ := nomino.Make(conf)
fmt.Println(st)
st, _ = nomino.Make(conf)
fmt.Println(st)
}
Output: pref---0.txt pref---1.txt
func WithSuffix ¶
WithSuffix sets a suffix for the generated name. It will be included in the base name before the suffix.
Example ¶
package main
import (
"fmt"
"codeberg.org/danjones000/nomino"
)
func main() {
conf := nomino.NewConfig(
nomino.WithSuffix("suff"),
nomino.WithGenerator(nomino.Incremental()),
)
st, _ := nomino.Make(conf)
fmt.Println(st)
st, _ = nomino.Make(conf)
fmt.Println(st)
}
Output: 0_suff.txt 1_suff.txt
func WithoutExtension ¶
func WithoutExtension() Option
WithoutExtension sets no extension for the generated filename. By default, it will be txt.
Example ¶
package main
import (
"fmt"
"codeberg.org/danjones000/nomino"
)
func main() {
st, _ := nomino.Make(nomino.NewConfig(
nomino.WithoutExtension(),
nomino.WithGenerator(nomino.Incremental()),
))
fmt.Println(st)
}
Output: 0
type RandomOption ¶ added in v0.4.0
type RandomOption func(*randConf)
RandomOption is an option for the Random Generator.
func RandomLength ¶ added in v0.4.0
func RandomLength(length int) RandomOption
RandomLength controls the length of the string generated by Random.
Example ¶
package main
import (
"fmt"
"codeberg.org/danjones000/nomino"
)
func main() {
str, _ := nomino.Random(nomino.RandomLength(32)).Make()
fmt.Println(str)
}
type TimestampOption ¶ added in v0.3.0
type TimestampOption func(c *timestampConf)
TimestampOption provides options for the Timestamp Generator.
func TimestampFormat ¶ added in v0.3.0
func TimestampFormat(format string) TimestampOption
TimestampFormat sets the format for the generated name. Consult time.Time.Format for details on the format.
Example ¶
package main
import (
"fmt"
"time"
"codeberg.org/danjones000/nomino"
)
func main() {
tz, _ := time.LoadLocation("America/New_York")
ts := time.Date(2009, time.January, 20, 12, 5, 0, 0, tz)
gen := nomino.Timestamp(nomino.TimestampTime(ts), nomino.TimestampFormat("2006#01#02<>15|04|05-0700"))
s, _ := gen.Make()
fmt.Println(s)
}
Output: 2009#01#20<>12|05|00-0500.txt
func TimestampTime ¶ added in v0.3.0
func TimestampTime(t time.Time) TimestampOption
TimestampTime sets the time for the generated name. By default, Timestamp uses the current time.
Example ¶
package main
import (
"fmt"
"time"
"codeberg.org/danjones000/nomino"
)
func main() {
tz, _ := time.LoadLocation("America/New_York")
ts := time.Date(2009, time.January, 20, 12, 5, 0, 0, tz)
gen := nomino.Timestamp(nomino.TimestampTime(ts))
s, _ := gen.Make()
fmt.Println(s)
}
Output: 2009-01-20T12-05-00-0500.txt
func TimestampUTC ¶
func TimestampUTC() TimestampOption
TimestampUTC uses the time in UTC, while also stripping the timezone from the format.
Example ¶
package main
import (
"fmt"
"time"
"codeberg.org/danjones000/nomino"
)
func main() {
tz, _ := time.LoadLocation("America/New_York")
ts := time.Date(2009, time.January, 20, 12, 5, 0, 0, tz)
gen := nomino.Timestamp(nomino.TimestampTime(ts), nomino.TimestampUTC())
s, _ := gen.Make()
fmt.Println(s)
}
Output: 2009-01-20T17-05-00.txt