Documentation
¶
Overview ¶
Package configwalk reads config structs the way the config loader does, so the things generated from them (a JSON Schema, an example file, a reference page) and the tests over them agree with what is decoded.
A struct's keys are its fields' mapstructure names, lower-cased as viper lower-cases keys; a field with no name uses its Go name. mapstructure reads the fields of a struct tagged ",squash" from the parent's keys, named field or embedded, and an embedded struct with no mapstructure tag likewise, so Fields inlines both. The package depends only on the standard library.
Index ¶
- Constants
- Variables
- func Defaults(prototype any) map[string]any
- func Elem(t reflect.Type) reflect.Type
- func IsIgnored(f reflect.StructField) bool
- func IsSquashed(f reflect.StructField) bool
- func Key(f reflect.StructField) string
- func SquashedFields(t reflect.Type) []reflect.StructField
- func Walk(root reflect.Type, visit func(t reflect.Type, fields []Field))
- type Field
- type KeyProblem
Examples ¶
Constants ¶
const ( IntegerPattern = `^([-+]?[0-9]+)?$` UnsignedPattern = `^(\+?[0-9]+)?$` NumberPattern = `^([-+]?([0-9]+(\.[0-9]*)?|\.[0-9]+)([eE][-+]?[0-9]+)?)?$` // DurationPattern matches what time.ParseDuration accepts. DurationPattern = `^[-+]?(0|(([0-9]+(\.[0-9]*)?|\.[0-9]+)(ns|us|µs|μs|ms|s|m|h))+)$` )
The patterns of the strings the config loader's weakly typed decoding converts to a number or a duration, for a generator that writes the schema of a scalar field. mapstructure parses an integer string with strconv.ParseInt in base 0, so it also accepts forms such as 0x1f and 1_000; these patterns accept decimal integers only. An empty string decodes to zero.
Variables ¶
var BoolStrings = []any{"", "1", "t", "T", "TRUE", "true", "True", "0", "f", "F", "FALSE", "false", "False"}
BoolStrings are the strings strconv.ParseBool accepts, which weakly typed decoding converts to a bool, and "", which it decodes to false.
Functions ¶
func Defaults ¶
Defaults returns the defaults a config type's constructor sets, keyed by the keys Fields reports: the value of each scalar field and list of scalars that prototype, a struct or a pointer to one, holds non-zero, written as it is in a config file (a duration as its string, "5s"). Structs, maps, pointers and interfaces record no default.
func Elem ¶
Elem returns the type a field of type t holds values of, looking through pointers, lists and maps.
func IsIgnored ¶
func IsIgnored(f reflect.StructField) bool
IsIgnored reports whether f is not a key: it is unexported and not embedded, or tagged `mapstructure:"-"`.
func IsSquashed ¶
func IsSquashed(f reflect.StructField) bool
IsSquashed reports whether f's fields are read from its parent's keys.
func Key ¶
func Key(f reflect.StructField) string
Key returns the key f is read from: its mapstructure name, or its Go name if it has none, lower-cased.
func SquashedFields ¶
func SquashedFields(t reflect.Type) []reflect.StructField
SquashedFields returns t's named struct fields tagged ",squash", including those of the structs it embeds. Some reflectors inline only embedded structs, so a generator can use these to inline the named ones as well.
Types ¶
type Field ¶
type Field struct {
// Key is the key the field is read from.
Key string
// StructField is the field itself. For a field of a squashed or embedded
// struct it is that struct's field, not the field that holds the struct.
StructField reflect.StructField
// Owner is the struct type StructField belongs to.
Owner reflect.Type
}
Field is one key of a struct.
func Fields ¶
Fields returns the keys of struct type t, in field order. The fields of an embedded struct, and of a struct tagged ",squash", are inlined, since they are read from t's own keys; a field ignored by IsIgnored is left out.
Example ¶
package main
import (
"fmt"
"reflect"
"github.com/dioad/config/configwalk"
)
func main() {
type config struct {
ListenAddress string `mapstructure:"listen-address"`
Limit struct {
RPS float64 `mapstructure:"rate-limit-rps"`
} `mapstructure:"limit,squash"`
}
for _, f := range configwalk.Fields(reflect.TypeFor[config]()) {
fmt.Println(f.Key)
}
}
Output: listen-address rate-limit-rps
type KeyProblem ¶
type KeyProblem struct {
// Field names the field as "Type.Field".
Field string
// Key is the offending key.
Key string
// Reason says which rule it breaks.
Reason string
}
KeyProblem is a config key that breaks the naming rules.
func KeyNamingProblems ¶
func KeyNamingProblems(root reflect.Type) []KeyProblem
KeyNamingProblems checks the keys of every struct reachable from root against the naming rules Dioad config files follow, and returns each key that breaks one:
- a key must not end in "config", since being in a config already says so: "tls-server", not "tls-server-config". This applies to the mapstructure key and to the json name of the same field, which names it in an API.
- a mapstructure key is kebab-case: lower-case words joined by hyphens.
A key may be exempt for a reason; filter the result in the test that calls this, keeping the reason beside the exemption.
Example ¶
package main
import (
"fmt"
"reflect"
"github.com/dioad/config/configwalk"
)
func main() {
type config struct {
TLS string `mapstructure:"tls-server-config"`
Listen string `mapstructure:"listen-address"`
}
for _, p := range configwalk.KeyNamingProblems(reflect.TypeFor[config]()) {
fmt.Println(p.Key, "-", p.Reason)
}
}
Output: tls-server-config - ends in "config"; drop the suffix
func (KeyProblem) String ¶
func (p KeyProblem) String() string
String returns the problem as "Type.Field: key: reason".