Functions

The standalone steps behind the manager for reading the field tree, setting it, validating it, and computing defaults.

The manager wraps these functions for the common case. Reach for them directly when you want the field tree, or want to run one step in isolation with your own settings.

GetStructFields

func GetStructFields(structure any, parent *Field, encodingTags []string) ([]Field, error)

Reflects over structure (a pointer to a struct) and returns its fields as []Field, recursing into named nested structs and building each nested field's FQN (the dotted path and glued tags relative to the root). Pass nil for parent at the top level. encodingTags names the tags whose comma options are stripped.

SetStructFields

func SetStructFields(structure any, settings Settings, inputs map[string]any) error

Reads the field tree and sets each field from inputs, recursing into nested structs. This is what Struct.Set calls. Settings controls tag priority and override behavior.

func SetFields(fields []Field, settings Settings, inputs map[string]any) error
func SetField(field Field, settings Settings, inputs map[string]any) error

The recursive workers behind SetStructFields: SetFields over a whole field slice, SetField for one field. Use them when you already hold a []Field from GetStructFields.

Settings

type Settings struct {
	// TagOrder is the tag priority used to match input keys to fields
	// the first tag in the list that a field carries wins.
	TagOrder	[]string
	// AllowEnvOverride toggles whether env vars can be overridden by tag inputs
	// env var handling takes priority over tag handling and is enabled by having a tag `env:"ENV_VAR"`
	// this toggles whether `env:"ENV_VAR"` can be overridden by `anything:"env_var"`
	AllowEnvOverride	bool
	// AllowTagOverride toggles whether a later matching tag in TagOrder can
	// override a value already set by an earlier one.
	// if false, the first tag in TagOrder that matches wins and matching stops there.
	// if true, every matching tag is applied in order, so the last match wins.
	AllowTagOverride	bool
	// EncodingTags are the tags whose values use comma-separated options (see
	// DefaultEncodingTags). Empty disables comma stripping.
	EncodingTags	[]string
}

TagOrder is the tag priority used to match input keys to fields. AllowEnvOverride toggles whether an env:"..." value can be overridden by a tag input. AllowTagOverride toggles whether a later matching tag in TagOrder can override a value already set by an earlier one. When false the first match wins and matching stops. EncodingTags are the tags whose values use comma-separated options, and empty disables comma stripping.

ValidateStructFields

func ValidateStructFields(ruleFuncs map[string]RuleFunc, structFields []Field, values map[string]any, validationTag string, tagPriority ...string) (map[string][]string, error)

Runs each field's rules (looked up in ruleFuncs) against values and returns a map of field name to error messages. This is what Struct.Validate calls. See the rules reference for RuleFunc and the built-ins.

MapDefaultValues

func MapDefaultValues(fields []Field, values map[string]any, tagPriority ...string) map[string]any

Returns a copy of values with each field's default: tag value filled in under the field's tag name, for fields that have no non-empty value yet. Useful when you want the merged, default-filled map without setting the struct.

Field and NewField

type Field struct {
	// Name is the Go struct field name (e.g. "Field1").
	Name	string
	// Type is the string form of Kind (e.g. "string", "struct").
	Type	string
	// Tags holds the parsed struct tags as tag name to value (e.g. {"json": "field_1"}).
	Tags	map[string]string
	// Default is the `default:` tag value, kept as a string because it comes
	// from the tag; it is converted to the field's type when the field is set.
	Default	string
	// Kind is the field's reflect.Kind.
	Kind	reflect.Kind
	// Value is the addressable reflect.Value backing the field, used to set it.
	Value	reflect.Value
	// Rules are the validation rules parsed from the `rules:` tag.
	Rules	[]Rule
	// FQN is the fully-qualified view of a nested field: Name and Tags glued to
	// the parent's with "." (or "_" for the `env` tag). nil for top-level fields.
	FQN	*Field
	// Parent points to the enclosing struct's field, nil for top-level fields.
	Parent	*Field
	// Fields are the nested fields when Kind is reflect.Struct.
	Fields	[]Field
}

func NewField(name string, dataType reflect.Kind, value reflect.Value, tags map[string]string, parentField *Field) Field

Field is the reflected description of one struct field, produced by GetStructFields. Nested struct fields are described recursively through Fields, and each carries an FQN giving its dotted path relative to the root. NewField builds one from a struct field's name, kind, value, and parsed tags, extracting the default: and rules: tags into Default and Rules.

Edit or read the source on GitHub