configwalk

package
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 14, 2026 License: Apache-2.0 Imports: 6 Imported by: 0

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

Examples

Constants

View Source
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

View Source
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

func Defaults(prototype any) map[string]any

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

func Elem(t reflect.Type) reflect.Type

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.

func Walk

func Walk(root reflect.Type, visit func(t reflect.Type, fields []Field))

Walk calls visit once for each struct type reachable from root through fields, pointers, lists and maps, with the struct's keys as Fields returns them. A struct type that refers to itself is visited once.

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

func Fields(t reflect.Type) []Field

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".

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL