migrate oc init command from urfave/cli to spf13/cobra

Signed-off-by: Christian Richter <c.richter@opencloud.eu>
2025-12-15 16:40:26 +01:00
parent 35900f8875
commit 1e970499af
118 changed files with 17189 additions and 41 deletions
@@ -0,0 +1,15 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_size = 4
+indent_style = space
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.go]
+indent_style = tab
+
+[{*.yml,*.yaml}]
+indent_size = 2
@@ -0,0 +1,25 @@
+# Compiled Object files, Static and Dynamic libs (Shared Objects)
+*.o
+*.a
+*.so
+
+# Folders
+_obj
+_test
+
+# Architecture specific extensions/prefixes
+*.[568vq]
+[568vq].out
+
+*.cgo1.go
+*.cgo2.c
+_cgo_defun.c
+_cgo_gotypes.go
+_cgo_export.*
+
+_testmain.go
+
+*.exe
+*.test
+
+*.bench
@@ -0,0 +1,39 @@
+version: "2"
+
+run:
+  timeout: 10m
+
+linters:
+  enable:
+    - errcheck
+    - govet
+    - ineffassign
+    - misspell
+    - nolintlint
+    # - revive
+    - unused
+
+  disable:
+    - staticcheck
+
+  settings:
+    misspell:
+      locale: US
+    nolintlint:
+      allow-unused: false # report any unused nolint directives
+      require-specific: false # don't require nolint directives to be specific about which linter is being skipped
+
+formatters:
+  enable:
+    - gci
+    - gofmt
+    # - gofumpt
+    - goimports
+    # - golines
+
+  settings:
+    gci:
+      sections:
+        - standard
+        - default
+        - localmodule
@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2014 Steve Francia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
@@ -0,0 +1,40 @@
+GOVERSION := $(shell go version | cut -d ' ' -f 3 | cut -d '.' -f 2)
+
+.PHONY: check fmt lint test test-race vet test-cover-html help
+.DEFAULT_GOAL := help
+
+check: test-race fmt vet lint ## Run tests and linters
+
+test: ## Run tests
+	go test ./...
+
+test-race: ## Run tests with race detector
+	go test -race ./...
+
+fmt: ## Run gofmt linter
+ifeq "$(GOVERSION)" "12"
+	@for d in `go list` ; do \
+		if [ "`gofmt -l -s $$GOPATH/src/$$d | tee /dev/stderr`" ]; then \
+			echo "^ improperly formatted go files" && echo && exit 1; \
+		fi \
+	done
+endif
+
+lint: ## Run golint linter
+	@for d in `go list` ; do \
+		if [ "`golint $$d | tee /dev/stderr`" ]; then \
+			echo "^ golint errors!" && echo && exit 1; \
+		fi \
+	done
+
+vet: ## Run go vet linter
+	@if [ "`go vet | tee /dev/stderr`" ]; then \
+		echo "^ go vet errors!" && echo && exit 1; \
+	fi
+
+test-cover-html: ## Generate test coverage report
+	go test -coverprofile=coverage.out -covermode=count
+	go tool cover -func=coverage.out
+
+help:
+	@grep -E '^[a-zA-Z0-9_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'
@@ -0,0 +1,79 @@
+# cast
+
+[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/spf13/cast/ci.yaml?style=flat-square)](https://github.com/spf13/cast/actions/workflows/ci.yaml)
+[![go.dev reference](https://img.shields.io/badge/go.dev-reference-007d9c?logo=go&logoColor=white&style=flat-square)](https://pkg.go.dev/mod/github.com/spf13/cast)
+![GitHub go.mod Go version](https://img.shields.io/github/go-mod/go-version/spf13/cast?style=flat-square&color=61CFDD)
+[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/spf13/cast/badge?style=flat-square)](https://deps.dev/go/github.com%252Fspf13%252Fcast)
+
+Easy and safe casting from one type to another in Go
+
+Don’t Panic! ... Cast
+
+## What is Cast?
+
+Cast is a library to convert between different go types in a consistent and easy way.
+
+Cast provides simple functions to easily convert a number to a string, an
+interface into a bool, etc. Cast does this intelligently when an obvious
+conversion is possible. It doesn’t make any attempts to guess what you meant,
+for example you can only convert a string to an int when it is a string
+representation of an int such as “8”. Cast was developed for use in
+[Hugo](https://gohugo.io), a website engine which uses YAML, TOML or JSON
+for meta data.
+
+## Why use Cast?
+
+When working with dynamic data in Go you often need to cast or convert the data
+from one type into another. Cast goes beyond just using type assertion (though
+it uses that when possible) to provide a very straightforward and convenient
+library.
+
+If you are working with interfaces to handle things like dynamic content
+you’ll need an easy way to convert an interface into a given type. This
+is the library for you.
+
+If you are taking in data from YAML, TOML or JSON or other formats which lack
+full types, then Cast is the library for you.
+
+## Usage
+
+Cast provides a handful of To_____ methods. These methods will always return
+the desired type. **If input is provided that will not convert to that type, the
+0 or nil value for that type will be returned**.
+
+Cast also provides identical methods To_____E. These return the same result as
+the To_____ methods, plus an additional error which tells you if it successfully
+converted. Using these methods you can tell the difference between when the
+input matched the zero value or when the conversion failed and the zero value
+was returned.
+
+The following examples are merely a sample of what is available. Please review
+the code for a complete set.
+
+### Example ‘ToString’:
+
+    cast.ToString("mayonegg")         // "mayonegg"
+    cast.ToString(8)                  // "8"
+    cast.ToString(8.31)               // "8.31"
+    cast.ToString([]byte("one time")) // "one time"
+    cast.ToString(nil)                // ""
+
+	var foo interface{} = "one more time"
+    cast.ToString(foo)                // "one more time"
+
+
+### Example ‘ToInt’:
+
+    cast.ToInt(8)                  // 8
+    cast.ToInt(8.31)               // 8
+    cast.ToInt("8")                // 8
+    cast.ToInt(true)               // 1
+    cast.ToInt(false)              // 0
+
+	var eight interface{} = 8
+    cast.ToInt(eight)              // 8
+    cast.ToInt(nil)                // 0
+
+## License
+
+The project is licensed under the [MIT License](LICENSE).
@@ -0,0 +1,69 @@
+// Copyright © 2014 Steve Francia <spf@spf13.com>.
+//
+// Use of this source code is governed by an MIT-style
+// license that can be found in the LICENSE file.
+package cast
+
+import (
+	"reflect"
+	"slices"
+)
+
+var kindNames = []string{
+	reflect.String:  "string",
+	reflect.Bool:    "bool",
+	reflect.Int:     "int",
+	reflect.Int8:    "int8",
+	reflect.Int16:   "int16",
+	reflect.Int32:   "int32",
+	reflect.Int64:   "int64",
+	reflect.Uint:    "uint",
+	reflect.Uint8:   "uint8",
+	reflect.Uint16:  "uint16",
+	reflect.Uint32:  "uint32",
+	reflect.Uint64:  "uint64",
+	reflect.Float32: "float32",
+	reflect.Float64: "float64",
+}
+
+var kinds = map[reflect.Kind]func(reflect.Value) any{
+	reflect.String:  func(v reflect.Value) any { return v.String() },
+	reflect.Bool:    func(v reflect.Value) any { return v.Bool() },
+	reflect.Int:     func(v reflect.Value) any { return int(v.Int()) },
+	reflect.Int8:    func(v reflect.Value) any { return int8(v.Int()) },
+	reflect.Int16:   func(v reflect.Value) any { return int16(v.Int()) },
+	reflect.Int32:   func(v reflect.Value) any { return int32(v.Int()) },
+	reflect.Int64:   func(v reflect.Value) any { return v.Int() },
+	reflect.Uint:    func(v reflect.Value) any { return uint(v.Uint()) },
+	reflect.Uint8:   func(v reflect.Value) any { return uint8(v.Uint()) },
+	reflect.Uint16:  func(v reflect.Value) any { return uint16(v.Uint()) },
+	reflect.Uint32:  func(v reflect.Value) any { return uint32(v.Uint()) },
+	reflect.Uint64:  func(v reflect.Value) any { return v.Uint() },
+	reflect.Float32: func(v reflect.Value) any { return float32(v.Float()) },
+	reflect.Float64: func(v reflect.Value) any { return v.Float() },
+}
+
+// resolveAlias attempts to resolve a named type to its underlying basic type (if possible).
+//
+// Pointers are expected to be indirected by this point.
+func resolveAlias(i any) (any, bool) {
+	if i == nil {
+		return nil, false
+	}
+
+	t := reflect.TypeOf(i)
+
+	// Not a named type
+	if t.Name() == "" || slices.Contains(kindNames, t.Name()) {
+		return i, false
+	}
+
+	resolve, ok := kinds[t.Kind()]
+	if !ok { // Not a supported kind
+		return i, false
+	}
+
+	v := reflect.ValueOf(i)
+
+	return resolve(v), true
+}
@@ -0,0 +1,131 @@
+// Copyright © 2014 Steve Francia <spf@spf13.com>.
+//
+// Use of this source code is governed by an MIT-style
+// license that can be found in the LICENSE file.
+
+package cast
+
+import (
+	"encoding/json"
+	"fmt"
+	"html/template"
+	"strconv"
+	"time"
+)
+
+// ToBoolE casts any value to a bool type.
+func ToBoolE(i any) (bool, error) {
+	i, _ = indirect(i)
+
+	switch b := i.(type) {
+	case bool:
+		return b, nil
+	case nil:
+		return false, nil
+	case int:
+		return b != 0, nil
+	case int8:
+		return b != 0, nil
+	case int16:
+		return b != 0, nil
+	case int32:
+		return b != 0, nil
+	case int64:
+		return b != 0, nil
+	case uint:
+		return b != 0, nil
+	case uint8:
+		return b != 0, nil
+	case uint16:
+		return b != 0, nil
+	case uint32:
+		return b != 0, nil
+	case uint64:
+		return b != 0, nil
+	case float32:
+		return b != 0, nil
+	case float64:
+		return b != 0, nil
+	case time.Duration:
+		return b != 0, nil
+	case string:
+		return strconv.ParseBool(b)
+	case json.Number:
+		v, err := ToInt64E(b)
+		if err == nil {
+			return v != 0, nil
+		}
+
+		return false, fmt.Errorf(errorMsg, i, i, false)
+	default:
+		if i, ok := resolveAlias(i); ok {
+			return ToBoolE(i)
+		}
+
+		return false, fmt.Errorf(errorMsg, i, i, false)
+	}
+}
+
+// ToStringE casts any value to a string type.
+func ToStringE(i any) (string, error) {
+	switch s := i.(type) {
+	case string:
+		return s, nil
+	case bool:
+		return strconv.FormatBool(s), nil
+	case float64:
+		return strconv.FormatFloat(s, 'f', -1, 64), nil
+	case float32:
+		return strconv.FormatFloat(float64(s), 'f', -1, 32), nil
+	case int:
+		return strconv.Itoa(s), nil
+	case int8:
+		return strconv.FormatInt(int64(s), 10), nil
+	case int16:
+		return strconv.FormatInt(int64(s), 10), nil
+	case int32:
+		return strconv.FormatInt(int64(s), 10), nil
+	case int64:
+		return strconv.FormatInt(s, 10), nil
+	case uint:
+		return strconv.FormatUint(uint64(s), 10), nil
+	case uint8:
+		return strconv.FormatUint(uint64(s), 10), nil
+	case uint16:
+		return strconv.FormatUint(uint64(s), 10), nil
+	case uint32:
+		return strconv.FormatUint(uint64(s), 10), nil
+	case uint64:
+		return strconv.FormatUint(s, 10), nil
+	case json.Number:
+		return s.String(), nil
+	case []byte:
+		return string(s), nil
+	case template.HTML:
+		return string(s), nil
+	case template.URL:
+		return string(s), nil
+	case template.JS:
+		return string(s), nil
+	case template.CSS:
+		return string(s), nil
+	case template.HTMLAttr:
+		return string(s), nil
+	case nil:
+		return "", nil
+	case fmt.Stringer:
+		return s.String(), nil
+	case error:
+		return s.Error(), nil
+	default:
+		if i, ok := indirect(i); ok {
+			return ToStringE(i)
+		}
+
+		if i, ok := resolveAlias(i); ok {
+			return ToStringE(i)
+		}
+
+		return "", fmt.Errorf(errorMsg, i, i, "")
+	}
+}
@@ -0,0 +1,84 @@
+// Copyright © 2014 Steve Francia <spf@spf13.com>.
+//
+// Use of this source code is governed by an MIT-style
+// license that can be found in the LICENSE file.
+
+// Package cast provides easy and safe casting in Go.
+package cast
+
+import "time"
+
+const errorMsg = "unable to cast %#v of type %T to %T"
+const errorMsgWith = "unable to cast %#v of type %T to %T: %w"
+
+// Basic is a type parameter constraint for functions accepting basic types.
+//
+// It represents the supported basic types this package can cast to.
+type Basic interface {
+	string | bool | Number | time.Time | time.Duration
+}
+
+// ToE casts any value to a [Basic] type.
+func ToE[T Basic](i any) (T, error) {
+	var t T
+
+	var v any
+	var err error
+
+	switch any(t).(type) {
+	case string:
+		v, err = ToStringE(i)
+	case bool:
+		v, err = ToBoolE(i)
+	case int:
+		v, err = toNumberE[int](i, parseInt[int])
+	case int8:
+		v, err = toNumberE[int8](i, parseInt[int8])
+	case int16:
+		v, err = toNumberE[int16](i, parseInt[int16])
+	case int32:
+		v, err = toNumberE[int32](i, parseInt[int32])
+	case int64:
+		v, err = toNumberE[int64](i, parseInt[int64])
+	case uint:
+		v, err = toUnsignedNumberE[uint](i, parseUint[uint])
+	case uint8:
+		v, err = toUnsignedNumberE[uint8](i, parseUint[uint8])
+	case uint16:
+		v, err = toUnsignedNumberE[uint16](i, parseUint[uint16])
+	case uint32:
+		v, err = toUnsignedNumberE[uint32](i, parseUint[uint32])
+	case uint64:
+		v, err = toUnsignedNumberE[uint64](i, parseUint[uint64])
+	case float32:
+		v, err = toNumberE[float32](i, parseFloat[float32])
+	case float64:
+		v, err = toNumberE[float64](i, parseFloat[float64])
+	case time.Time:
+		v, err = ToTimeE(i)
+	case time.Duration:
+		v, err = ToDurationE(i)
+	}
+
+	if err != nil {
+		return t, err
+	}
+
+	return v.(T), nil
+}
+
+// Must is a helper that wraps a call to a cast function and panics if the error is non-nil.
+func Must[T any](i any, err error) T {
+	if err != nil {
+		panic(err)
+	}
+
+	return i.(T)
+}
+
+// To casts any value to a [Basic] type.
+func To[T Basic](i any) T {
+	v, _ := ToE[T](i)
+
+	return v
+}
@@ -0,0 +1,37 @@
+// Copyright © 2014 Steve Francia <spf@spf13.com>.
+//
+// Use of this source code is governed by an MIT-style
+// license that can be found in the LICENSE file.
+
+package cast
+
+import (
+	"reflect"
+)
+
+// From html/template/content.go
+// Copyright 2011 The Go Authors. All rights reserved.
+// indirect returns the value, after dereferencing as many times
+// as necessary to reach the base type (or nil).
+func indirect(i any) (any, bool) {
+	if i == nil {
+		return nil, false
+	}
+
+	if t := reflect.TypeOf(i); t.Kind() != reflect.Ptr {
+		// Avoid creating a reflect.Value if it's not a pointer.
+		return i, false
+	}
+
+	v := reflect.ValueOf(i)
+
+	for v.Kind() == reflect.Ptr || (v.Kind() == reflect.Interface && v.Elem().Kind() == reflect.Ptr) {
+		if v.IsNil() {
+			return nil, true
+		}
+
+		v = v.Elem()
+	}
+
+	return v.Interface(), true
+}
@@ -0,0 +1,79 @@
+package internal
+
+import (
+	"fmt"
+	"time"
+)
+
+//go:generate stringer -type=TimeFormatType
+
+type TimeFormatType int
+
+const (
+	TimeFormatNoTimezone TimeFormatType = iota
+	TimeFormatNamedTimezone
+	TimeFormatNumericTimezone
+	TimeFormatNumericAndNamedTimezone
+	TimeFormatTimeOnly
+)
+
+type TimeFormat struct {
+	Format string
+	Typ    TimeFormatType
+}
+
+func (f TimeFormat) HasTimezone() bool {
+	// We don't include the formats with only named timezones, see
+	// https://github.com/golang/go/issues/19694#issuecomment-289103522
+	return f.Typ >= TimeFormatNumericTimezone && f.Typ <= TimeFormatNumericAndNamedTimezone
+}
+
+var TimeFormats = []TimeFormat{
+	// Keep common formats at the top.
+	{"2006-01-02", TimeFormatNoTimezone},
+	{time.RFC3339, TimeFormatNumericTimezone},
+	{"2006-01-02T15:04:05", TimeFormatNoTimezone}, // iso8601 without timezone
+	{time.RFC1123Z, TimeFormatNumericTimezone},
+	{time.RFC1123, TimeFormatNamedTimezone},
+	{time.RFC822Z, TimeFormatNumericTimezone},
+	{time.RFC822, TimeFormatNamedTimezone},
+	{time.RFC850, TimeFormatNamedTimezone},
+	{"2006-01-02 15:04:05.999999999 -0700 MST", TimeFormatNumericAndNamedTimezone}, // Time.String()
+	{"2006-01-02T15:04:05-0700", TimeFormatNumericTimezone},                        // RFC3339 without timezone hh:mm colon
+	{"2006-01-02 15:04:05Z0700", TimeFormatNumericTimezone},                        // RFC3339 without T or timezone hh:mm colon
+	{"2006-01-02 15:04:05", TimeFormatNoTimezone},
+	{time.ANSIC, TimeFormatNoTimezone},
+	{time.UnixDate, TimeFormatNamedTimezone},
+	{time.RubyDate, TimeFormatNumericTimezone},
+	{"2006-01-02 15:04:05Z07:00", TimeFormatNumericTimezone},
+	{"02 Jan 2006", TimeFormatNoTimezone},
+	{"2006-01-02 15:04:05 -07:00", TimeFormatNumericTimezone},
+	{"2006-01-02 15:04:05 -0700", TimeFormatNumericTimezone},
+	{time.Kitchen, TimeFormatTimeOnly},
+	{time.Stamp, TimeFormatTimeOnly},
+	{time.StampMilli, TimeFormatTimeOnly},
+	{time.StampMicro, TimeFormatTimeOnly},
+	{time.StampNano, TimeFormatTimeOnly},
+}
+
+func ParseDateWith(s string, location *time.Location, formats []TimeFormat) (d time.Time, e error) {
+	for _, format := range formats {
+		if d, e = time.Parse(format.Format, s); e == nil {
+
+			// Some time formats have a zone name, but no offset, so it gets
+			// put in that zone name (not the default one passed in to us), but
+			// without that zone's offset. So set the location manually.
+			if format.Typ <= TimeFormatNamedTimezone {
+				if location == nil {
+					location = time.Local
+				}
+				year, month, day := d.Date()
+				hour, min, sec := d.Clock()
+				d = time.Date(year, month, day, hour, min, sec, d.Nanosecond(), location)
+			}
+
+			return
+		}
+	}
+	return d, fmt.Errorf("unable to parse date: %s", s)
+}
@@ -0,0 +1,27 @@
+// Code generated by "stringer -type=TimeFormatType"; DO NOT EDIT.
+
+package internal
+
+import "strconv"
+
+func _() {
+	// An "invalid array index" compiler error signifies that the constant values have changed.
+	// Re-run the stringer command to generate them again.
+	var x [1]struct{}
+	_ = x[TimeFormatNoTimezone-0]
+	_ = x[TimeFormatNamedTimezone-1]
+	_ = x[TimeFormatNumericTimezone-2]
+	_ = x[TimeFormatNumericAndNamedTimezone-3]
+	_ = x[TimeFormatTimeOnly-4]
+}
+
+const _TimeFormatType_name = "TimeFormatNoTimezoneTimeFormatNamedTimezoneTimeFormatNumericTimezoneTimeFormatNumericAndNamedTimezoneTimeFormatTimeOnly"
+
+var _TimeFormatType_index = [...]uint8{0, 20, 43, 68, 101, 119}
+
+func (i TimeFormatType) String() string {
+	if i < 0 || i >= TimeFormatType(len(_TimeFormatType_index)-1) {
+		return "TimeFormatType(" + strconv.FormatInt(int64(i), 10) + ")"
+	}
+	return _TimeFormatType_name[_TimeFormatType_index[i]:_TimeFormatType_index[i+1]]
+}
@@ -0,0 +1,212 @@
+// Copyright © 2014 Steve Francia <spf@spf13.com>.
+//
+// Use of this source code is governed by an MIT-style
+// license that can be found in the LICENSE file.
+
+package cast
+
+import (
+	"encoding/json"
+	"fmt"
+	"reflect"
+)
+
+func toMapE[K comparable, V any](i any, keyFn func(any) K, valFn func(any) V) (map[K]V, error) {
+	m := map[K]V{}
+
+	if i == nil {
+		return m, fmt.Errorf(errorMsg, i, i, m)
+	}
+
+	switch v := i.(type) {
+	case map[K]V:
+		return v, nil
+
+	case map[K]any:
+		for k, val := range v {
+			m[k] = valFn(val)
+		}
+
+		return m, nil
+
+	case map[any]V:
+		for k, val := range v {
+			m[keyFn(k)] = val
+		}
+
+		return m, nil
+
+	case map[any]any:
+		for k, val := range v {
+			m[keyFn(k)] = valFn(val)
+		}
+
+		return m, nil
+
+	case string:
+		err := jsonStringToObject(v, &m)
+		return m, err
+
+	default:
+		return m, fmt.Errorf(errorMsg, i, i, m)
+	}
+}
+
+func toStringMapE[T any](i any, fn func(any) T) (map[string]T, error) {
+	return toMapE(i, ToString, fn)
+}
+
+// ToStringMapStringE casts any value to a map[string]string type.
+func ToStringMapStringE(i any) (map[string]string, error) {
+	return toStringMapE(i, ToString)
+}
+
+// ToStringMapStringSliceE casts any value to a map[string][]string type.
+func ToStringMapStringSliceE(i any) (map[string][]string, error) {
+	m := map[string][]string{}
+
+	switch v := i.(type) {
+	case map[string][]string:
+		return v, nil
+	case map[string][]any:
+		for k, val := range v {
+			m[ToString(k)] = ToStringSlice(val)
+		}
+		return m, nil
+	case map[string]string:
+		for k, val := range v {
+			m[ToString(k)] = []string{val}
+		}
+	case map[string]any:
+		for k, val := range v {
+			switch vt := val.(type) {
+			case []any:
+				m[ToString(k)] = ToStringSlice(vt)
+			case []string:
+				m[ToString(k)] = vt
+			default:
+				m[ToString(k)] = []string{ToString(val)}
+			}
+		}
+		return m, nil
+	case map[any][]string:
+		for k, val := range v {
+			m[ToString(k)] = ToStringSlice(val)
+		}
+		return m, nil
+	case map[any]string:
+		for k, val := range v {
+			m[ToString(k)] = ToStringSlice(val)
+		}
+		return m, nil
+	case map[any][]any:
+		for k, val := range v {
+			m[ToString(k)] = ToStringSlice(val)
+		}
+		return m, nil
+	case map[any]any:
+		for k, val := range v {
+			key, err := ToStringE(k)
+			if err != nil {
+				return m, fmt.Errorf(errorMsg, i, i, m)
+			}
+			value, err := ToStringSliceE(val)
+			if err != nil {
+				return m, fmt.Errorf(errorMsg, i, i, m)
+			}
+			m[key] = value
+		}
+	case string:
+		err := jsonStringToObject(v, &m)
+		return m, err
+	default:
+		return m, fmt.Errorf(errorMsg, i, i, m)
+	}
+
+	return m, nil
+}
+
+// ToStringMapBoolE casts any value to a map[string]bool type.
+func ToStringMapBoolE(i any) (map[string]bool, error) {
+	return toStringMapE(i, ToBool)
+}
+
+// ToStringMapE casts any value to a map[string]any type.
+func ToStringMapE(i any) (map[string]any, error) {
+	fn := func(i any) any { return i }
+
+	return toStringMapE(i, fn)
+}
+
+func toStringMapIntE[T int | int64](i any, fn func(any) T, fnE func(any) (T, error)) (map[string]T, error) {
+	m := map[string]T{}
+
+	if i == nil {
+		return nil, fmt.Errorf(errorMsg, i, i, m)
+	}
+
+	switch v := i.(type) {
+	case map[string]T:
+		return v, nil
+
+	case map[string]any:
+		for k, val := range v {
+			m[k] = fn(val)
+		}
+
+		return m, nil
+
+	case map[any]T:
+		for k, val := range v {
+			m[ToString(k)] = val
+		}
+
+		return m, nil
+
+	case map[any]any:
+		for k, val := range v {
+			m[ToString(k)] = fn(val)
+		}
+
+		return m, nil
+
+	case string:
+		err := jsonStringToObject(v, &m)
+		return m, err
+	}
+
+	if reflect.TypeOf(i).Kind() != reflect.Map {
+		return m, fmt.Errorf(errorMsg, i, i, m)
+	}
+
+	mVal := reflect.ValueOf(m)
+	v := reflect.ValueOf(i)
+
+	for _, keyVal := range v.MapKeys() {
+		val, err := fnE(v.MapIndex(keyVal).Interface())
+		if err != nil {
+			return m, fmt.Errorf(errorMsg, i, i, m)
+		}
+
+		mVal.SetMapIndex(keyVal, reflect.ValueOf(val))
+	}
+
+	return m, nil
+}
+
+// ToStringMapIntE casts any value to a map[string]int type.
+func ToStringMapIntE(i any) (map[string]int, error) {
+	return toStringMapIntE(i, ToInt, ToIntE)
+}
+
+// ToStringMapInt64E casts any value to a map[string]int64 type.
+func ToStringMapInt64E(i any) (map[string]int64, error) {
+	return toStringMapIntE(i, ToInt64, ToInt64E)
+}
+
+// jsonStringToObject attempts to unmarshall a string as JSON into
+// the object passed as pointer.
+func jsonStringToObject(s string, v any) error {
+	data := []byte(s)
+	return json.Unmarshal(data, v)
+}
@@ -0,0 +1,549 @@
+// Copyright © 2014 Steve Francia <spf@spf13.com>.
+//
+// Use of this source code is governed by an MIT-style
+// license that can be found in the LICENSE file.
+
+package cast
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"regexp"
+	"strconv"
+	"strings"
+	"time"
+)
+
+var errNegativeNotAllowed = errors.New("unable to cast negative value")
+
+type float64EProvider interface {
+	Float64() (float64, error)
+}
+
+type float64Provider interface {
+	Float64() float64
+}
+
+// Number is a type parameter constraint for functions accepting number types.
+//
+// It represents the supported number types this package can cast to.
+type Number interface {
+	int | int8 | int16 | int32 | int64 | uint | uint8 | uint16 | uint32 | uint64 | float32 | float64
+}
+
+type integer interface {
+	int | int8 | int16 | int32 | int64
+}
+
+type unsigned interface {
+	uint | uint8 | uint16 | uint32 | uint64
+}
+
+type float interface {
+	float32 | float64
+}
+
+// ToNumberE casts any value to a [Number] type.
+func ToNumberE[T Number](i any) (T, error) {
+	var t T
+
+	switch any(t).(type) {
+	case int:
+		return toNumberE[T](i, parseNumber[T])
+	case int8:
+		return toNumberE[T](i, parseNumber[T])
+	case int16:
+		return toNumberE[T](i, parseNumber[T])
+	case int32:
+		return toNumberE[T](i, parseNumber[T])
+	case int64:
+		return toNumberE[T](i, parseNumber[T])
+	case uint:
+		return toUnsignedNumberE[T](i, parseNumber[T])
+	case uint8:
+		return toUnsignedNumberE[T](i, parseNumber[T])
+	case uint16:
+		return toUnsignedNumberE[T](i, parseNumber[T])
+	case uint32:
+		return toUnsignedNumberE[T](i, parseNumber[T])
+	case uint64:
+		return toUnsignedNumberE[T](i, parseNumber[T])
+	case float32:
+		return toNumberE[T](i, parseNumber[T])
+	case float64:
+		return toNumberE[T](i, parseNumber[T])
+	default:
+		return 0, fmt.Errorf("unknown number type: %T", t)
+	}
+}
+
+// ToNumber casts any value to a [Number] type.
+func ToNumber[T Number](i any) T {
+	v, _ := ToNumberE[T](i)
+
+	return v
+}
+
+// toNumber's semantics differ from other "to" functions.
+// It returns false as the second parameter if the conversion fails.
+// This is to signal other callers that they should proceed with their own conversions.
+func toNumber[T Number](i any) (T, bool) {
+	i, _ = indirect(i)
+
+	switch s := i.(type) {
+	case T:
+		return s, true
+	case int:
+		return T(s), true
+	case int8:
+		return T(s), true
+	case int16:
+		return T(s), true
+	case int32:
+		return T(s), true
+	case int64:
+		return T(s), true
+	case uint:
+		return T(s), true
+	case uint8:
+		return T(s), true
+	case uint16:
+		return T(s), true
+	case uint32:
+		return T(s), true
+	case uint64:
+		return T(s), true
+	case float32:
+		return T(s), true
+	case float64:
+		return T(s), true
+	case bool:
+		if s {
+			return 1, true
+		}
+
+		return 0, true
+	case nil:
+		return 0, true
+	case time.Weekday:
+		return T(s), true
+	case time.Month:
+		return T(s), true
+	}
+
+	return 0, false
+}
+
+func toNumberE[T Number](i any, parseFn func(string) (T, error)) (T, error) {
+	n, ok := toNumber[T](i)
+	if ok {
+		return n, nil
+	}
+
+	i, _ = indirect(i)
+
+	switch s := i.(type) {
+	case string:
+		if s == "" {
+			return 0, nil
+		}
+
+		v, err := parseFn(s)
+		if err != nil {
+			return 0, fmt.Errorf(errorMsgWith, i, i, n, err)
+		}
+
+		return v, nil
+	case json.Number:
+		if s == "" {
+			return 0, nil
+		}
+
+		v, err := parseFn(string(s))
+		if err != nil {
+			return 0, fmt.Errorf(errorMsgWith, i, i, n, err)
+		}
+
+		return v, nil
+	case float64EProvider:
+		if _, ok := any(n).(float64); !ok {
+			return 0, fmt.Errorf(errorMsg, i, i, n)
+		}
+
+		v, err := s.Float64()
+		if err != nil {
+			return 0, fmt.Errorf(errorMsg, i, i, n)
+		}
+
+		return T(v), nil
+	case float64Provider:
+		if _, ok := any(n).(float64); !ok {
+			return 0, fmt.Errorf(errorMsg, i, i, n)
+		}
+
+		return T(s.Float64()), nil
+	default:
+		if i, ok := resolveAlias(i); ok {
+			return toNumberE(i, parseFn)
+		}
+
+		return 0, fmt.Errorf(errorMsg, i, i, n)
+	}
+}
+
+func toUnsignedNumber[T Number](i any) (T, bool, bool) {
+	i, _ = indirect(i)
+
+	switch s := i.(type) {
+	case T:
+		return s, true, true
+	case int:
+		if s < 0 {
+			return 0, false, false
+		}
+
+		return T(s), true, true
+	case int8:
+		if s < 0 {
+			return 0, false, false
+		}
+
+		return T(s), true, true
+	case int16:
+		if s < 0 {
+			return 0, false, false
+		}
+
+		return T(s), true, true
+	case int32:
+		if s < 0 {
+			return 0, false, false
+		}
+
+		return T(s), true, true
+	case int64:
+		if s < 0 {
+			return 0, false, false
+		}
+
+		return T(s), true, true
+	case uint:
+		return T(s), true, true
+	case uint8:
+		return T(s), true, true
+	case uint16:
+		return T(s), true, true
+	case uint32:
+		return T(s), true, true
+	case uint64:
+		return T(s), true, true
+	case float32:
+		if s < 0 {
+			return 0, false, false
+		}
+
+		return T(s), true, true
+	case float64:
+		if s < 0 {
+			return 0, false, false
+		}
+
+		return T(s), true, true
+	case bool:
+		if s {
+			return 1, true, true
+		}
+
+		return 0, true, true
+	case nil:
+		return 0, true, true
+	case time.Weekday:
+		if s < 0 {
+			return 0, false, false
+		}
+
+		return T(s), true, true
+	case time.Month:
+		if s < 0 {
+			return 0, false, false
+		}
+
+		return T(s), true, true
+	}
+
+	return 0, true, false
+}
+
+func toUnsignedNumberE[T Number](i any, parseFn func(string) (T, error)) (T, error) {
+	n, valid, ok := toUnsignedNumber[T](i)
+	if ok {
+		return n, nil
+	}
+
+	i, _ = indirect(i)
+
+	if !valid {
+		return 0, errNegativeNotAllowed
+	}
+
+	switch s := i.(type) {
+	case string:
+		if s == "" {
+			return 0, nil
+		}
+
+		v, err := parseFn(s)
+		if err != nil {
+			return 0, fmt.Errorf(errorMsgWith, i, i, n, err)
+		}
+
+		return v, nil
+	case json.Number:
+		if s == "" {
+			return 0, nil
+		}
+
+		v, err := parseFn(string(s))
+		if err != nil {
+			return 0, fmt.Errorf(errorMsgWith, i, i, n, err)
+		}
+
+		return v, nil
+	case float64EProvider:
+		if _, ok := any(n).(float64); !ok {
+			return 0, fmt.Errorf(errorMsg, i, i, n)
+		}
+
+		v, err := s.Float64()
+		if err != nil {
+			return 0, fmt.Errorf(errorMsg, i, i, n)
+		}
+
+		if v < 0 {
+			return 0, errNegativeNotAllowed
+		}
+
+		return T(v), nil
+	case float64Provider:
+		if _, ok := any(n).(float64); !ok {
+			return 0, fmt.Errorf(errorMsg, i, i, n)
+		}
+
+		v := s.Float64()
+
+		if v < 0 {
+			return 0, errNegativeNotAllowed
+		}
+
+		return T(v), nil
+	default:
+		if i, ok := resolveAlias(i); ok {
+			return toUnsignedNumberE(i, parseFn)
+		}
+
+		return 0, fmt.Errorf(errorMsg, i, i, n)
+	}
+}
+
+func parseNumber[T Number](s string) (T, error) {
+	var t T
+
+	switch any(t).(type) {
+	case int:
+		v, err := parseInt[int](s)
+
+		return T(v), err
+	case int8:
+		v, err := parseInt[int8](s)
+
+		return T(v), err
+	case int16:
+		v, err := parseInt[int16](s)
+
+		return T(v), err
+	case int32:
+		v, err := parseInt[int32](s)
+
+		return T(v), err
+	case int64:
+		v, err := parseInt[int64](s)
+
+		return T(v), err
+	case uint:
+		v, err := parseUint[uint](s)
+
+		return T(v), err
+	case uint8:
+		v, err := parseUint[uint8](s)
+
+		return T(v), err
+	case uint16:
+		v, err := parseUint[uint16](s)
+
+		return T(v), err
+	case uint32:
+		v, err := parseUint[uint32](s)
+
+		return T(v), err
+	case uint64:
+		v, err := parseUint[uint64](s)
+
+		return T(v), err
+	case float32:
+		v, err := strconv.ParseFloat(s, 32)
+
+		return T(v), err
+	case float64:
+		v, err := strconv.ParseFloat(s, 64)
+
+		return T(v), err
+
+	default:
+		return 0, fmt.Errorf("unknown number type: %T", t)
+	}
+}
+
+func parseInt[T integer](s string) (T, error) {
+	v, err := strconv.ParseInt(trimDecimal(s), 0, 0)
+	if err != nil {
+		return 0, err
+	}
+
+	return T(v), nil
+}
+
+func parseUint[T unsigned](s string) (T, error) {
+	v, err := strconv.ParseUint(strings.TrimLeft(trimDecimal(s), "+"), 0, 0)
+	if err != nil {
+		return 0, err
+	}
+
+	return T(v), nil
+}
+
+func parseFloat[T float](s string) (T, error) {
+	var t T
+
+	var v any
+	var err error
+
+	switch any(t).(type) {
+	case float32:
+		n, e := strconv.ParseFloat(s, 32)
+
+		v = float32(n)
+		err = e
+	case float64:
+		n, e := strconv.ParseFloat(s, 64)
+
+		v = float64(n)
+		err = e
+	}
+
+	return v.(T), err
+}
+
+// ToFloat64E casts an interface to a float64 type.
+func ToFloat64E(i any) (float64, error) {
+	return toNumberE[float64](i, parseFloat[float64])
+}
+
+// ToFloat32E casts an interface to a float32 type.
+func ToFloat32E(i any) (float32, error) {
+	return toNumberE[float32](i, parseFloat[float32])
+}
+
+// ToInt64E casts an interface to an int64 type.
+func ToInt64E(i any) (int64, error) {
+	return toNumberE[int64](i, parseInt[int64])
+}
+
+// ToInt32E casts an interface to an int32 type.
+func ToInt32E(i any) (int32, error) {
+	return toNumberE[int32](i, parseInt[int32])
+}
+
+// ToInt16E casts an interface to an int16 type.
+func ToInt16E(i any) (int16, error) {
+	return toNumberE[int16](i, parseInt[int16])
+}
+
+// ToInt8E casts an interface to an int8 type.
+func ToInt8E(i any) (int8, error) {
+	return toNumberE[int8](i, parseInt[int8])
+}
+
+// ToIntE casts an interface to an int type.
+func ToIntE(i any) (int, error) {
+	return toNumberE[int](i, parseInt[int])
+}
+
+// ToUintE casts an interface to a uint type.
+func ToUintE(i any) (uint, error) {
+	return toUnsignedNumberE[uint](i, parseUint[uint])
+}
+
+// ToUint64E casts an interface to a uint64 type.
+func ToUint64E(i any) (uint64, error) {
+	return toUnsignedNumberE[uint64](i, parseUint[uint64])
+}
+
+// ToUint32E casts an interface to a uint32 type.
+func ToUint32E(i any) (uint32, error) {
+	return toUnsignedNumberE[uint32](i, parseUint[uint32])
+}
+
+// ToUint16E casts an interface to a uint16 type.
+func ToUint16E(i any) (uint16, error) {
+	return toUnsignedNumberE[uint16](i, parseUint[uint16])
+}
+
+// ToUint8E casts an interface to a uint type.
+func ToUint8E(i any) (uint8, error) {
+	return toUnsignedNumberE[uint8](i, parseUint[uint8])
+}
+
+func trimZeroDecimal(s string) string {
+	var foundZero bool
+	for i := len(s); i > 0; i-- {
+		switch s[i-1] {
+		case '.':
+			if foundZero {
+				return s[:i-1]
+			}
+		case '0':
+			foundZero = true
+		default:
+			return s
+		}
+	}
+	return s
+}
+
+var stringNumberRe = regexp.MustCompile(`^([-+]?\d*)(\.\d*)?$`)
+
+// see [BenchmarkDecimal] for details about the implementation
+func trimDecimal(s string) string {
+	if !strings.Contains(s, ".") {
+		return s
+	}
+
+	matches := stringNumberRe.FindStringSubmatch(s)
+	if matches != nil {
+		// matches[1] is the captured integer part with sign
+		s = matches[1]
+
+		// handle special cases
+		switch s {
+		case "-", "+":
+			s += "0"
+		case "":
+			s = "0"
+		}
+
+		return s
+	}
+
+	return s
+}
@@ -0,0 +1,106 @@
+// Copyright © 2014 Steve Francia <spf@spf13.com>.
+//
+// Use of this source code is governed by an MIT-style
+// license that can be found in the LICENSE file.
+
+package cast
+
+import (
+	"fmt"
+	"reflect"
+	"strings"
+)
+
+// ToSliceE casts any value to a []any type.
+func ToSliceE(i any) ([]any, error) {
+	i, _ = indirect(i)
+
+	var s []any
+
+	switch v := i.(type) {
+	case []any:
+		// TODO: use slices.Clone
+		return append(s, v...), nil
+	case []map[string]any:
+		for _, u := range v {
+			s = append(s, u)
+		}
+
+		return s, nil
+	default:
+		return s, fmt.Errorf(errorMsg, i, i, s)
+	}
+}
+
+func toSliceE[T Basic](i any) ([]T, error) {
+	v, ok, err := toSliceEOk[T](i)
+	if err != nil {
+		return nil, err
+	}
+
+	if !ok {
+		return nil, fmt.Errorf(errorMsg, i, i, []T{})
+	}
+
+	return v, nil
+}
+
+func toSliceEOk[T Basic](i any) ([]T, bool, error) {
+	i, _ = indirect(i)
+	if i == nil {
+		return nil, true, fmt.Errorf(errorMsg, i, i, []T{})
+	}
+
+	switch v := i.(type) {
+	case []T:
+		// TODO: clone slice
+		return v, true, nil
+	}
+
+	kind := reflect.TypeOf(i).Kind()
+	switch kind {
+	case reflect.Slice, reflect.Array:
+		s := reflect.ValueOf(i)
+		a := make([]T, s.Len())
+
+		for j := 0; j < s.Len(); j++ {
+			val, err := ToE[T](s.Index(j).Interface())
+			if err != nil {
+				return nil, true, fmt.Errorf(errorMsg, i, i, []T{})
+			}
+
+			a[j] = val
+		}
+
+		return a, true, nil
+	default:
+		return nil, false, nil
+	}
+}
+
+// ToStringSliceE casts any value to a []string type.
+func ToStringSliceE(i any) ([]string, error) {
+	if a, ok, err := toSliceEOk[string](i); ok {
+		if err != nil {
+			return nil, err
+		}
+
+		return a, nil
+	}
+
+	var a []string
+
+	switch v := i.(type) {
+	case string:
+		return strings.Fields(v), nil
+	case any:
+		str, err := ToStringE(v)
+		if err != nil {
+			return nil, fmt.Errorf(errorMsg, i, i, a)
+		}
+
+		return []string{str}, nil
+	default:
+		return nil, fmt.Errorf(errorMsg, i, i, a)
+	}
+}
@@ -0,0 +1,116 @@
+// Copyright © 2014 Steve Francia <spf@spf13.com>.
+//
+// Use of this source code is governed by an MIT-style
+// license that can be found in the LICENSE file.
+
+package cast
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"strings"
+	"time"
+
+	"github.com/spf13/cast/internal"
+)
+
+// ToTimeE any value to a [time.Time] type.
+func ToTimeE(i any) (time.Time, error) {
+	return ToTimeInDefaultLocationE(i, time.UTC)
+}
+
+// ToTimeInDefaultLocationE casts an empty interface to [time.Time],
+// interpreting inputs without a timezone to be in the given location,
+// or the local timezone if nil.
+func ToTimeInDefaultLocationE(i any, location *time.Location) (tim time.Time, err error) {
+	i, _ = indirect(i)
+
+	switch v := i.(type) {
+	case time.Time:
+		return v, nil
+	case string:
+		return StringToDateInDefaultLocation(v, location)
+	case json.Number:
+		// Originally this used ToInt64E, but adding string float conversion broke ToTime.
+		// the behavior of ToTime would have changed if we continued using it.
+		// For now, using json.Number's own Int64 method should be good enough to preserve backwards compatibility.
+		v = json.Number(trimZeroDecimal(string(v)))
+		s, err1 := v.Int64()
+		if err1 != nil {
+			return time.Time{}, fmt.Errorf(errorMsg, i, i, time.Time{})
+		}
+		return time.Unix(s, 0), nil
+	case int:
+		return time.Unix(int64(v), 0), nil
+	case int32:
+		return time.Unix(int64(v), 0), nil
+	case int64:
+		return time.Unix(v, 0), nil
+	case uint:
+		return time.Unix(int64(v), 0), nil
+	case uint32:
+		return time.Unix(int64(v), 0), nil
+	case uint64:
+		return time.Unix(int64(v), 0), nil
+	case nil:
+		return time.Time{}, nil
+	default:
+		return time.Time{}, fmt.Errorf(errorMsg, i, i, time.Time{})
+	}
+}
+
+// ToDurationE casts any value to a [time.Duration] type.
+func ToDurationE(i any) (time.Duration, error) {
+	i, _ = indirect(i)
+
+	switch s := i.(type) {
+	case time.Duration:
+		return s, nil
+	case int, int8, int16, int32, int64, uint, uint8, uint16, uint32, uint64:
+		v, err := ToInt64E(s)
+		if err != nil {
+			// TODO: once there is better error handling, this should be easier
+			return 0, errors.New(strings.ReplaceAll(err.Error(), " int64", "time.Duration"))
+		}
+
+		return time.Duration(v), nil
+	case float32, float64, float64EProvider, float64Provider:
+		v, err := ToFloat64E(s)
+		if err != nil {
+			// TODO: once there is better error handling, this should be easier
+			return 0, errors.New(strings.ReplaceAll(err.Error(), " float64", "time.Duration"))
+		}
+
+		return time.Duration(v), nil
+	case string:
+		if !strings.ContainsAny(s, "nsuµmh") {
+			return time.ParseDuration(s + "ns")
+		}
+
+		return time.ParseDuration(s)
+	case nil:
+		return time.Duration(0), nil
+	default:
+		if i, ok := resolveAlias(i); ok {
+			return ToDurationE(i)
+		}
+
+		return 0, fmt.Errorf(errorMsg, i, i, time.Duration(0))
+	}
+}
+
+// StringToDate attempts to parse a string into a [time.Time] type using a
+// predefined list of formats.
+//
+// If no suitable format is found, an error is returned.
+func StringToDate(s string) (time.Time, error) {
+	return internal.ParseDateWith(s, time.UTC, internal.TimeFormats)
+}
+
+// StringToDateInDefaultLocation casts an empty interface to a [time.Time],
+// interpreting inputs without a timezone to be in the given location,
+// or the local timezone if nil.
+func StringToDateInDefaultLocation(s string, location *time.Location) (time.Time, error) {
+	return internal.ParseDateWith(s, location, internal.TimeFormats)
+}
@@ -0,0 +1,261 @@
+// Code generated by cast generator. DO NOT EDIT.
+
+package cast
+
+import "time"
+
+// ToBool casts any value to a(n) bool type.
+func ToBool(i any) bool {
+	v, _ := ToBoolE(i)
+	return v
+}
+
+// ToString casts any value to a(n) string type.
+func ToString(i any) string {
+	v, _ := ToStringE(i)
+	return v
+}
+
+// ToTime casts any value to a(n) time.Time type.
+func ToTime(i any) time.Time {
+	v, _ := ToTimeE(i)
+	return v
+}
+
+// ToTimeInDefaultLocation casts any value to a(n) time.Time type.
+func ToTimeInDefaultLocation(i any, location *time.Location) time.Time {
+	v, _ := ToTimeInDefaultLocationE(i, location)
+	return v
+}
+
+// ToDuration casts any value to a(n) time.Duration type.
+func ToDuration(i any) time.Duration {
+	v, _ := ToDurationE(i)
+	return v
+}
+
+// ToInt casts any value to a(n) int type.
+func ToInt(i any) int {
+	v, _ := ToIntE(i)
+	return v
+}
+
+// ToInt8 casts any value to a(n) int8 type.
+func ToInt8(i any) int8 {
+	v, _ := ToInt8E(i)
+	return v
+}
+
+// ToInt16 casts any value to a(n) int16 type.
+func ToInt16(i any) int16 {
+	v, _ := ToInt16E(i)
+	return v
+}
+
+// ToInt32 casts any value to a(n) int32 type.
+func ToInt32(i any) int32 {
+	v, _ := ToInt32E(i)
+	return v
+}
+
+// ToInt64 casts any value to a(n) int64 type.
+func ToInt64(i any) int64 {
+	v, _ := ToInt64E(i)
+	return v
+}
+
+// ToUint casts any value to a(n) uint type.
+func ToUint(i any) uint {
+	v, _ := ToUintE(i)
+	return v
+}
+
+// ToUint8 casts any value to a(n) uint8 type.
+func ToUint8(i any) uint8 {
+	v, _ := ToUint8E(i)
+	return v
+}
+
+// ToUint16 casts any value to a(n) uint16 type.
+func ToUint16(i any) uint16 {
+	v, _ := ToUint16E(i)
+	return v
+}
+
+// ToUint32 casts any value to a(n) uint32 type.
+func ToUint32(i any) uint32 {
+	v, _ := ToUint32E(i)
+	return v
+}
+
+// ToUint64 casts any value to a(n) uint64 type.
+func ToUint64(i any) uint64 {
+	v, _ := ToUint64E(i)
+	return v
+}
+
+// ToFloat32 casts any value to a(n) float32 type.
+func ToFloat32(i any) float32 {
+	v, _ := ToFloat32E(i)
+	return v
+}
+
+// ToFloat64 casts any value to a(n) float64 type.
+func ToFloat64(i any) float64 {
+	v, _ := ToFloat64E(i)
+	return v
+}
+
+// ToStringMapString casts any value to a(n) map[string]string type.
+func ToStringMapString(i any) map[string]string {
+	v, _ := ToStringMapStringE(i)
+	return v
+}
+
+// ToStringMapStringSlice casts any value to a(n) map[string][]string type.
+func ToStringMapStringSlice(i any) map[string][]string {
+	v, _ := ToStringMapStringSliceE(i)
+	return v
+}
+
+// ToStringMapBool casts any value to a(n) map[string]bool type.
+func ToStringMapBool(i any) map[string]bool {
+	v, _ := ToStringMapBoolE(i)
+	return v
+}
+
+// ToStringMapInt casts any value to a(n) map[string]int type.
+func ToStringMapInt(i any) map[string]int {
+	v, _ := ToStringMapIntE(i)
+	return v
+}
+
+// ToStringMapInt64 casts any value to a(n) map[string]int64 type.
+func ToStringMapInt64(i any) map[string]int64 {
+	v, _ := ToStringMapInt64E(i)
+	return v
+}
+
+// ToStringMap casts any value to a(n) map[string]any type.
+func ToStringMap(i any) map[string]any {
+	v, _ := ToStringMapE(i)
+	return v
+}
+
+// ToSlice casts any value to a(n) []any type.
+func ToSlice(i any) []any {
+	v, _ := ToSliceE(i)
+	return v
+}
+
+// ToBoolSlice casts any value to a(n) []bool type.
+func ToBoolSlice(i any) []bool {
+	v, _ := ToBoolSliceE(i)
+	return v
+}
+
+// ToStringSlice casts any value to a(n) []string type.
+func ToStringSlice(i any) []string {
+	v, _ := ToStringSliceE(i)
+	return v
+}
+
+// ToIntSlice casts any value to a(n) []int type.
+func ToIntSlice(i any) []int {
+	v, _ := ToIntSliceE(i)
+	return v
+}
+
+// ToInt64Slice casts any value to a(n) []int64 type.
+func ToInt64Slice(i any) []int64 {
+	v, _ := ToInt64SliceE(i)
+	return v
+}
+
+// ToUintSlice casts any value to a(n) []uint type.
+func ToUintSlice(i any) []uint {
+	v, _ := ToUintSliceE(i)
+	return v
+}
+
+// ToFloat64Slice casts any value to a(n) []float64 type.
+func ToFloat64Slice(i any) []float64 {
+	v, _ := ToFloat64SliceE(i)
+	return v
+}
+
+// ToDurationSlice casts any value to a(n) []time.Duration type.
+func ToDurationSlice(i any) []time.Duration {
+	v, _ := ToDurationSliceE(i)
+	return v
+}
+
+// ToBoolSliceE casts any value to a(n) []bool type.
+func ToBoolSliceE(i any) ([]bool, error) {
+	return toSliceE[bool](i)
+}
+
+// ToDurationSliceE casts any value to a(n) []time.Duration type.
+func ToDurationSliceE(i any) ([]time.Duration, error) {
+	return toSliceE[time.Duration](i)
+}
+
+// ToIntSliceE casts any value to a(n) []int type.
+func ToIntSliceE(i any) ([]int, error) {
+	return toSliceE[int](i)
+}
+
+// ToInt8SliceE casts any value to a(n) []int8 type.
+func ToInt8SliceE(i any) ([]int8, error) {
+	return toSliceE[int8](i)
+}
+
+// ToInt16SliceE casts any value to a(n) []int16 type.
+func ToInt16SliceE(i any) ([]int16, error) {
+	return toSliceE[int16](i)
+}
+
+// ToInt32SliceE casts any value to a(n) []int32 type.
+func ToInt32SliceE(i any) ([]int32, error) {
+	return toSliceE[int32](i)
+}
+
+// ToInt64SliceE casts any value to a(n) []int64 type.
+func ToInt64SliceE(i any) ([]int64, error) {
+	return toSliceE[int64](i)
+}
+
+// ToUintSliceE casts any value to a(n) []uint type.
+func ToUintSliceE(i any) ([]uint, error) {
+	return toSliceE[uint](i)
+}
+
+// ToUint8SliceE casts any value to a(n) []uint8 type.
+func ToUint8SliceE(i any) ([]uint8, error) {
+	return toSliceE[uint8](i)
+}
+
+// ToUint16SliceE casts any value to a(n) []uint16 type.
+func ToUint16SliceE(i any) ([]uint16, error) {
+	return toSliceE[uint16](i)
+}
+
+// ToUint32SliceE casts any value to a(n) []uint32 type.
+func ToUint32SliceE(i any) ([]uint32, error) {
+	return toSliceE[uint32](i)
+}
+
+// ToUint64SliceE casts any value to a(n) []uint64 type.
+func ToUint64SliceE(i any) ([]uint64, error) {
+	return toSliceE[uint64](i)
+}
+
+// ToFloat32SliceE casts any value to a(n) []float32 type.
+func ToFloat32SliceE(i any) ([]float32, error) {
+	return toSliceE[float32](i)
+}
+
+// ToFloat64SliceE casts any value to a(n) []float64 type.
+func ToFloat64SliceE(i any) ([]float64, error) {
+	return toSliceE[float64](i)
+}
@@ -0,0 +1,21 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_size = 4
+indent_style = space
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.go]
+indent_style = tab
+
+[{Makefile,*.mk}]
+indent_style = tab
+
+[*.nix]
+indent_size = 2
+
+[.golangci.yaml]
+indent_size = 2
@@ -0,0 +1,8 @@
+/.devenv/
+/.direnv/
+/.idea/
+/.pre-commit-config.yaml
+/bin/
+/build/
+/var/
+/vendor/
@@ -0,0 +1,118 @@
+version: "2"
+
+run:
+  timeout: 5m
+
+linters:
+  enable:
+    - bodyclose
+    - dogsled
+    - dupl
+    - durationcheck
+    - exhaustive
+    - gocritic
+    - godot
+    - gomoddirectives
+    - goprintffuncname
+    - govet
+    - importas
+    - ineffassign
+    - makezero
+    - misspell
+    - nakedret
+    - nilerr
+    - noctx
+    - nolintlint
+    - prealloc
+    - predeclared
+    - revive
+    - rowserrcheck
+    - sqlclosecheck
+    - staticcheck
+    - tparallel
+    - unconvert
+    - unparam
+    - unused
+    - wastedassign
+    - whitespace
+
+    # fixme
+    # - cyclop
+    # - errcheck
+    # - errorlint
+    # - exhaustivestruct
+    # - forbidigo
+    # - forcetypeassert
+    # - gochecknoglobals
+    # - gochecknoinits
+    # - gocognit
+    # - goconst
+    # - gocyclo
+    # - gosec
+    # - gosimple
+    # - ifshort
+    # - lll
+    # - nlreturn
+    # - paralleltest
+    # - scopelint
+    # - thelper
+    # - wrapcheck
+
+    # unused
+    # - depguard
+    # - goheader
+    # - gomodguard
+
+    # don't enable:
+    # - asciicheck
+    # - funlen
+    # - godox
+    # - goerr113
+    # - gomnd
+    # - interfacer
+    # - maligned
+    # - nestif
+    # - testpackage
+    # - wsl
+
+  exclusions:
+    rules:
+      - linters:
+        - errcheck
+        - noctx
+        path: _test.go
+    presets:
+      - comments
+      - std-error-handling
+
+  settings:
+    misspell:
+      locale: US
+    nolintlint:
+      allow-unused: false # report any unused nolint directives
+      require-specific: false # don't require nolint directives to be specific about which linter is being skipped
+    gocritic:
+      # Enable multiple checks by tags. See "Tags" section in https://github.com/go-critic/go-critic#usage.
+      enabled-tags:
+        - diagnostic
+        - experimental
+        - opinionated
+        - style
+      disabled-checks:
+        - importShadow
+        - unnamedResult
+
+formatters:
+  enable:
+    - gci
+    - gofmt
+    - gofumpt
+    - goimports
+    # - golines
+
+  settings:
+    gci:
+      sections:
+        - standard
+        - default
+        - localmodule
@@ -0,0 +1,2 @@
+# TODO: FIXME
+/.github/
@@ -0,0 +1,6 @@
+ignore-from-file: [.gitignore, .yamlignore]
+
+extends: default
+
+rules:
+  line-length: disable
@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2014 Steve Francia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
@@ -0,0 +1,87 @@
+# A Self-Documenting Makefile: http://marmelab.com/blog/2016/02/29/auto-documented-makefile.html
+
+OS = $(shell uname | tr A-Z a-z)
+export PATH := $(abspath bin/):${PATH}
+
+# Build variables
+BUILD_DIR ?= build
+export CGO_ENABLED ?= 0
+export GOOS = $(shell go env GOOS)
+ifeq (${VERBOSE}, 1)
+ifeq ($(filter -v,${GOARGS}),)
+	GOARGS += -v
+endif
+TEST_FORMAT = short-verbose
+endif
+
+# Dependency versions
+GOTESTSUM_VERSION = 1.9.0
+GOLANGCI_VERSION = 1.53.3
+
+# Add the ability to override some variables
+# Use with care
+-include override.mk
+
+.PHONY: clear
+clear: ## Clear the working area and the project
+	rm -rf bin/
+
+.PHONY: check
+check: test lint ## Run tests and linters
+
+
+TEST_PKGS ?= ./...
+.PHONY: test
+test: TEST_FORMAT ?= short
+test: SHELL = /bin/bash
+test: export CGO_ENABLED=1
+test: bin/gotestsum ## Run tests
+	@mkdir -p ${BUILD_DIR}
+	bin/gotestsum --no-summary=skipped --junitfile ${BUILD_DIR}/coverage.xml --format ${TEST_FORMAT} -- -race -coverprofile=${BUILD_DIR}/coverage.txt -covermode=atomic $(filter-out -v,${GOARGS}) $(if ${TEST_PKGS},${TEST_PKGS},./...)
+
+.PHONY: lint
+lint: lint-go lint-yaml
+lint: ## Run linters
+
+.PHONY: lint-go
+lint-go:
+	golangci-lint run $(if ${CI},--out-format github-actions,)
+
+.PHONY: lint-yaml
+lint-yaml:
+	yamllint $(if ${CI},-f github,) --no-warnings .
+
+.PHONY: fmt
+fmt: ## Format code
+	golangci-lint run --fix
+
+deps: bin/golangci-lint bin/gotestsum yamllint
+deps: ## Install dependencies
+
+bin/gotestsum:
+	@mkdir -p bin
+	curl -L https://github.com/gotestyourself/gotestsum/releases/download/v${GOTESTSUM_VERSION}/gotestsum_${GOTESTSUM_VERSION}_${OS}_amd64.tar.gz | tar -zOxf - gotestsum > ./bin/gotestsum && chmod +x ./bin/gotestsum
+
+bin/golangci-lint:
+	@mkdir -p bin
+	curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | bash -s -- v${GOLANGCI_VERSION}
+
+.PHONY: yamllint
+yamllint:
+	pip3 install --user yamllint
+
+# Add custom targets here
+-include custom.mk
+
+.PHONY: list
+list: ## List all make targets
+	@${MAKE} -pRrn : -f $(MAKEFILE_LIST) 2>/dev/null | awk -v RS= -F: '/^# File/,/^# Finished Make data base/ {if ($$1 !~ "^[#.]") {print $$1}}' | egrep -v -e '^[^[:alnum:]]' -e '^$@$$' | sort
+
+.PHONY: help
+.DEFAULT_GOAL := help
+help:
+	@grep -h -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'
+
+# Variable outputting/exporting rules
+var-%: ; @echo $($*)
+varexport-%: ; @echo $*=$($*)
@@ -0,0 +1,931 @@
+> ## Viper v2 feedback
+> Viper is heading towards v2 and we would love to hear what _**you**_ would like to see in it. Share your thoughts here: https://forms.gle/R6faU74qPRPAzchZ9
+>
+> **Thank you!**
+
+![viper logo](https://github.com/user-attachments/assets/acae9193-2974-41f3-808d-2d433f5ada5e)
+
+
+[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge-flat.svg)](https://github.com/avelino/awesome-go#configuration)
+[![run on repl.it](https://repl.it/badge/github/sagikazarmark/Viper-example)](https://repl.it/@sagikazarmark/Viper-example#main.go)
+
+[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/spf13/viper/ci.yaml?branch=master&style=flat-square)](https://github.com/spf13/viper/actions?query=workflow%3ACI)
+[![Join the chat at https://gitter.im/spf13/viper](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/spf13/viper?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
+[![Go Report Card](https://goreportcard.com/badge/github.com/spf13/viper?style=flat-square)](https://goreportcard.com/report/github.com/spf13/viper)
+![Go Version](https://img.shields.io/badge/go%20version-%3E=1.23-61CFDD.svg?style=flat-square)
+[![PkgGoDev](https://pkg.go.dev/badge/mod/github.com/spf13/viper)](https://pkg.go.dev/mod/github.com/spf13/viper)
+
+**Go configuration with fangs!**
+
+Many Go projects are built using Viper including:
+
+* [Hugo](http://gohugo.io)
+* [EMC RexRay](http://rexray.readthedocs.org/en/stable/)
+* [Imgur’s Incus](https://github.com/Imgur/incus)
+* [Nanobox](https://github.com/nanobox-io/nanobox)/[Nanopack](https://github.com/nanopack)
+* [Docker Notary](https://github.com/docker/Notary)
+* [BloomApi](https://www.bloomapi.com/)
+* [doctl](https://github.com/digitalocean/doctl)
+* [Clairctl](https://github.com/jgsqware/clairctl)
+* [Mercure](https://mercure.rocks)
+* [Meshery](https://github.com/meshery/meshery)
+* [Bearer](https://github.com/bearer/bearer)
+* [Coder](https://github.com/coder/coder)
+* [Vitess](https://vitess.io/)
+
+
+## Install
+
+```shell
+go get github.com/spf13/viper
+```
+
+**Note:** Viper uses [Go Modules](https://go.dev/wiki/Modules) to manage dependencies.
+
+
+## What is Viper?
+
+Viper is a complete configuration solution for Go applications including [12-Factor apps](https://12factor.net/#the_twelve_factors).
+It is designed to work within an application, and can handle all types of configuration needs
+and formats. It supports:
+
+* setting defaults
+* reading from JSON, TOML, YAML, HCL, envfile and Java properties config files
+* live watching and re-reading of config files (optional)
+* reading from environment variables
+* reading from remote config systems (etcd or Consul), and watching changes
+* reading from command line flags
+* reading from buffer
+* setting explicit values
+
+Viper can be thought of as a registry for all of your applications configuration needs.
+
+
+## Why Viper?
+
+When building a modern application, you don’t want to worry about
+configuration file formats; you want to focus on building awesome software.
+Viper is here to help with that.
+
+Viper does the following for you:
+
+1. Find, load, and unmarshal a configuration file in JSON, TOML, YAML, HCL, INI, envfile or Java properties formats.
+2. Provide a mechanism to set default values for your different configuration options.
+3. Provide a mechanism to set override values for options specified through command line flags.
+4. Provide an alias system to easily rename parameters without breaking existing code.
+5. Make it easy to tell the difference between when a user has provided a command line or config file which is the same as the default.
+
+Viper uses the following precedence order. Each item takes precedence over the item below it:
+
+ * explicit call to `Set`
+ * flag
+ * env
+ * config
+ * key/value store
+ * default
+
+**Important:** Viper configuration keys are case insensitive.
+There are ongoing discussions about making that optional.
+
+
+## Putting Values into Viper
+
+### Establishing Defaults
+
+A good configuration system will support default values. A default value is not
+required for a key, but it’s useful in the event that a key hasn't been set via
+config file, environment variable, remote configuration or flag.
+
+Examples:
+
+```go
+viper.SetDefault("ContentDir", "content")
+viper.SetDefault("LayoutDir", "layouts")
+viper.SetDefault("Taxonomies", map[string]string{"tag": "tags", "category": "categories"})
+```
+
+### Reading Config Files
+
+Viper requires minimal configuration so it knows where to look for config files.
+Viper supports JSON, TOML, YAML, HCL, INI, envfile and Java Properties files. Viper can search multiple paths, but
+currently a single Viper instance only supports a single configuration file.
+Viper does not default to any configuration search paths leaving defaults decision
+to an application.
+
+Here is an example of how to use Viper to search for and read a configuration file.
+None of the specific paths are required, but at least one path should be provided
+where a configuration file is expected.
+
+```go
+viper.SetConfigName("config") // name of config file (without extension)
+viper.SetConfigType("yaml") // REQUIRED if the config file does not have the extension in the name
+viper.AddConfigPath("/etc/appname/")   // path to look for the config file in
+viper.AddConfigPath("$HOME/.appname")  // call multiple times to add many search paths
+viper.AddConfigPath(".")               // optionally look for config in the working directory
+err := viper.ReadInConfig() // Find and read the config file
+if err != nil { // Handle errors reading the config file
+	panic(fmt.Errorf("fatal error config file: %w", err))
+}
+```
+
+You can handle the specific case where no config file is found like this:
+
+```go
+if err := viper.ReadInConfig(); err != nil {
+	if _, ok := err.(viper.ConfigFileNotFoundError); ok {
+		// Config file not found; ignore error if desired
+	} else {
+		// Config file was found but another error was produced
+	}
+}
+
+// Config file found and successfully parsed
+```
+
+*NOTE [since 1.6]:* You can also have a file without an extension and specify the format programmatically. For those configuration files that lie in the home of the user without any extension like `.bashrc`
+
+### Writing Config Files
+
+Reading from config files is useful, but at times you want to store all modifications made at run time.
+For that, a bunch of commands are available, each with its own purpose:
+
+* WriteConfig - writes the current viper configuration to the predefined path, if exists. Errors if no predefined path. Will overwrite the current config file, if it exists.
+* SafeWriteConfig - writes the current viper configuration to the predefined path. Errors if no predefined path. Will not overwrite the current config file, if it exists.
+* WriteConfigAs - writes the current viper configuration to the given filepath. Will overwrite the given file, if it exists.
+* SafeWriteConfigAs - writes the current viper configuration to the given filepath. Will not overwrite the given file, if it exists.
+
+As a rule of the thumb, everything marked with safe won't overwrite any file, but just create if not existent, whilst the default behavior is to create or truncate.
+
+A small examples section:
+
+```go
+viper.WriteConfig() // writes current config to predefined path set by 'viper.AddConfigPath()' and 'viper.SetConfigName'
+viper.SafeWriteConfig()
+viper.WriteConfigAs("/path/to/my/.config")
+viper.SafeWriteConfigAs("/path/to/my/.config") // will error since it has already been written
+viper.SafeWriteConfigAs("/path/to/my/.other_config")
+```
+
+### Watching and re-reading config files
+
+Viper supports the ability to have your application live read a config file while running.
+
+Gone are the days of needing to restart a server to have a config take effect,
+viper powered applications can read an update to a config file while running and
+not miss a beat.
+
+Simply tell the viper instance to watchConfig.
+Optionally you can provide a function for Viper to run each time a change occurs.
+
+**Make sure you add all of the configPaths prior to calling `WatchConfig()`**
+
+```go
+viper.OnConfigChange(func(e fsnotify.Event) {
+	fmt.Println("Config file changed:", e.Name)
+})
+viper.WatchConfig()
+```
+
+### Reading Config from io.Reader
+
+Viper predefines many configuration sources such as files, environment
+variables, flags, and remote K/V store, but you are not bound to them. You can
+also implement your own required configuration source and feed it to viper.
+
+```go
+viper.SetConfigType("yaml") // or viper.SetConfigType("YAML")
+
+// any approach to require this configuration into your program.
+var yamlExample = []byte(`
+Hacker: true
+name: steve
+hobbies:
+- skateboarding
+- snowboarding
+- go
+clothing:
+  jacket: leather
+  trousers: denim
+age: 35
+eyes : brown
+beard: true
+`)
+
+viper.ReadConfig(bytes.NewBuffer(yamlExample))
+
+viper.Get("name") // this would be "steve"
+```
+
+### Setting Overrides
+
+These could be from a command line flag, or from your own application logic.
+
+```go
+viper.Set("Verbose", true)
+viper.Set("LogFile", LogFile)
+viper.Set("host.port", 5899)   // set subset
+```
+
+### Registering and Using Aliases
+
+Aliases permit a single value to be referenced by multiple keys
+
+```go
+viper.RegisterAlias("loud", "Verbose")
+
+viper.Set("verbose", true) // same result as next line
+viper.Set("loud", true)   // same result as prior line
+
+viper.GetBool("loud") // true
+viper.GetBool("verbose") // true
+```
+
+### Working with Environment Variables
+
+Viper has full support for environment variables. This enables 12 factor
+applications out of the box. There are five methods that exist to aid working
+with ENV:
+
+ * `AutomaticEnv()`
+ * `BindEnv(string...) : error`
+ * `SetEnvPrefix(string)`
+ * `SetEnvKeyReplacer(string...) *strings.Replacer`
+ * `AllowEmptyEnv(bool)`
+
+_When working with ENV variables, it’s important to recognize that Viper
+treats ENV variables as case sensitive._
+
+Viper provides a mechanism to try to ensure that ENV variables are unique. By
+using `SetEnvPrefix`, you can tell Viper to use a prefix while reading from
+the environment variables. Both `BindEnv` and `AutomaticEnv` will use this
+prefix.
+
+`BindEnv` takes one or more parameters. The first parameter is the key name, the
+rest are the name of the environment variables to bind to this key. If more than
+one are provided, they will take precedence in the specified order. The name of
+the environment variable is case sensitive. If the ENV variable name is not provided, then
+Viper will automatically assume that the ENV variable matches the following format: prefix + "_" + the key name in ALL CAPS. When you explicitly provide the ENV variable name (the second parameter),
+it **does not** automatically add the prefix. For example if the second parameter is "id",
+Viper will look for the ENV variable "ID".
+
+One important thing to recognize when working with ENV variables is that the
+value will be read each time it is accessed. Viper does not fix the value when
+the `BindEnv` is called.
+
+`AutomaticEnv` is a powerful helper especially when combined with
+`SetEnvPrefix`. When called, Viper will check for an environment variable any
+time a `viper.Get` request is made. It will apply the following rules. It will
+check for an environment variable with a name matching the key uppercased and
+prefixed with the `EnvPrefix` if set.
+
+`SetEnvKeyReplacer` allows you to use a `strings.Replacer` object to rewrite Env
+keys to an extent. This is useful if you want to use `-` or something in your
+`Get()` calls, but want your environmental variables to use `_` delimiters. An
+example of using it can be found in `viper_test.go`.
+
+Alternatively, you can use `EnvKeyReplacer` with `NewWithOptions` factory function.
+Unlike `SetEnvKeyReplacer`, it accepts a `StringReplacer` interface allowing you to write custom string replacing logic.
+
+By default empty environment variables are considered unset and will fall back to
+the next configuration source. To treat empty environment variables as set, use
+the `AllowEmptyEnv` method.
+
+#### Env example
+
+```go
+SetEnvPrefix("spf") // will be uppercased automatically
+BindEnv("id")
+
+os.Setenv("SPF_ID", "13") // typically done outside of the app
+
+id := Get("id") // 13
+```
+
+### Working with Flags
+
+Viper has the ability to bind to flags. Specifically, Viper supports `Pflags`
+as used in the [Cobra](https://github.com/spf13/cobra) library.
+
+Like `BindEnv`, the value is not set when the binding method is called, but when
+it is accessed. This means you can bind as early as you want, even in an
+`init()` function.
+
+For individual flags, the `BindPFlag()` method provides this functionality.
+
+Example:
+
+```go
+serverCmd.Flags().Int("port", 1138, "Port to run Application server on")
+viper.BindPFlag("port", serverCmd.Flags().Lookup("port"))
+```
+
+You can also bind an existing set of pflags (pflag.FlagSet):
+
+Example:
+
+```go
+pflag.Int("flagname", 1234, "help message for flagname")
+
+pflag.Parse()
+viper.BindPFlags(pflag.CommandLine)
+
+i := viper.GetInt("flagname") // retrieve values from viper instead of pflag
+```
+
+The use of [pflag](https://github.com/spf13/pflag/) in Viper does not preclude
+the use of other packages that use the [flag](https://golang.org/pkg/flag/)
+package from the standard library. The pflag package can handle the flags
+defined for the flag package by importing these flags. This is accomplished
+by a calling a convenience function provided by the pflag package called
+AddGoFlagSet().
+
+Example:
+
+```go
+package main
+
+import (
+	"flag"
+	"github.com/spf13/pflag"
+)
+
+func main() {
+
+	// using standard library "flag" package
+	flag.Int("flagname", 1234, "help message for flagname")
+
+	pflag.CommandLine.AddGoFlagSet(flag.CommandLine)
+	pflag.Parse()
+	viper.BindPFlags(pflag.CommandLine)
+
+	i := viper.GetInt("flagname") // retrieve value from viper
+
+	// ...
+}
+```
+
+#### Flag interfaces
+
+Viper provides two Go interfaces to bind other flag systems if you don’t use `Pflags`.
+
+`FlagValue` represents a single flag. This is a very simple example on how to implement this interface:
+
+```go
+type myFlag struct {}
+func (f myFlag) HasChanged() bool { return false }
+func (f myFlag) Name() string { return "my-flag-name" }
+func (f myFlag) ValueString() string { return "my-flag-value" }
+func (f myFlag) ValueType() string { return "string" }
+```
+
+Once your flag implements this interface, you can simply tell Viper to bind it:
+
+```go
+viper.BindFlagValue("my-flag-name", myFlag{})
+```
+
+`FlagValueSet` represents a group of flags. This is a very simple example on how to implement this interface:
+
+```go
+type myFlagSet struct {
+	flags []myFlag
+}
+
+func (f myFlagSet) VisitAll(fn func(FlagValue)) {
+	for _, flag := range flags {
+		fn(flag)
+	}
+}
+```
+
+Once your flag set implements this interface, you can simply tell Viper to bind it:
+
+```go
+fSet := myFlagSet{
+	flags: []myFlag{myFlag{}, myFlag{}},
+}
+viper.BindFlagValues("my-flags", fSet)
+```
+
+### Remote Key/Value Store Support
+
+To enable remote support in Viper, do a blank import of the `viper/remote`
+package:
+
+`import _ "github.com/spf13/viper/remote"`
+
+Viper will read a config string (as JSON, TOML, YAML, HCL or envfile) retrieved from a path
+in a Key/Value store such as etcd or Consul.  These values take precedence over
+default values, but are overridden by configuration values retrieved from disk,
+flags, or environment variables.
+
+Viper supports multiple hosts. To use, pass a list of endpoints separated by `;`. For example `http://127.0.0.1:4001;http://127.0.0.1:4002`.
+
+Viper uses [crypt](https://github.com/sagikazarmark/crypt) to retrieve
+configuration from the K/V store, which means that you can store your
+configuration values encrypted and have them automatically decrypted if you have
+the correct gpg keyring.  Encryption is optional.
+
+You can use remote configuration in conjunction with local configuration, or
+independently of it.
+
+`crypt` has a command-line helper that you can use to put configurations in your
+K/V store. `crypt` defaults to etcd on http://127.0.0.1:4001.
+
+```bash
+$ go get github.com/sagikazarmark/crypt/bin/crypt
+$ crypt set -plaintext /config/hugo.json /Users/hugo/settings/config.json
+```
+
+Confirm that your value was set:
+
+```bash
+$ crypt get -plaintext /config/hugo.json
+```
+
+See the `crypt` documentation for examples of how to set encrypted values, or
+how to use Consul.
+
+### Remote Key/Value Store Example - Unencrypted
+
+#### etcd
+```go
+viper.AddRemoteProvider("etcd", "http://127.0.0.1:4001","/config/hugo.json")
+viper.SetConfigType("json") // because there is no file extension in a stream of bytes, supported extensions are "json", "toml", "yaml", "yml", "properties", "props", "prop", "env", "dotenv"
+err := viper.ReadRemoteConfig()
+```
+
+#### etcd3
+```go
+viper.AddRemoteProvider("etcd3", "http://127.0.0.1:4001","/config/hugo.json")
+viper.SetConfigType("json") // because there is no file extension in a stream of bytes, supported extensions are "json", "toml", "yaml", "yml", "properties", "props", "prop", "env", "dotenv"
+err := viper.ReadRemoteConfig()
+```
+
+#### Consul
+You need to set a key to Consul key/value storage with JSON value containing your desired config.
+For example, create a Consul key/value store key `MY_CONSUL_KEY` with value:
+
+```json
+{
+    "port": 8080,
+    "hostname": "myhostname.com"
+}
+```
+
+```go
+viper.AddRemoteProvider("consul", "localhost:8500", "MY_CONSUL_KEY")
+viper.SetConfigType("json") // Need to explicitly set this to json
+err := viper.ReadRemoteConfig()
+
+fmt.Println(viper.Get("port")) // 8080
+fmt.Println(viper.Get("hostname")) // myhostname.com
+```
+
+#### Firestore
+
+```go
+viper.AddRemoteProvider("firestore", "google-cloud-project-id", "collection/document")
+viper.SetConfigType("json") // Config's format: "json", "toml", "yaml", "yml"
+err := viper.ReadRemoteConfig()
+```
+
+Of course, you're allowed to use `SecureRemoteProvider` also
+
+
+#### NATS
+
+```go
+viper.AddRemoteProvider("nats", "nats://127.0.0.1:4222", "myapp.config")
+viper.SetConfigType("json")
+err := viper.ReadRemoteConfig()
+```
+
+### Remote Key/Value Store Example - Encrypted
+
+```go
+viper.AddSecureRemoteProvider("etcd","http://127.0.0.1:4001","/config/hugo.json","/etc/secrets/mykeyring.gpg")
+viper.SetConfigType("json") // because there is no file extension in a stream of bytes,  supported extensions are "json", "toml", "yaml", "yml", "properties", "props", "prop", "env", "dotenv"
+err := viper.ReadRemoteConfig()
+```
+
+### Watching Changes in etcd - Unencrypted
+
+```go
+// alternatively, you can create a new viper instance.
+var runtime_viper = viper.New()
+
+runtime_viper.AddRemoteProvider("etcd", "http://127.0.0.1:4001", "/config/hugo.yml")
+runtime_viper.SetConfigType("yaml") // because there is no file extension in a stream of bytes, supported extensions are "json", "toml", "yaml", "yml", "properties", "props", "prop", "env", "dotenv"
+
+// read from remote config the first time.
+err := runtime_viper.ReadRemoteConfig()
+
+// unmarshal config
+runtime_viper.Unmarshal(&runtime_conf)
+
+// open a goroutine to watch remote changes forever
+go func(){
+	for {
+		time.Sleep(time.Second * 5) // delay after each request
+
+		// currently, only tested with etcd support
+		err := runtime_viper.WatchRemoteConfig()
+		if err != nil {
+			log.Errorf("unable to read remote config: %v", err)
+			continue
+		}
+
+		// unmarshal new config into our runtime config struct. you can also use channel
+		// to implement a signal to notify the system of the changes
+		runtime_viper.Unmarshal(&runtime_conf)
+	}
+}()
+```
+
+## Getting Values From Viper
+
+In Viper, there are a few ways to get a value depending on the value’s type.
+The following functions and methods exist:
+
+ * `Get(key string) : any`
+ * `GetBool(key string) : bool`
+ * `GetFloat64(key string) : float64`
+ * `GetInt(key string) : int`
+ * `GetIntSlice(key string) : []int`
+ * `GetString(key string) : string`
+ * `GetStringMap(key string) : map[string]any`
+ * `GetStringMapString(key string) : map[string]string`
+ * `GetStringSlice(key string) : []string`
+ * `GetTime(key string) : time.Time`
+ * `GetDuration(key string) : time.Duration`
+ * `IsSet(key string) : bool`
+ * `AllSettings() : map[string]any`
+
+One important thing to recognize is that each Get function will return a zero
+value if it’s not found. To check if a given key exists, the `IsSet()` method
+has been provided.
+
+The zero value will also be returned if the value is set, but fails to parse
+as the requested type.
+
+Example:
+```go
+viper.GetString("logfile") // case-insensitive Setting & Getting
+if viper.GetBool("verbose") {
+	fmt.Println("verbose enabled")
+}
+```
+### Accessing nested keys
+
+The accessor methods also accept formatted paths to deeply nested keys. For
+example, if the following JSON file is loaded:
+
+```json
+{
+    "host": {
+        "address": "localhost",
+        "port": 5799
+    },
+    "datastore": {
+        "metric": {
+            "host": "127.0.0.1",
+            "port": 3099
+        },
+        "warehouse": {
+            "host": "198.0.0.1",
+            "port": 2112
+        }
+    }
+}
+
+```
+
+Viper can access a nested field by passing a `.` delimited path of keys:
+
+```go
+GetString("datastore.metric.host") // (returns "127.0.0.1")
+```
+
+This obeys the precedence rules established above; the search for the path
+will cascade through the remaining configuration registries until found.
+
+For example, given this configuration file, both `datastore.metric.host` and
+`datastore.metric.port` are already defined (and may be overridden). If in addition
+`datastore.metric.protocol` was defined in the defaults, Viper would also find it.
+
+However, if `datastore.metric` was overridden (by a flag, an environment variable,
+the `Set()` method, …) with an immediate value, then all sub-keys of
+`datastore.metric` become undefined, they are “shadowed” by the higher-priority
+configuration level.
+
+Viper can access array indices by using numbers in the path. For example:
+
+```jsonc
+{
+    "host": {
+        "address": "localhost",
+        "ports": [
+            5799,
+            6029
+        ]
+    },
+    "datastore": {
+        "metric": {
+            "host": "127.0.0.1",
+            "port": 3099
+        },
+        "warehouse": {
+            "host": "198.0.0.1",
+            "port": 2112
+        }
+    }
+}
+
+GetInt("host.ports.1") // returns 6029
+
+```
+
+Lastly, if there exists a key that matches the delimited key path, its value
+will be returned instead. E.g.
+
+```jsonc
+{
+    "datastore.metric.host": "0.0.0.0",
+    "host": {
+        "address": "localhost",
+        "port": 5799
+    },
+    "datastore": {
+        "metric": {
+            "host": "127.0.0.1",
+            "port": 3099
+        },
+        "warehouse": {
+            "host": "198.0.0.1",
+            "port": 2112
+        }
+    }
+}
+
+GetString("datastore.metric.host") // returns "0.0.0.0"
+```
+
+### Extracting a sub-tree
+
+When developing reusable modules, it's often useful to extract a subset of the configuration
+and pass it to a module. This way the module can be instantiated more than once, with different configurations.
+
+For example, an application might use multiple different cache stores for different purposes:
+
+```yaml
+cache:
+  cache1:
+    max-items: 100
+    item-size: 64
+  cache2:
+    max-items: 200
+    item-size: 80
+```
+
+We could pass the cache name to a module (eg. `NewCache("cache1")`),
+but it would require weird concatenation for accessing config keys and would be less separated from the global config.
+
+So instead of doing that let's pass a Viper instance to the constructor that represents a subset of the configuration:
+
+```go
+cache1Config := viper.Sub("cache.cache1")
+if cache1Config == nil { // Sub returns nil if the key cannot be found
+	panic("cache configuration not found")
+}
+
+cache1 := NewCache(cache1Config)
+```
+
+**Note:** Always check the return value of `Sub`. It returns `nil` if a key cannot be found.
+
+Internally, the `NewCache` function can address `max-items` and `item-size` keys directly:
+
+```go
+func NewCache(v *Viper) *Cache {
+	return &Cache{
+		MaxItems: v.GetInt("max-items"),
+		ItemSize: v.GetInt("item-size"),
+	}
+}
+```
+
+The resulting code is easy to test, since it's decoupled from the main config structure,
+and easier to reuse (for the same reason).
+
+
+### Unmarshaling
+
+You also have the option of Unmarshaling all or a specific value to a struct, map,
+etc.
+
+There are two methods to do this:
+
+ * `Unmarshal(rawVal any) : error`
+ * `UnmarshalKey(key string, rawVal any) : error`
+
+Example:
+
+```go
+type config struct {
+	Port int
+	Name string
+	PathMap string `mapstructure:"path_map"`
+}
+
+var C config
+
+err := viper.Unmarshal(&C)
+if err != nil {
+	t.Fatalf("unable to decode into struct, %v", err)
+}
+```
+
+If you want to unmarshal configuration where the keys themselves contain dot (the default key delimiter),
+you have to change the delimiter:
+
+```go
+v := viper.NewWithOptions(viper.KeyDelimiter("::"))
+
+v.SetDefault("chart::values", map[string]any{
+	"ingress": map[string]any{
+		"annotations": map[string]any{
+			"traefik.frontend.rule.type":                 "PathPrefix",
+			"traefik.ingress.kubernetes.io/ssl-redirect": "true",
+		},
+	},
+})
+
+type config struct {
+	Chart struct{
+		Values map[string]any
+	}
+}
+
+var C config
+
+v.Unmarshal(&C)
+```
+
+Viper also supports unmarshaling into embedded structs:
+
+```go
+/*
+Example config:
+
+module:
+    enabled: true
+    token: 89h3f98hbwf987h3f98wenf89ehf
+*/
+type config struct {
+	Module struct {
+		Enabled bool
+
+		moduleConfig `mapstructure:",squash"`
+	}
+}
+
+// moduleConfig could be in a module specific package
+type moduleConfig struct {
+	Token string
+}
+
+var C config
+
+err := viper.Unmarshal(&C)
+if err != nil {
+	t.Fatalf("unable to decode into struct, %v", err)
+}
+```
+
+Viper uses [github.com/go-viper/mapstructure](https://github.com/go-viper/mapstructure) under the hood for unmarshaling values which uses `mapstructure` tags by default.
+
+### Decoding custom formats
+
+A frequently requested feature for Viper is adding more value formats and decoders.
+For example, parsing character (dot, comma, semicolon, etc) separated strings into slices.
+
+This is already available in Viper using mapstructure decode hooks.
+
+Read more about the details in [this blog post](https://sagikazarmark.hu/blog/decoding-custom-formats-with-viper/).
+
+### Marshalling to string
+
+You may need to marshal all the settings held in viper into a string rather than write them to a file.
+You can use your favorite format's marshaller with the config returned by `AllSettings()`.
+
+```go
+import (
+	yaml "go.yaml.in/yaml/v3"
+	// ...
+)
+
+func yamlStringSettings() string {
+	c := viper.AllSettings()
+	bs, err := yaml.Marshal(c)
+	if err != nil {
+		log.Fatalf("unable to marshal config to YAML: %v", err)
+	}
+	return string(bs)
+}
+```
+
+## Viper or Vipers?
+
+Viper comes with a global instance (singleton) out of the box.
+
+Although it makes setting up configuration easy,
+using it is generally discouraged as it makes testing harder and can lead to unexpected behavior.
+
+The best practice is to initialize a Viper instance and pass that around when necessary.
+
+The global instance _MAY_ be deprecated in the future.
+See [#1855](https://github.com/spf13/viper/issues/1855) for more details.
+
+### Working with multiple vipers
+
+You can also create many different vipers for use in your application. Each will
+have its own unique set of configurations and values. Each can read from a
+different config file, key value store, etc. All of the functions that viper
+package supports are mirrored as methods on a viper.
+
+Example:
+
+```go
+x := viper.New()
+y := viper.New()
+
+x.SetDefault("ContentDir", "content")
+y.SetDefault("ContentDir", "foobar")
+
+//...
+```
+
+When working with multiple vipers, it is up to the user to keep track of the
+different vipers.
+
+
+## Q & A
+
+### Why is it called “Viper”?
+
+A: Viper is designed to be a [companion](http://en.wikipedia.org/wiki/Viper_(G.I._Joe))
+to [Cobra](https://github.com/spf13/cobra). While both can operate completely
+independently, together they make a powerful pair to handle much of your
+application foundation needs.
+
+### Why is it called “Cobra”?
+
+Is there a better name for a [commander](http://en.wikipedia.org/wiki/Cobra_Commander)?
+
+### Does Viper support case sensitive keys?
+
+**tl;dr:** No.
+
+Viper merges configuration from various sources, many of which are either case insensitive or uses different casing than the rest of the sources (eg. env vars).
+In order to provide the best experience when using multiple sources, the decision has been made to make all keys case insensitive.
+
+There has been several attempts to implement case sensitivity, but unfortunately it's not that trivial. We might take a stab at implementing it in [Viper v2](https://github.com/spf13/viper/issues/772), but despite the initial noise, it does not seem to be requested that much.
+
+You can vote for case sensitivity by filling out this feedback form: https://forms.gle/R6faU74qPRPAzchZ9
+
+### Is it safe to concurrently read and write to a viper?
+
+No, you will need to synchronize access to the viper yourself (for example by using the `sync` package). Concurrent reads and writes can cause a panic.
+
+## Troubleshooting
+
+See [TROUBLESHOOTING.md](TROUBLESHOOTING.md).
+
+## Development
+
+**For an optimal developer experience, it is recommended to install [Nix](https://nixos.org/download.html) and [direnv](https://direnv.net/docs/installation.html).**
+
+_Alternatively, install [Go](https://go.dev/dl/) on your computer then run `make deps` to install the rest of the dependencies._
+
+Run the test suite:
+
+```shell
+make test
+```
+
+Run linters:
+
+```shell
+make lint # pass -j option to run them in parallel
+```
+
+Some linter violations can automatically be fixed:
+
+```shell
+make fmt
+```
+
+## License
+
+The project is licensed under the [MIT License](LICENSE).
@@ -0,0 +1,32 @@
+# Troubleshooting
+
+## Unmarshaling doesn't work
+
+The most common reason for this issue is improper use of struct tags (eg. `yaml` or `json`). Viper uses [github.com/mitchellh/mapstructure](https://github.com/mitchellh/mapstructure) under the hood for unmarshaling values which uses `mapstructure` tags by default. Please refer to the library's documentation for using other struct tags.
+
+## Cannot find package
+
+Viper installation seems to fail a lot lately with the following (or a similar) error:
+
+```
+cannot find package "github.com/hashicorp/hcl/tree/hcl1" in any of:
+/usr/local/Cellar/go/1.15.7_1/libexec/src/github.com/hashicorp/hcl/tree/hcl1 (from $GOROOT)
+/Users/user/go/src/github.com/hashicorp/hcl/tree/hcl1 (from $GOPATH)
+```
+
+As the error message suggests, Go tries to look up dependencies in `GOPATH` mode (as it's commonly called) from the `GOPATH`.
+Viper opted to use [Go Modules](https://go.dev/wiki/Modules) to manage its dependencies. While in many cases the two methods are interchangeable, once a dependency releases new (major) versions, `GOPATH` mode is no longer able to decide which version to use, so it'll either use one that's already present or pick a version (usually the `master` branch).
+
+The solution is easy: switch to using Go Modules.
+Please refer to the [wiki](https://go.dev/wiki/Modules) on how to do that.
+
+**tl;dr* `export GO111MODULE=on`
+
+## Unquoted 'y' and 'n' characters get replaced with _true_ and _false_ when reading a YAML file
+
+This is a YAML 1.1 feature according to [go-yaml/yaml#740](https://github.com/go-yaml/yaml/issues/740).
+
+Potential solutions are:
+
+1. Quoting values resolved as boolean
+1. Upgrading to YAML v3 (for the time being this is possible by passing the `viper_yaml3` tag to your build)
@@ -0,0 +1,147 @@
+# Update Log
+
+**This document details any major updates required to use new features or improvements in Viper.**
+
+## v1.20.x
+
+### New file searching API
+
+Viper now includes a new file searching API that allows users to customize how Viper looks for config files.
+
+Viper accepts a custom [`Finder`](https://pkg.go.dev/github.com/spf13/viper#Finder) interface implementation:
+
+```go
+// Finder looks for files and directories in an [afero.Fs] filesystem.
+type Finder interface {
+	Find(fsys afero.Fs) ([]string, error)
+}
+```
+
+It is supposed to return a list of paths to config files.
+
+The default implementation uses [github.com/sagikazarmark/locafero](https://github.com/sagikazarmark/locafero) under the hood.
+
+You can supply your own implementation using `WithFinder`:
+
+```go
+v := viper.NewWithOptions(
+    viper.WithFinder(&MyFinder{}),
+)
+```
+
+For more information, check out the [Finder examples](https://pkg.go.dev/github.com/spf13/viper#Finder)
+and the [documentation](https://pkg.go.dev/github.com/sagikazarmark/locafero) for the locafero package.
+
+### New encoding API
+
+Viper now allows customizing the encoding layer by providing an API for encoding and decoding configuration data:
+
+```go
+// Encoder encodes Viper's internal data structures into a byte representation.
+// It's primarily used for encoding a map[string]any into a file format.
+type Encoder interface {
+	Encode(v map[string]any) ([]byte, error)
+}
+
+// Decoder decodes the contents of a byte slice into Viper's internal data structures.
+// It's primarily used for decoding contents of a file into a map[string]any.
+type Decoder interface {
+	Decode(b []byte, v map[string]any) error
+}
+
+// Codec combines [Encoder] and [Decoder] interfaces.
+type Codec interface {
+	Encoder
+	Decoder
+}
+```
+
+By default, Viper includes the following codecs:
+
+- JSON
+- TOML
+- YAML
+- Dotenv
+
+The rest of the codecs are moved to [github.com/go-viper/encoding](https://github.com/go-viper/encoding)
+
+Customizing the encoding layer is possible by providing a custom registry of codecs:
+
+- [Encoder](https://pkg.go.dev/github.com/spf13/viper#Encoder) -> [EncoderRegistry](https://pkg.go.dev/github.com/spf13/viper#EncoderRegistry)
+- [Decoder](https://pkg.go.dev/github.com/spf13/viper#Decoder) -> [DecoderRegistry](https://pkg.go.dev/github.com/spf13/viper#DecoderRegistry)
+- [Codec](https://pkg.go.dev/github.com/spf13/viper#Codec) -> [CodecRegistry](https://pkg.go.dev/github.com/spf13/viper#CodecRegistry)
+
+You can supply the registry of codecs to Viper using the appropriate `With*Registry` function:
+
+```go
+codecRegistry := viper.NewCodecRegistry()
+
+codecRegistry.RegisterCodec("myformat", &MyCodec{})
+
+v := viper.NewWithOptions(
+    viper.WithCodecRegistry(codecRegistry),
+)
+```
+
+### BREAKING: "github.com/mitchellh/mapstructure" depedency replaced
+
+The original [mapstructure](https://github.com/mitchellh/mapstructure) has been [archived](https://github.com/mitchellh/mapstructure/issues/349) and was replaced with a [fork](https://github.com/go-viper/mapstructure) maintained by Viper ([#1723](https://github.com/spf13/viper/pull/1723)).
+
+As a result, the package import path needs to be changed in cases where `mapstructure` is directly referenced in your code.
+
+For example, when providing a custom decoder config:
+
+```go
+err := viper.Unmarshal(&appConfig, func(config *mapstructure.DecoderConfig) {
+	config.TagName = "yaml"
+})
+```
+
+The change is fairly straightforward, just replace all occurrences of the import path `github.com/mitchellh/mapstructure` with `github.com/go-viper/mapstructure/v2`:
+
+```diff
+- import "github.com/mitchellh/mapstructure"
+ import "github.com/go-viper/mapstructure/v2"
+```
+
+### BREAKING: HCL, Java properties, INI removed from core
+
+In order to reduce third-party dependencies, Viper dropped support for the following formats from the core:
+
+- HCL
+- Java properties
+- INI
+
+You can still use these formats though by importing them from [github.com/go-viper/encoding](https://github.com/go-viper/encoding):
+
+```go
+import (
+    "github.com/go-viper/encoding/hcl"
+    "github.com/go-viper/encoding/javaproperties"
+    "github.com/go-viper/encoding/ini"
+)
+
+codecRegistry := viper.NewCodecRegistry()
+
+{
+    codec := hcl.Codec{}
+
+    codecRegistry.RegisterCodec("hcl", codec)
+    codecRegistry.RegisterCodec("tfvars", codec)
+
+}
+
+{
+    codec := &javaproperties.Codec{}
+
+    codecRegistry.RegisterCodec("properties", codec)
+    codecRegistry.RegisterCodec("props", codec)
+    codecRegistry.RegisterCodec("prop", codec)
+}
+
+codecRegistry.RegisterCodec("ini", ini.Codec{})
+
+v := viper.NewWithOptions(
+    viper.WithCodecRegistry(codecRegistry),
+)
+```
@@ -0,0 +1,181 @@
+package viper
+
+import (
+	"errors"
+	"strings"
+	"sync"
+
+	"github.com/spf13/viper/internal/encoding/dotenv"
+	"github.com/spf13/viper/internal/encoding/json"
+	"github.com/spf13/viper/internal/encoding/toml"
+	"github.com/spf13/viper/internal/encoding/yaml"
+)
+
+// Encoder encodes Viper's internal data structures into a byte representation.
+// It's primarily used for encoding a map[string]any into a file format.
+type Encoder interface {
+	Encode(v map[string]any) ([]byte, error)
+}
+
+// Decoder decodes the contents of a byte slice into Viper's internal data structures.
+// It's primarily used for decoding contents of a file into a map[string]any.
+type Decoder interface {
+	Decode(b []byte, v map[string]any) error
+}
+
+// Codec combines [Encoder] and [Decoder] interfaces.
+type Codec interface {
+	Encoder
+	Decoder
+}
+
+// TODO: consider adding specific errors for not found scenarios
+
+// EncoderRegistry returns an [Encoder] for a given format.
+//
+// Format is case-insensitive.
+//
+// [EncoderRegistry] returns an error if no [Encoder] is registered for the format.
+type EncoderRegistry interface {
+	Encoder(format string) (Encoder, error)
+}
+
+// DecoderRegistry returns an [Decoder] for a given format.
+//
+// Format is case-insensitive.
+//
+// [DecoderRegistry] returns an error if no [Decoder] is registered for the format.
+type DecoderRegistry interface {
+	Decoder(format string) (Decoder, error)
+}
+
+// [CodecRegistry] combines [EncoderRegistry] and [DecoderRegistry] interfaces.
+type CodecRegistry interface {
+	EncoderRegistry
+	DecoderRegistry
+}
+
+// WithEncoderRegistry sets a custom [EncoderRegistry].
+func WithEncoderRegistry(r EncoderRegistry) Option {
+	return optionFunc(func(v *Viper) {
+		if r == nil {
+			return
+		}
+
+		v.encoderRegistry = r
+	})
+}
+
+// WithDecoderRegistry sets a custom [DecoderRegistry].
+func WithDecoderRegistry(r DecoderRegistry) Option {
+	return optionFunc(func(v *Viper) {
+		if r == nil {
+			return
+		}
+
+		v.decoderRegistry = r
+	})
+}
+
+// WithCodecRegistry sets a custom [EncoderRegistry] and [DecoderRegistry].
+func WithCodecRegistry(r CodecRegistry) Option {
+	return optionFunc(func(v *Viper) {
+		if r == nil {
+			return
+		}
+
+		v.encoderRegistry = r
+		v.decoderRegistry = r
+	})
+}
+
+// DefaultCodecRegistry is a simple implementation of [CodecRegistry] that allows registering custom [Codec]s.
+type DefaultCodecRegistry struct {
+	codecs map[string]Codec
+
+	mu   sync.RWMutex
+	once sync.Once
+}
+
+// NewCodecRegistry returns a new [CodecRegistry], ready to accept custom [Codec]s.
+func NewCodecRegistry() *DefaultCodecRegistry {
+	r := &DefaultCodecRegistry{}
+
+	r.init()
+
+	return r
+}
+
+func (r *DefaultCodecRegistry) init() {
+	r.once.Do(func() {
+		r.codecs = map[string]Codec{}
+	})
+}
+
+// RegisterCodec registers a custom [Codec].
+//
+// Format is case-insensitive.
+func (r *DefaultCodecRegistry) RegisterCodec(format string, codec Codec) error {
+	r.init()
+
+	r.mu.Lock()
+	defer r.mu.Unlock()
+
+	r.codecs[strings.ToLower(format)] = codec
+
+	return nil
+}
+
+// Encoder implements the [EncoderRegistry] interface.
+//
+// Format is case-insensitive.
+func (r *DefaultCodecRegistry) Encoder(format string) (Encoder, error) {
+	encoder, ok := r.codec(format)
+	if !ok {
+		return nil, errors.New("encoder not found for this format")
+	}
+
+	return encoder, nil
+}
+
+// Decoder implements the [DecoderRegistry] interface.
+//
+// Format is case-insensitive.
+func (r *DefaultCodecRegistry) Decoder(format string) (Decoder, error) {
+	decoder, ok := r.codec(format)
+	if !ok {
+		return nil, errors.New("decoder not found for this format")
+	}
+
+	return decoder, nil
+}
+
+func (r *DefaultCodecRegistry) codec(format string) (Codec, bool) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+
+	format = strings.ToLower(format)
+
+	if r.codecs != nil {
+		codec, ok := r.codecs[format]
+		if ok {
+			return codec, true
+		}
+	}
+
+	switch format {
+	case "yaml", "yml":
+		return yaml.Codec{}, true
+
+	case "json":
+		return json.Codec{}, true
+
+	case "toml":
+		return toml.Codec{}, true
+
+	case "dotenv", "env":
+		return &dotenv.Codec{}, true
+	}
+
+	return nil, false
+}
@@ -0,0 +1,8 @@
+package viper
+
+// ExperimentalBindStruct tells Viper to use the new bind struct feature.
+func ExperimentalBindStruct() Option {
+	return optionFunc(func(v *Viper) {
+		v.experimentalBindStruct = true
+	})
+}
@@ -0,0 +1,104 @@
+package viper
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+
+	"github.com/sagikazarmark/locafero"
+	"github.com/spf13/afero"
+)
+
+// ExperimentalFinder tells Viper to use the new Finder interface for finding configuration files.
+func ExperimentalFinder() Option {
+	return optionFunc(func(v *Viper) {
+		v.experimentalFinder = true
+	})
+}
+
+// Search for a config file.
+func (v *Viper) findConfigFile() (string, error) {
+	finder := v.finder
+
+	if finder == nil && v.experimentalFinder {
+		var names []string
+
+		if v.configType != "" {
+			names = locafero.NameWithOptionalExtensions(v.configName, SupportedExts...)
+		} else {
+			names = locafero.NameWithExtensions(v.configName, SupportedExts...)
+		}
+
+		finder = locafero.Finder{
+			Paths: v.configPaths,
+			Names: names,
+			Type:  locafero.FileTypeFile,
+		}
+	}
+
+	if finder != nil {
+		return v.findConfigFileWithFinder(finder)
+	}
+
+	return v.findConfigFileOld()
+}
+
+func (v *Viper) findConfigFileWithFinder(finder Finder) (string, error) {
+	results, err := finder.Find(v.fs)
+	if err != nil {
+		return "", err
+	}
+
+	if len(results) == 0 {
+		return "", ConfigFileNotFoundError{v.configName, fmt.Sprintf("%s", v.configPaths)}
+	}
+
+	// We call clean on the final result to ensure that the path is in its canonical form.
+	// This is mostly for consistent path handling and to make sure tests pass.
+	return results[0], nil
+}
+
+// Search all configPaths for any config file.
+// Returns the first path that exists (and is a config file).
+func (v *Viper) findConfigFileOld() (string, error) {
+	v.logger.Info("searching for config in paths", "paths", v.configPaths)
+
+	for _, cp := range v.configPaths {
+		file := v.searchInPath(cp)
+		if file != "" {
+			return file, nil
+		}
+	}
+	return "", ConfigFileNotFoundError{v.configName, fmt.Sprintf("%s", v.configPaths)}
+}
+
+func (v *Viper) searchInPath(in string) (filename string) {
+	v.logger.Debug("searching for config in path", "path", in)
+	for _, ext := range SupportedExts {
+		v.logger.Debug("checking if file exists", "file", filepath.Join(in, v.configName+"."+ext))
+		if b, _ := exists(v.fs, filepath.Join(in, v.configName+"."+ext)); b {
+			v.logger.Debug("found file", "file", filepath.Join(in, v.configName+"."+ext))
+			return filepath.Join(in, v.configName+"."+ext)
+		}
+	}
+
+	if v.configType != "" {
+		if b, _ := exists(v.fs, filepath.Join(in, v.configName)); b {
+			return filepath.Join(in, v.configName)
+		}
+	}
+
+	return ""
+}
+
+// exists checks if file exists.
+func exists(fs afero.Fs, path string) (bool, error) {
+	stat, err := fs.Stat(path)
+	if err == nil {
+		return !stat.IsDir(), nil
+	}
+	if os.IsNotExist(err) {
+		return false, nil
+	}
+	return false, err
+}
@@ -0,0 +1,55 @@
+package viper
+
+import (
+	"errors"
+
+	"github.com/spf13/afero"
+)
+
+// WithFinder sets a custom [Finder].
+func WithFinder(f Finder) Option {
+	return optionFunc(func(v *Viper) {
+		if f == nil {
+			return
+		}
+
+		v.finder = f
+	})
+}
+
+// Finder looks for files and directories in an [afero.Fs] filesystem.
+type Finder interface {
+	Find(fsys afero.Fs) ([]string, error)
+}
+
+// Finders combines multiple finders into one.
+func Finders(finders ...Finder) Finder {
+	return &combinedFinder{finders: finders}
+}
+
+// combinedFinder is a Finder that combines multiple finders.
+type combinedFinder struct {
+	finders []Finder
+}
+
+// Find implements the [Finder] interface.
+func (c *combinedFinder) Find(fsys afero.Fs) ([]string, error) {
+	var results []string
+	var errs []error
+
+	for _, finder := range c.finders {
+		if finder == nil {
+			continue
+		}
+
+		r, err := finder.Find(fsys)
+		if err != nil {
+			errs = append(errs, err)
+			continue
+		}
+
+		results = append(results, r...)
+	}
+
+	return results, errors.Join(errs...)
+}
@@ -0,0 +1,57 @@
+package viper
+
+import "github.com/spf13/pflag"
+
+// FlagValueSet is an interface that users can implement
+// to bind a set of flags to viper.
+type FlagValueSet interface {
+	VisitAll(fn func(FlagValue))
+}
+
+// FlagValue is an interface that users can implement
+// to bind different flags to viper.
+type FlagValue interface {
+	HasChanged() bool
+	Name() string
+	ValueString() string
+	ValueType() string
+}
+
+// pflagValueSet is a wrapper around *pflag.ValueSet
+// that implements FlagValueSet.
+type pflagValueSet struct {
+	flags *pflag.FlagSet
+}
+
+// VisitAll iterates over all *pflag.Flag inside the *pflag.FlagSet.
+func (p pflagValueSet) VisitAll(fn func(flag FlagValue)) {
+	p.flags.VisitAll(func(flag *pflag.Flag) {
+		fn(pflagValue{flag})
+	})
+}
+
+// pflagValue is a wrapper around *pflag.flag
+// that implements FlagValue.
+type pflagValue struct {
+	flag *pflag.Flag
+}
+
+// HasChanged returns whether the flag has changes or not.
+func (p pflagValue) HasChanged() bool {
+	return p.flag.Changed
+}
+
+// Name returns the name of the flag.
+func (p pflagValue) Name() string {
+	return p.flag.Name
+}
+
+// ValueString returns the value of the flag as a string.
+func (p pflagValue) ValueString() string {
+	return p.flag.Value.String()
+}
+
+// ValueType returns the type of the flag as a string.
+func (p pflagValue) ValueType() string {
+	return p.flag.Value.Type()
+}
@@ -0,0 +1,255 @@
+{
+  "nodes": {
+    "cachix": {
+      "inputs": {
+        "devenv": [
+          "devenv"
+        ],
+        "flake-compat": [
+          "devenv"
+        ],
+        "git-hooks": [
+          "devenv",
+          "git-hooks"
+        ],
+        "nixpkgs": [
+          "devenv",
+          "nixpkgs"
+        ]
+      },
+      "locked": {
+        "lastModified": 1748883665,
+        "narHash": "sha256-R0W7uAg+BLoHjMRMQ8+oiSbTq8nkGz5RDpQ+ZfxxP3A=",
+        "owner": "cachix",
+        "repo": "cachix",
+        "rev": "f707778d902af4d62d8dd92c269f8e70de09acbe",
+        "type": "github"
+      },
+      "original": {
+        "owner": "cachix",
+        "ref": "latest",
+        "repo": "cachix",
+        "type": "github"
+      }
+    },
+    "devenv": {
+      "inputs": {
+        "cachix": "cachix",
+        "flake-compat": "flake-compat",
+        "git-hooks": "git-hooks",
+        "nix": "nix",
+        "nixpkgs": "nixpkgs"
+      },
+      "locked": {
+        "lastModified": 1755257397,
+        "narHash": "sha256-VU+OHexL2y6y7yrpEc6bZvYYwoQg6aZK1b4YxT0yZCk=",
+        "owner": "cachix",
+        "repo": "devenv",
+        "rev": "6f9c3d4722aa253631644329f7bda60b1d3d1b97",
+        "type": "github"
+      },
+      "original": {
+        "owner": "cachix",
+        "repo": "devenv",
+        "type": "github"
+      }
+    },
+    "flake-compat": {
+      "flake": false,
+      "locked": {
+        "lastModified": 1747046372,
+        "narHash": "sha256-CIVLLkVgvHYbgI2UpXvIIBJ12HWgX+fjA8Xf8PUmqCY=",
+        "owner": "edolstra",
+        "repo": "flake-compat",
+        "rev": "9100a0f413b0c601e0533d1d94ffd501ce2e7885",
+        "type": "github"
+      },
+      "original": {
+        "owner": "edolstra",
+        "repo": "flake-compat",
+        "type": "github"
+      }
+    },
+    "flake-parts": {
+      "inputs": {
+        "nixpkgs-lib": [
+          "devenv",
+          "nix",
+          "nixpkgs"
+        ]
+      },
+      "locked": {
+        "lastModified": 1733312601,
+        "narHash": "sha256-4pDvzqnegAfRkPwO3wmwBhVi/Sye1mzps0zHWYnP88c=",
+        "owner": "hercules-ci",
+        "repo": "flake-parts",
+        "rev": "205b12d8b7cd4802fbcb8e8ef6a0f1408781a4f9",
+        "type": "github"
+      },
+      "original": {
+        "owner": "hercules-ci",
+        "repo": "flake-parts",
+        "type": "github"
+      }
+    },
+    "flake-parts_2": {
+      "inputs": {
+        "nixpkgs-lib": "nixpkgs-lib"
+      },
+      "locked": {
+        "lastModified": 1754487366,
+        "narHash": "sha256-pHYj8gUBapuUzKV/kN/tR3Zvqc7o6gdFB9XKXIp1SQ8=",
+        "owner": "hercules-ci",
+        "repo": "flake-parts",
+        "rev": "af66ad14b28a127c5c0f3bbb298218fc63528a18",
+        "type": "github"
+      },
+      "original": {
+        "owner": "hercules-ci",
+        "repo": "flake-parts",
+        "type": "github"
+      }
+    },
+    "git-hooks": {
+      "inputs": {
+        "flake-compat": [
+          "devenv",
+          "flake-compat"
+        ],
+        "gitignore": "gitignore",
+        "nixpkgs": [
+          "devenv",
+          "nixpkgs"
+        ]
+      },
+      "locked": {
+        "lastModified": 1750779888,
+        "narHash": "sha256-wibppH3g/E2lxU43ZQHC5yA/7kIKLGxVEnsnVK1BtRg=",
+        "owner": "cachix",
+        "repo": "git-hooks.nix",
+        "rev": "16ec914f6fb6f599ce988427d9d94efddf25fe6d",
+        "type": "github"
+      },
+      "original": {
+        "owner": "cachix",
+        "repo": "git-hooks.nix",
+        "type": "github"
+      }
+    },
+    "gitignore": {
+      "inputs": {
+        "nixpkgs": [
+          "devenv",
+          "git-hooks",
+          "nixpkgs"
+        ]
+      },
+      "locked": {
+        "lastModified": 1709087332,
+        "narHash": "sha256-HG2cCnktfHsKV0s4XW83gU3F57gaTljL9KNSuG6bnQs=",
+        "owner": "hercules-ci",
+        "repo": "gitignore.nix",
+        "rev": "637db329424fd7e46cf4185293b9cc8c88c95394",
+        "type": "github"
+      },
+      "original": {
+        "owner": "hercules-ci",
+        "repo": "gitignore.nix",
+        "type": "github"
+      }
+    },
+    "nix": {
+      "inputs": {
+        "flake-compat": [
+          "devenv",
+          "flake-compat"
+        ],
+        "flake-parts": "flake-parts",
+        "git-hooks-nix": [
+          "devenv",
+          "git-hooks"
+        ],
+        "nixpkgs": [
+          "devenv",
+          "nixpkgs"
+        ],
+        "nixpkgs-23-11": [
+          "devenv"
+        ],
+        "nixpkgs-regression": [
+          "devenv"
+        ]
+      },
+      "locked": {
+        "lastModified": 1755029779,
+        "narHash": "sha256-3+GHIYGg4U9XKUN4rg473frIVNn8YD06bjwxKS1IPrU=",
+        "owner": "cachix",
+        "repo": "nix",
+        "rev": "b0972b0eee6726081d10b1199f54de6d2917f861",
+        "type": "github"
+      },
+      "original": {
+        "owner": "cachix",
+        "ref": "devenv-2.30",
+        "repo": "nix",
+        "type": "github"
+      }
+    },
+    "nixpkgs": {
+      "locked": {
+        "lastModified": 1750441195,
+        "narHash": "sha256-yke+pm+MdgRb6c0dPt8MgDhv7fcBbdjmv1ZceNTyzKg=",
+        "owner": "cachix",
+        "repo": "devenv-nixpkgs",
+        "rev": "0ceffe312871b443929ff3006960d29b120dc627",
+        "type": "github"
+      },
+      "original": {
+        "owner": "cachix",
+        "ref": "rolling",
+        "repo": "devenv-nixpkgs",
+        "type": "github"
+      }
+    },
+    "nixpkgs-lib": {
+      "locked": {
+        "lastModified": 1753579242,
+        "narHash": "sha256-zvaMGVn14/Zz8hnp4VWT9xVnhc8vuL3TStRqwk22biA=",
+        "owner": "nix-community",
+        "repo": "nixpkgs.lib",
+        "rev": "0f36c44e01a6129be94e3ade315a5883f0228a6e",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nix-community",
+        "repo": "nixpkgs.lib",
+        "type": "github"
+      }
+    },
+    "nixpkgs_2": {
+      "locked": {
+        "lastModified": 1755268003,
+        "narHash": "sha256-nNaeJjo861wFR0tjHDyCnHs1rbRtrMgxAKMoig9Sj/w=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "32f313e49e42f715491e1ea7b306a87c16fe0388",
+        "type": "github"
+      },
+      "original": {
+        "owner": "NixOS",
+        "ref": "nixpkgs-unstable",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "root": {
+      "inputs": {
+        "devenv": "devenv",
+        "flake-parts": "flake-parts_2",
+        "nixpkgs": "nixpkgs_2"
+      }
+    }
+  },
+  "root": "root",
+  "version": 7
+}
@@ -0,0 +1,61 @@
+{
+  description = "Viper";
+
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable";
+    flake-parts.url = "github:hercules-ci/flake-parts";
+    devenv.url = "github:cachix/devenv";
+  };
+
+  outputs =
+    inputs@{ flake-parts, ... }:
+    flake-parts.lib.mkFlake { inherit inputs; } {
+      imports = [
+        inputs.devenv.flakeModule
+      ];
+
+      systems = [
+        "x86_64-linux"
+        "x86_64-darwin"
+        "aarch64-darwin"
+      ];
+
+      perSystem =
+        { pkgs, ... }:
+        {
+          devenv.shells = {
+            default = {
+              languages = {
+                go.enable = true;
+              };
+
+              git-hooks.hooks = {
+                nixpkgs-fmt.enable = true;
+                yamllint.enable = true;
+              };
+
+              packages = with pkgs; [
+                gnumake
+
+                golangci-lint
+                yamllint
+              ];
+
+              scripts = {
+                versions.exec = ''
+                  go version
+                  golangci-lint version
+                '';
+              };
+
+              enterShell = ''
+                versions
+              '';
+
+              # https://github.com/cachix/devenv/issues/528#issuecomment-1556108767
+              containers = pkgs.lib.mkForce { };
+            };
+          };
+        };
+    };
+}
@@ -0,0 +1,61 @@
+package dotenv
+
+import (
+	"bytes"
+	"fmt"
+	"sort"
+	"strings"
+
+	"github.com/subosito/gotenv"
+)
+
+const keyDelimiter = "_"
+
+// Codec implements the encoding.Encoder and encoding.Decoder interfaces for encoding data containing environment variables
+// (commonly called as dotenv format).
+type Codec struct{}
+
+func (Codec) Encode(v map[string]any) ([]byte, error) {
+	flattened := map[string]any{}
+
+	flattened = flattenAndMergeMap(flattened, v, "", keyDelimiter)
+
+	keys := make([]string, 0, len(flattened))
+
+	for key := range flattened {
+		keys = append(keys, key)
+	}
+
+	sort.Strings(keys)
+
+	var buf bytes.Buffer
+
+	for _, key := range keys {
+		_, err := buf.WriteString(fmt.Sprintf("%v=%v\n", strings.ToUpper(key), flattened[key]))
+		if err != nil {
+			return nil, err
+		}
+	}
+
+	return buf.Bytes(), nil
+}
+
+func (Codec) Decode(b []byte, v map[string]any) error {
+	var buf bytes.Buffer
+
+	_, err := buf.Write(b)
+	if err != nil {
+		return err
+	}
+
+	env, err := gotenv.StrictParse(&buf)
+	if err != nil {
+		return err
+	}
+
+	for key, value := range env {
+		v[key] = value
+	}
+
+	return nil
+}
@@ -0,0 +1,41 @@
+package dotenv
+
+import (
+	"strings"
+
+	"github.com/spf13/cast"
+)
+
+// flattenAndMergeMap recursively flattens the given map into a new map
+// Code is based on the function with the same name in the main package.
+// TODO: move it to a common place.
+func flattenAndMergeMap(shadow, m map[string]any, prefix, delimiter string) map[string]any {
+	if shadow != nil && prefix != "" && shadow[prefix] != nil {
+		// prefix is shadowed => nothing more to flatten
+		return shadow
+	}
+	if shadow == nil {
+		shadow = make(map[string]any)
+	}
+
+	var m2 map[string]any
+	if prefix != "" {
+		prefix += delimiter
+	}
+	for k, val := range m {
+		fullKey := prefix + k
+		switch val := val.(type) {
+		case map[string]any:
+			m2 = val
+		case map[any]any:
+			m2 = cast.ToStringMap(val)
+		default:
+			// immediate value
+			shadow[strings.ToLower(fullKey)] = val
+			continue
+		}
+		// recursively merge to shadow map
+		shadow = flattenAndMergeMap(shadow, m2, fullKey, delimiter)
+	}
+	return shadow
+}
@@ -0,0 +1,17 @@
+package json
+
+import (
+	"encoding/json"
+)
+
+// Codec implements the encoding.Encoder and encoding.Decoder interfaces for JSON encoding.
+type Codec struct{}
+
+func (Codec) Encode(v map[string]any) ([]byte, error) {
+	// TODO: expose prefix and indent in the Codec as setting?
+	return json.MarshalIndent(v, "", "  ")
+}
+
+func (Codec) Decode(b []byte, v map[string]any) error {
+	return json.Unmarshal(b, &v)
+}
@@ -0,0 +1,16 @@
+package toml
+
+import (
+	"github.com/pelletier/go-toml/v2"
+)
+
+// Codec implements the encoding.Encoder and encoding.Decoder interfaces for TOML encoding.
+type Codec struct{}
+
+func (Codec) Encode(v map[string]any) ([]byte, error) {
+	return toml.Marshal(v)
+}
+
+func (Codec) Decode(b []byte, v map[string]any) error {
+	return toml.Unmarshal(b, &v)
+}
@@ -0,0 +1,14 @@
+package yaml
+
+import "go.yaml.in/yaml/v3"
+
+// Codec implements the encoding.Encoder and encoding.Decoder interfaces for YAML encoding.
+type Codec struct{}
+
+func (Codec) Encode(v map[string]any) ([]byte, error) {
+	return yaml.Marshal(v)
+}
+
+func (Codec) Decode(b []byte, v map[string]any) error {
+	return yaml.Unmarshal(b, &v)
+}
@@ -0,0 +1,5 @@
+//go:build viper_bind_struct
+
+package features
+
+const BindStruct = true
@@ -0,0 +1,5 @@
+//go:build !viper_bind_struct
+
+package features
+
+const BindStruct = false
@@ -0,0 +1,5 @@
+//go:build viper_finder
+
+package features
+
+const Finder = true
@@ -0,0 +1,5 @@
+//go:build !viper_finder
+
+package features
+
+const Finder = false
@@ -0,0 +1,31 @@
+package viper
+
+import (
+	"context"
+	"log/slog"
+)
+
+// WithLogger sets a custom logger.
+func WithLogger(l *slog.Logger) Option {
+	return optionFunc(func(v *Viper) {
+		v.logger = l
+	})
+}
+
+type discardHandler struct{}
+
+func (n *discardHandler) Enabled(_ context.Context, _ slog.Level) bool {
+	return false
+}
+
+func (n *discardHandler) Handle(_ context.Context, _ slog.Record) error {
+	return nil
+}
+
+func (n *discardHandler) WithAttrs(_ []slog.Attr) slog.Handler {
+	return n
+}
+
+func (n *discardHandler) WithGroup(_ string) slog.Handler {
+	return n
+}
@@ -0,0 +1,259 @@
+package viper
+
+import (
+	"bytes"
+	"fmt"
+	"io"
+	"reflect"
+	"slices"
+)
+
+// SupportedRemoteProviders are universally supported remote providers.
+var SupportedRemoteProviders = []string{"etcd", "etcd3", "consul", "firestore", "nats"}
+
+func resetRemote() {
+	SupportedRemoteProviders = []string{"etcd", "etcd3", "consul", "firestore", "nats"}
+}
+
+type remoteConfigFactory interface {
+	Get(rp RemoteProvider) (io.Reader, error)
+	Watch(rp RemoteProvider) (io.Reader, error)
+	WatchChannel(rp RemoteProvider) (<-chan *RemoteResponse, chan bool)
+}
+
+type RemoteResponse struct {
+	Value []byte
+	Error error
+}
+
+// RemoteConfig is optional, see the remote package.
+var RemoteConfig remoteConfigFactory
+
+// UnsupportedRemoteProviderError denotes encountering an unsupported remote
+// provider. Currently only etcd and Consul are supported.
+type UnsupportedRemoteProviderError string
+
+// Error returns the formatted remote provider error.
+func (str UnsupportedRemoteProviderError) Error() string {
+	return fmt.Sprintf("Unsupported Remote Provider Type %q", string(str))
+}
+
+// RemoteConfigError denotes encountering an error while trying to
+// pull the configuration from the remote provider.
+type RemoteConfigError string
+
+// Error returns the formatted remote provider error.
+func (rce RemoteConfigError) Error() string {
+	return fmt.Sprintf("Remote Configurations Error: %s", string(rce))
+}
+
+type defaultRemoteProvider struct {
+	provider      string
+	endpoint      string
+	path          string
+	secretKeyring string
+}
+
+func (rp defaultRemoteProvider) Provider() string {
+	return rp.provider
+}
+
+func (rp defaultRemoteProvider) Endpoint() string {
+	return rp.endpoint
+}
+
+func (rp defaultRemoteProvider) Path() string {
+	return rp.path
+}
+
+func (rp defaultRemoteProvider) SecretKeyring() string {
+	return rp.secretKeyring
+}
+
+// RemoteProvider stores the configuration necessary
+// to connect to a remote key/value store.
+// Optional secretKeyring to unencrypt encrypted values
+// can be provided.
+type RemoteProvider interface {
+	Provider() string
+	Endpoint() string
+	Path() string
+	SecretKeyring() string
+}
+
+// AddRemoteProvider adds a remote configuration source.
+// Remote Providers are searched in the order they are added.
+// provider is a string value: "etcd", "etcd3", "consul", "firestore" or "nats" are currently supported.
+// endpoint is the url.  etcd requires http://ip:port, consul requires ip:port, nats requires nats://ip:port
+// path is the path in the k/v store to retrieve configuration
+// To retrieve a config file called myapp.json from /configs/myapp.json
+// you should set path to /configs and set config name (SetConfigName()) to
+// "myapp".
+func AddRemoteProvider(provider, endpoint, path string) error {
+	return v.AddRemoteProvider(provider, endpoint, path)
+}
+
+func (v *Viper) AddRemoteProvider(provider, endpoint, path string) error {
+	if !slices.Contains(SupportedRemoteProviders, provider) {
+		return UnsupportedRemoteProviderError(provider)
+	}
+	if provider != "" && endpoint != "" {
+		v.logger.Info("adding remote provider", "provider", provider, "endpoint", endpoint)
+
+		rp := &defaultRemoteProvider{
+			endpoint: endpoint,
+			provider: provider,
+			path:     path,
+		}
+		if !v.providerPathExists(rp) {
+			v.remoteProviders = append(v.remoteProviders, rp)
+		}
+	}
+	return nil
+}
+
+// AddSecureRemoteProvider adds a remote configuration source.
+// Secure Remote Providers are searched in the order they are added.
+// provider is a string value: "etcd", "etcd3", "consul", "firestore" or "nats" are currently supported.
+// endpoint is the url.  etcd requires http://ip:port  consul requires ip:port
+// secretkeyring is the filepath to your openpgp secret keyring.  e.g. /etc/secrets/myring.gpg
+// path is the path in the k/v store to retrieve configuration
+// To retrieve a config file called myapp.json from /configs/myapp.json
+// you should set path to /configs and set config name (SetConfigName()) to
+// "myapp".
+// Secure Remote Providers are implemented with github.com/sagikazarmark/crypt.
+func AddSecureRemoteProvider(provider, endpoint, path, secretkeyring string) error {
+	return v.AddSecureRemoteProvider(provider, endpoint, path, secretkeyring)
+}
+
+func (v *Viper) AddSecureRemoteProvider(provider, endpoint, path, secretkeyring string) error {
+	if !slices.Contains(SupportedRemoteProviders, provider) {
+		return UnsupportedRemoteProviderError(provider)
+	}
+	if provider != "" && endpoint != "" {
+		v.logger.Info("adding remote provider", "provider", provider, "endpoint", endpoint)
+
+		rp := &defaultRemoteProvider{
+			endpoint:      endpoint,
+			provider:      provider,
+			path:          path,
+			secretKeyring: secretkeyring,
+		}
+		if !v.providerPathExists(rp) {
+			v.remoteProviders = append(v.remoteProviders, rp)
+		}
+	}
+	return nil
+}
+
+func (v *Viper) providerPathExists(p *defaultRemoteProvider) bool {
+	for _, y := range v.remoteProviders {
+		if reflect.DeepEqual(y, p) {
+			return true
+		}
+	}
+	return false
+}
+
+// ReadRemoteConfig attempts to get configuration from a remote source
+// and read it in the remote configuration registry.
+func ReadRemoteConfig() error { return v.ReadRemoteConfig() }
+
+func (v *Viper) ReadRemoteConfig() error {
+	return v.getKeyValueConfig()
+}
+
+func WatchRemoteConfig() error { return v.WatchRemoteConfig() }
+func (v *Viper) WatchRemoteConfig() error {
+	return v.watchKeyValueConfig()
+}
+
+func (v *Viper) WatchRemoteConfigOnChannel() error {
+	return v.watchKeyValueConfigOnChannel()
+}
+
+// Retrieve the first found remote configuration.
+func (v *Viper) getKeyValueConfig() error {
+	if RemoteConfig == nil {
+		return RemoteConfigError("Enable the remote features by doing a blank import of the viper/remote package: '_ github.com/spf13/viper/remote'")
+	}
+
+	if len(v.remoteProviders) == 0 {
+		return RemoteConfigError("No Remote Providers")
+	}
+
+	for _, rp := range v.remoteProviders {
+		val, err := v.getRemoteConfig(rp)
+		if err != nil {
+			v.logger.Error(fmt.Errorf("get remote config: %w", err).Error())
+
+			continue
+		}
+
+		v.kvstore = val
+
+		return nil
+	}
+	return RemoteConfigError("No Files Found")
+}
+
+func (v *Viper) getRemoteConfig(provider RemoteProvider) (map[string]any, error) {
+	reader, err := RemoteConfig.Get(provider)
+	if err != nil {
+		return nil, err
+	}
+	err = v.unmarshalReader(reader, v.kvstore)
+	return v.kvstore, err
+}
+
+// Retrieve the first found remote configuration.
+func (v *Viper) watchKeyValueConfigOnChannel() error {
+	if len(v.remoteProviders) == 0 {
+		return RemoteConfigError("No Remote Providers")
+	}
+
+	for _, rp := range v.remoteProviders {
+		respc, _ := RemoteConfig.WatchChannel(rp)
+		// Todo: Add quit channel
+		go func(rc <-chan *RemoteResponse) {
+			for {
+				b := <-rc
+				reader := bytes.NewReader(b.Value)
+				err := v.unmarshalReader(reader, v.kvstore)
+				if err != nil {
+					v.logger.Error(fmt.Errorf("failed to unmarshal remote config: %w", err).Error())
+				}
+			}
+		}(respc)
+		return nil
+	}
+	return RemoteConfigError("No Files Found")
+}
+
+// Retrieve the first found remote configuration.
+func (v *Viper) watchKeyValueConfig() error {
+	if len(v.remoteProviders) == 0 {
+		return RemoteConfigError("No Remote Providers")
+	}
+
+	for _, rp := range v.remoteProviders {
+		val, err := v.watchRemoteConfig(rp)
+		if err != nil {
+			v.logger.Error(fmt.Errorf("watch remote config: %w", err).Error())
+
+			continue
+		}
+		v.kvstore = val
+		return nil
+	}
+	return RemoteConfigError("No Files Found")
+}
+
+func (v *Viper) watchRemoteConfig(provider RemoteProvider) (map[string]any, error) {
+	reader, err := RemoteConfig.Watch(provider)
+	if err != nil {
+		return nil, err
+	}
+	err = v.unmarshalReader(reader, v.kvstore)
+	return v.kvstore, err
+}
@@ -0,0 +1,211 @@
+// Copyright © 2014 Steve Francia <spf@spf13.com>.
+//
+// Use of this source code is governed by an MIT-style
+// license that can be found in the LICENSE file.
+
+// Viper is a application configuration system.
+// It believes that applications can be configured a variety of ways
+// via flags, ENVIRONMENT variables, configuration files retrieved
+// from the file system, or a remote key/value store.
+
+package viper
+
+import (
+	"fmt"
+	"log/slog"
+	"os"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"unicode"
+
+	"github.com/spf13/cast"
+)
+
+// ConfigParseError denotes failing to parse configuration file.
+type ConfigParseError struct {
+	err error
+}
+
+// Error returns the formatted configuration error.
+func (pe ConfigParseError) Error() string {
+	return fmt.Sprintf("While parsing config: %s", pe.err.Error())
+}
+
+// Unwrap returns the wrapped error.
+func (pe ConfigParseError) Unwrap() error {
+	return pe.err
+}
+
+// toCaseInsensitiveValue checks if the value is a  map;
+// if so, create a copy and lower-case the keys recursively.
+func toCaseInsensitiveValue(value any) any {
+	switch v := value.(type) {
+	case map[any]any:
+		value = copyAndInsensitiviseMap(cast.ToStringMap(v))
+	case map[string]any:
+		value = copyAndInsensitiviseMap(v)
+	}
+
+	return value
+}
+
+// copyAndInsensitiviseMap behaves like insensitiviseMap, but creates a copy of
+// any map it makes case insensitive.
+func copyAndInsensitiviseMap(m map[string]any) map[string]any {
+	nm := make(map[string]any)
+
+	for key, val := range m {
+		lkey := strings.ToLower(key)
+		switch v := val.(type) {
+		case map[any]any:
+			nm[lkey] = copyAndInsensitiviseMap(cast.ToStringMap(v))
+		case map[string]any:
+			nm[lkey] = copyAndInsensitiviseMap(v)
+		default:
+			nm[lkey] = v
+		}
+	}
+
+	return nm
+}
+
+func insensitiviseVal(val any) any {
+	switch v := val.(type) {
+	case map[any]any:
+		// nested map: cast and recursively insensitivise
+		val = cast.ToStringMap(val)
+		insensitiviseMap(val.(map[string]any))
+	case map[string]any:
+		// nested map: recursively insensitivise
+		insensitiviseMap(v)
+	case []any:
+		// nested array: recursively insensitivise
+		insensitiveArray(v)
+	}
+	return val
+}
+
+func insensitiviseMap(m map[string]any) {
+	for key, val := range m {
+		val = insensitiviseVal(val)
+		lower := strings.ToLower(key)
+		if key != lower {
+			// remove old key (not lower-cased)
+			delete(m, key)
+		}
+		// update map
+		m[lower] = val
+	}
+}
+
+func insensitiveArray(a []any) {
+	for i, val := range a {
+		a[i] = insensitiviseVal(val)
+	}
+}
+
+func absPathify(logger *slog.Logger, inPath string) string {
+	logger.Info("trying to resolve absolute path", "path", inPath)
+
+	if inPath == "$HOME" || strings.HasPrefix(inPath, "$HOME"+string(os.PathSeparator)) {
+		inPath = userHomeDir() + inPath[5:]
+	}
+
+	inPath = os.ExpandEnv(inPath)
+
+	if filepath.IsAbs(inPath) {
+		return filepath.Clean(inPath)
+	}
+
+	p, err := filepath.Abs(inPath)
+	if err == nil {
+		return filepath.Clean(p)
+	}
+
+	logger.Error(fmt.Errorf("could not discover absolute path: %w", err).Error())
+
+	return ""
+}
+
+func userHomeDir() string {
+	if runtime.GOOS == "windows" {
+		home := os.Getenv("HOMEDRIVE") + os.Getenv("HOMEPATH")
+		if home == "" {
+			home = os.Getenv("USERPROFILE")
+		}
+		return home
+	}
+	return os.Getenv("HOME")
+}
+
+func safeMul(a, b uint) uint {
+	c := a * b
+	if a > 1 && b > 1 && c/b != a {
+		return 0
+	}
+	return c
+}
+
+// parseSizeInBytes converts strings like 1GB or 12 mb into an unsigned integer number of bytes.
+func parseSizeInBytes(sizeStr string) uint {
+	sizeStr = strings.TrimSpace(sizeStr)
+	lastChar := len(sizeStr) - 1
+	multiplier := uint(1)
+
+	if lastChar > 0 {
+		if sizeStr[lastChar] == 'b' || sizeStr[lastChar] == 'B' {
+			if lastChar > 1 {
+				switch unicode.ToLower(rune(sizeStr[lastChar-1])) {
+				case 'k':
+					multiplier = 1 << 10
+					sizeStr = strings.TrimSpace(sizeStr[:lastChar-1])
+				case 'm':
+					multiplier = 1 << 20
+					sizeStr = strings.TrimSpace(sizeStr[:lastChar-1])
+				case 'g':
+					multiplier = 1 << 30
+					sizeStr = strings.TrimSpace(sizeStr[:lastChar-1])
+				default:
+					multiplier = 1
+					sizeStr = strings.TrimSpace(sizeStr[:lastChar])
+				}
+			}
+		}
+	}
+
+	size := max(cast.ToInt(sizeStr), 0)
+
+	return safeMul(uint(size), multiplier)
+}
+
+// deepSearch scans deep maps, following the key indexes listed in the
+// sequence "path".
+// The last value is expected to be another map, and is returned.
+//
+// In case intermediate keys do not exist, or map to a non-map value,
+// a new map is created and inserted, and the search continues from there:
+// the initial map "m" may be modified!
+func deepSearch(m map[string]any, path []string) map[string]any {
+	for _, k := range path {
+		m2, ok := m[k]
+		if !ok {
+			// intermediate key does not exist
+			// => create it and continue from there
+			m3 := make(map[string]any)
+			m[k] = m3
+			m = m3
+			continue
+		}
+		m3, ok := m2.(map[string]any)
+		if !ok {
+			// intermediate key is a value
+			// => replace with a new map
+			m3 = make(map[string]any)
+			m[k] = m3
+		}
+		// continue search from here
+		m = m3
+	}
+	return m
+}