Merge pull request #110 from vimeo/enums

Enum Support

Author: sergiosalvatore

README.md

@@ -15,7 +15,7 @@ go get github.com/vimeo/dials@latest
 
 ## Prerequisites
 
-Dials requires Go 1.18 or later.
+Dials requires Go 1.24 or later.
 
 ## What is Dials?
 
@@ -276,6 +276,78 @@ If you wish to watch the config file and make updates to your configuration, use
 	}
 ```
 
+### Using Enums
+Dials provides some helper types to deal with values that are part of defined
+enumerations.  All you need to do is have your enum implement the `dials.ValueMap`
+interface with `DialsValueMap()`, which provides a mapping from a string (your
+config value) to the enum value.  Further more, when using flags, Enums are
+integrated into those packages so that Usage text for each Enum value will
+include a list of all the possible values.
+
+Also, `FuzzyEnum` provides identical functionality to `Enum` except comparisons
+are done in a case-insensitive manner.
+
+For example:
+
+```go
+type Protocol int
+
+const (
+	HTTP Protocol = iota
+	HTTPS
+	Gopher
+	FTP
+)
+
+func (p Protocol) DialsValueMap() map[string]Protocol {
+	return map[string]Protocol{
+		"http":   HTTP,
+		"https":  HTTPS,
+		"gopher": Gopher,
+		"ftp":    FTP,
+	}
+}
+
+func (p Protocol) String() string {
+	switch p {
+	case HTTP:
+		return "HyperText Transfer Protocol"
+	case HTTPS:
+		return "Secure HyperText Transfer Protocol"
+	case Gopher:
+		return "Gopher"
+	case FTP:
+		return "File Transfer Protocol"
+	}
+	return "unknown"
+}
+
+type Config struct {
+	SelectedProto dials.Enum[Protocol]
+	Backup        dials.Enum[Protocol]
+}
+
+func main() {
+	source := &static.StringSource{
+		Data:    `{"selectedProto": "gopher"}`,
+		Decoder: &json.Decoder{},
+	}
+
+	c := &EnumConfig{
+		Backup: dials.EnumValue(HTTPS),
+	}
+
+	d, err := dials.Config(context.Background(), c, source)
+	if err != nil {
+		panic("something went wrong!")
+	}
+
+	v := d.View()
+	fmt.Printf("selected: %s, backup: %s", v.SelectedProto.Value, v.Backup.Value)
+	// Output: selected: Gopher, backup: Secure HyperText Transfer Protocol
+}
+```
+
 ### Aliased Configuration Values
 Dials supports aliases for fields where you want to change the name and support
 an orderly transition from an old name to a new name.  Just as there is a

enum.go

@@ -0,0 +1,141 @@
+//go:build go1.23
+
+package dials
+
+import (
+	"fmt"
+	"maps"
+	"slices"
+	"strings"
+)
+
+// ValueMap provides a mapping from a string to a type of your choice to be used
+// like an enum.  Users should implement the `DialsValueMap()` method to provide
+// all possible mappings values.  Any values not in the mapping will fail when
+// unmarshaling.
+type ValueMap[T any] interface {
+	DialsValueMap() map[string]T
+}
+
+// Enum allows you to treat a certain type like an enumeration.  Enums are
+// integrated into the flags packages to automatically amend the `Usage` text to
+// include all allowed values.
+type Enum[T ValueMap[T]] struct {
+	Value T
+}
+
+// EnumValuable is an interface that is useful to get all the allowed enum
+// values as strings.  It is used by the flag packages to adjust the usage text
+// to include all available values.
+type EnumValuable interface {
+	AllowedEnumValues() []string
+}
+
+// AllowedEnumValues implements the [EnumValuable] interface.
+func (e Enum[T]) AllowedEnumValues() []string {
+	return slices.Sorted(maps.Keys(e.Value.DialsValueMap()))
+}
+
+// UnmarshalText implements [encoding.TextUnmarshaler] so that we can map from
+// strings to our typed enum.  If there is no appropriate mapping,
+// [ErrInvalidEnumValue] is returned.
+func (e *Enum[T]) UnmarshalText(text []byte) error {
+	allVals := e.Value.DialsValueMap()
+	if mapping, ok := allVals[string(text)]; ok {
+		e.Value = mapping
+		return nil
+	}
+	return &ErrInvalidEnumValue{
+		Input:   string(text),
+		Allowed: e.AllowedEnumValues(),
+	}
+}
+
+// FuzzyEnum is just like an [Enum], but does case-insensitive comparisons. Just
+// like Enums, FuzzyEnums are integrated into the flags packages to
+// automatically amend the `Usage` text to include all allowed values and will
+// also indicate that the matching is case-insensitive.
+type FuzzyEnum[T ValueMap[T]] struct {
+	Value T
+}
+
+// FuzzyEnumComparer is an interface that allows us to detect that
+// case-insensitive comparison has been used.
+type FuzzyEnumComparer interface {
+	isFuzzy()
+}
+
+// AllowedEnumValues implements the [EnumValuable] interface.
+func (f FuzzyEnum[T]) AllowedEnumValues() []string {
+	return slices.Sorted(maps.Keys(f.Value.DialsValueMap()))
+}
+
+// isFuzzy implements the FuzzyEnumComparer interface.
+func (f FuzzyEnum[T]) isFuzzy() {}
+
+// UnmarshalText implements [encoding.TextUnmarshaler] and does a case-insensitive
+// comparison of the string to map back to the appropriate value from the
+// enumeration.  If there is no appropriate mapping, [ErrInvalidEnumValue] is
+// returned.
+func (f *FuzzyEnum[T]) UnmarshalText(text []byte) error {
+	allVals := f.Value.DialsValueMap()
+	noCase := make(map[string]T, len(allVals))
+	for k, v := range allVals {
+		noCase[strings.ToLower(k)] = v
+	}
+
+	if mapping, ok := noCase[strings.ToLower(string(text))]; ok {
+		f.Value = mapping
+		return nil
+	}
+
+	return &ErrInvalidEnumValue{
+		Input:   string(text),
+		Allowed: f.AllowedEnumValues(),
+		Fuzzy:   true,
+	}
+}
+
+// ErrInvalidEnumValue is an error that is returned when there is no mapping for
+// a particular value in the enumeration.
+type ErrInvalidEnumValue struct {
+	// All the allowed inputs.
+	Allowed []string
+	// The input that was provided (not in the Allowed list).
+	Input string
+	// true if the comparison is case-insensitive.
+	Fuzzy bool
+}
+
+// Error implements the error interface.
+func (e *ErrInvalidEnumValue) Error() string {
+	return fmt.Sprintf("value %q is not part of the allowed enumeration: %+v, fuzzy: %t", e.Input, e.Allowed, e.Fuzzy)
+}
+
+// StringValueMap is a helper that converts string-ish typed-enums to the
+// mapping table expected by the [ValueMap] interface.
+func StringValueMap[T ~string](in ...T) map[string]T {
+	mapping := make(map[string]T, len(in))
+	for _, element := range in {
+		mapping[string(element)] = element
+	}
+	return mapping
+}
+
+// StringerValueMap is a helper that converts types that implement the
+// [fmt.Stringer] interface to the mapping table expected by the [ValueMap]
+// interface.
+func StringerValueMap[T fmt.Stringer](in ...T) map[string]T {
+	mapping := make(map[string]T, len(in))
+	for _, element := range in {
+		mapping[element.String()] = element
+	}
+	return mapping
+}
+
+// EnumValue is a helper that's particularly useful when setting enum defaults in configuration.
+func EnumValue[T ValueMap[T]](in T) Enum[T] {
+	return Enum[T]{
+		Value: in,
+	}
+}

integrationtests/enum_example_test.go

@@ -0,0 +1,69 @@
+package integrationtests_test
+
+import (
+	"context"
+
+	"fmt"
+
+	"github.com/vimeo/dials"
+	"github.com/vimeo/dials/decoders/json"
+	"github.com/vimeo/dials/sources/static"
+)
+
+type Protocol int
+
+const (
+	HTTP Protocol = iota
+	HTTPS
+	Gopher
+	FTP
+)
+
+func (p Protocol) DialsValueMap() map[string]Protocol {
+	return map[string]Protocol{
+		"http":   HTTP,
+		"https":  HTTPS,
+		"gopher": Gopher,
+		"ftp":    FTP,
+	}
+}
+
+func (p Protocol) String() string {
+	switch p {
+	case HTTP:
+		return "HyperText Transfer Protocol"
+	case HTTPS:
+		return "Secure HyperText Transfer Protocol"
+	case Gopher:
+		return "Gopher"
+	case FTP:
+		return "File Transfer Protocol"
+	}
+	return "unknown"
+}
+
+type EnumConfig struct {
+	SelectedProto dials.Enum[Protocol]
+	Backup        dials.Enum[Protocol]
+}
+
+func ExampleEnum() {
+
+	source := &static.StringSource{
+		Data:    `{"selectedProto": "gopher"}`,
+		Decoder: &json.Decoder{},
+	}
+
+	c := &EnumConfig{
+		Backup: dials.EnumValue(HTTPS),
+	}
+
+	d, err := dials.Config(context.Background(), c, source)
+	if err != nil {
+		panic("something went wrong!")
+	}
+
+	v := d.View()
+	fmt.Printf("selected: %s, backup: %s", v.SelectedProto.Value, v.Backup.Value)
+	// Output: selected: Gopher, backup: Secure HyperText Transfer Protocol
+}