randchar

Documentation

Overview

Package randchar helps to generate random sequences of characters from a configured character set, which can be useful for e.g. generating passwords.

It supports many different character sets and configuration options to meet even the weirdest of password requirements. However, note that the strongest passwords are the ones with the least requirements. Imposing e.g. a minimum requirement on generated passwords reduces the entropy of the resulting password. So when possible, avoid using any constraints.

Index

• Variables
• type Charset
  • func NewCharset(characters string) Charset
  • func (c Charset) Add(set Charset) Charset
  • func (c Charset) Equals(other Charset) bool
  • func (c Charset) IsSubset(of Charset) bool
  • func (c Charset) Size() int
  • func (c Charset) Subtract(set Charset) Charset
• type Generator
  • func NewGenerator(useSymbols bool) Generator
• type Option
  • func Min(n int, charset Charset) Option
  • func WithReader(reader io.Reader) Option
• type Rand
  • func MustNewRand(base Charset, options ...Option) Rand
  • func NewRand(base Charset, options ...Option) (Rand, error)
  • func (r Rand) Generate(n int) ([]byte, error)

Variables

var (
	// Numeric defines a character set containing all numbers.
	Numeric = NewCharset("0123456789")
	// Lowercase defines a character set containing all lowercase letters.
	Lowercase = NewCharset("abcdefghijklmnopqrstuvwxyz")
	// Uppercase defines a character set containing all uppercase letters.
	Uppercase = NewCharset("ABCDEFGHIJKLMNOPQRSTUVWXYZ")
	// Letters defines a character set containing all upper- and lowercase letters of the alphabet.
	Letters = Lowercase.Add(Uppercase)
	// Alphanumeric defines a character set containing letters and numbers.
	Alphanumeric = Letters.Add(Numeric)
	// Symbols defines a character set containing special characters commonly used for passwords.
	Symbols = NewCharset("!@#$%^*-_+=.,?")
	// All defines a character set containing both alphanumeric and symbol characters.
	All = Alphanumeric.Add(Symbols)
	// Similar defines a character set containing similar looking characters.
	Similar = NewCharset("iIlL1oO0")

	// DefaultRand defines the default random generator to use. You can create
	// your own generators using NewRand.
	DefaultRand = MustNewRand(Alphanumeric)
)

Types

type Charset

type Charset struct {
	// contains filtered or unexported fields
}

Charset is a set of unique characters.

func NewCharset

func NewCharset(characters string) Charset

NewCharset creates a set of characters from a given byte slice, removing duplicates to ensure the random generators are not biased.

func (Charset) Add

func (c Charset) Add(set Charset) Charset

Add merges two character sets into one, removing duplicates.

func (Charset) Equals

func (c Charset) Equals(other Charset) bool

Equals returns true when both character sets contain the exactly same characters.

func (Charset) IsSubset

func (c Charset) IsSubset(of Charset) bool

IsSubset returns true when the character set is a subset of the given set. When both sets are the same it returns true too.

func (Charset) Size

func (c Charset) Size() int

Size returns the number of distinct characters in the set.

func (Charset) Subtract

func (c Charset) Subtract(set Charset) Charset

Subtract removes all characters from a set that match a given set of characters.

type Generator

type Generator interface {
	Generate(n int) ([]byte, error)
}

Generator generates random byte arrays.

func NewGenerator

func NewGenerator(useSymbols bool) Generator

NewGenerator is a shorthand function to create a new random alphanumeric generator, optionally configured to use symbols too. For more flexibility to configure the random generator, use NewRand instead.

type Option

type Option func(r Rand) (Rand, error)

Option defines a configuration option for a random reader.

func Min

func Min(n int, charset Charset) Option

Min ensures the generated slice contains at least n characters from the given character set. When multiple Min options are given with the same character set, the biggest minimum takes precedence.

func WithReader

func WithReader(reader io.Reader) Option

WithReader allows you to set the reader used as source of randomness. Do not use this unless you know what you're doing. By default, the source of randomness is set to crypto/rand.Reader.

type Rand

type Rand struct {
	// contains filtered or unexported fields
}

Rand helps generating slices of randomly chosen characters from a given character set.

func MustNewRand

func MustNewRand(base Charset, options ...Option) Rand

MustNewRand is a utility function for creating random character generators, which panics upon error so be careful. For more safety, use NewRand instead.

func NewRand

func NewRand(base Charset, options ...Option) (Rand, error)

NewRand initializes a new random generator from the given character set and configures it with the given options.

func (Rand) Generate

func (r Rand) Generate(n int) ([]byte, error)

Generate returns a randomly generated slice of characters that meets the requirements of the reader.