Documentation
¶
Index ¶
- Variables
- func FromMap[T any](value map[string]any, options ...decoderOption) (*T, error)
- func NewDecoder(result any, options ...decoderOption) (*mapstructure.Decoder, error)
- func ToMap(value any, options ...decoderOption) (result map[string]any, err error)
- func WithAllowUnsetPointer() decoderOption
- func WithDecodeHook(decodeHook mapstructure.DecodeHookFunc) decoderOption
- func WithDecodeNil() decoderOption
- func WithErrorUnset() decoderOption
- func WithErrorUnused() decoderOption
- func WithIgnoreUntaggedFields(ignoreUntaggedFields bool) decoderOption
- func WithMatchName(matchName func(mapKey, fieldName string) bool) decoderOption
- func WithMetadata(metadata *Metadata) decoderOption
- func WithTagName(tagName string) decoderOption
- func WithWeaklyTypedInput() decoderOption
- func WithZeroFields() decoderOption
- type Metadata
Constants ¶
This section is empty.
Variables ¶
var ( // ErrInvalidToMapValue indicates the value passed to ToMap is not a struct. ErrInvalidToMapValue = errors.New("the value of ToMap function must be a struct") // ErrInvalidFromMapType indicates the type parameter of FromMap is not a struct. ErrInvalidFromMapType = errors.New("the type parameter of FromMap function must be a struct") // ErrValueOrZeroMethodNotFound indicates ValueOrZero method is missing on null.Value type. ErrValueOrZeroMethodNotFound = errors.New("ValueOrZero method not found on null.Value type") )
var ( // DecoderHook composes multiple decode hooks for comprehensive type conversion. // It includes hooks for null types, text unmarshalling, time parsing, URL parsing, IP parsing, and basic type conversion. DecoderHook = mapstructure.ComposeDecodeHookFunc( convertNullBool, convertNullString, convertNullInt, convertNullInt16, convertNullInt32, convertNullFloat, convertNullByte, convertNullDateTime, convertNullDate, convertNullTime, convertNullDecimal, convertNullValue, convertFileHeader, mapstructure.TextUnmarshallerHookFunc(), mapstructure.StringToTimeHookFunc(time.DateTime), mapstructure.StringToTimeLocationHookFunc(), mapstructure.StringToTimeDurationHookFunc(), mapstructure.StringToURLHookFunc(), mapstructure.StringToIPHookFunc(), mapstructure.StringToIPNetHookFunc(), mapstructure.StringToNetIPPrefixHookFunc(), mapstructure.StringToNetIPAddrHookFunc(), mapstructure.StringToNetIPAddrPortHookFunc(), mapstructure.StringToBasicTypeHookFunc(), ) )
Functions ¶
func FromMap ¶
FromMap converts a map[string]any to a struct value. The type parameter T must be a struct type.
func NewDecoder ¶
func NewDecoder(result any, options ...decoderOption) (*mapstructure.Decoder, error)
NewDecoder creates a mapstructure decoder with the given result and optional configuration. The decoder is configured with sensible defaults for struct-to-map and map-to-struct conversions.
func ToMap ¶
ToMap converts a struct value to a map[string]any. The input value must be a struct or a pointer to a struct.
func WithAllowUnsetPointer ¶
func WithAllowUnsetPointer() decoderOption
WithAllowUnsetPointer prevents pointer-type fields from being reported as unset. When enabled, pointer fields that remain nil won't trigger errors with WithErrorUnset(). This allows optional pointer fields without causing validation failures.
func WithDecodeHook ¶
func WithDecodeHook(decodeHook mapstructure.DecodeHookFunc) decoderOption
The hook is called before decoding and allows modification of values before setting them. It's called for every map and value in the input. Returning an error will cause the entire decode to fail. This replaces the default DecoderHook which includes time, URL, IP, and basic type conversions.
func WithDecodeNil ¶
func WithDecodeNil() decoderOption
WithDecodeNil enables running DecodeHook even when input values are nil. When enabled, the decode hook function will be called for nil inputs, allowing the hook to provide default values or perform nil-specific processing. This is useful for implementing default value logic in decode hooks.
func WithErrorUnset ¶
func WithErrorUnset() decoderOption
WithErrorUnset enables strict decoding that returns an error for unset fields in the result struct. When enabled, any struct fields that remain unset after decoding will cause an error. This applies to all nested structs and is useful for ensuring complete data population.
func WithErrorUnused ¶
func WithErrorUnused() decoderOption
WithErrorUnused enables strict decoding that returns an error for unused keys in the input map. When enabled, any map keys that don't correspond to struct fields will cause decoding to fail. This is useful for validating that all input data is being processed.
func WithIgnoreUntaggedFields ¶
func WithIgnoreUntaggedFields(ignoreUntaggedFields bool) decoderOption
WithIgnoreUntaggedFields controls whether struct fields without explicit tags are ignored. When true, fields without tags are skipped during decoding (similar to `mapstructure:"-"`). When false (default), untagged fields use their Go field names for mapping.
func WithMatchName ¶
Default uses CamelCase matching. The function receives the map key and struct field name, and should return true if they match. This allows implementing case-sensitive matching, snake_case conversion, or other custom naming strategies.
func WithMetadata ¶
func WithMetadata(metadata *Metadata) decoderOption
WithMetadata enables collection of decoding metadata. The provided Metadata struct will be populated with information about: - Keys: successfully decoded keys from the input - Unused: keys from input that weren't used - Unset: struct fields that weren't set during decoding This is useful for debugging and validation purposes.
func WithTagName ¶
func WithTagName(tagName string) decoderOption
Default is "json". This specifies which struct tag to read for field names. Example: WithTagName("yaml") will use `yaml:"field_name"` tags.
func WithWeaklyTypedInput ¶
func WithWeaklyTypedInput() decoderOption
WithWeaklyTypedInput enables flexible type conversions during decoding. When enabled, the decoder will attempt to convert between types automatically: - Strings to numbers, booleans, and other types - Numbers to strings - Various other weak type transformations This is useful when working with loosely-typed data sources like JSON.
func WithZeroFields ¶
func WithZeroFields() decoderOption
WithZeroFields enables zeroing of fields before writing new values. When enabled, struct fields are reset to their zero values before decoding. For maps, this empties the map before adding decoded values. This is useful when reusing structs or ensuring clean state.
Types ¶
type Metadata ¶
type Metadata = mapstructure.Metadata
Metadata is an alias for mapstructure.Metadata that contains decoding metadata.
Source Files