decode

Documentation

Overview

Package decode provides tools for customizing the decoding of configuration, into structures using mapstructure.

Index

• func HookTranslateKeys(_, to reflect.Type, data interface{}) (interface{}, error)
• func HookWeakDecodeFromSlice(from, to reflect.Type, data interface{}) (interface{}, error)

Functions

func HookTranslateKeys

func HookTranslateKeys(_, to reflect.Type, data interface{}) (interface{}, error)

HookTranslateKeys is a mapstructure decode hook which translates keys in a map to their canonical value.

Any struct field with a field tag of `alias` may be loaded from any of the values keyed by any of the aliases. A field may have one or more alias. Aliases must be lowercase, as keys are compared case-insensitive.

Example alias tag:

MyField []string `alias:"old_field_name,otherfieldname"`

This hook should ONLY be used to maintain backwards compatibility with deprecated keys. For new structures use mapstructure struct tags to set the desired serialization key.

IMPORTANT: This function assumes that mapstructure is being used with the default struct field tag of `mapstructure`. If mapstructure.DecoderConfig.TagName is set to a different value this function will need to be parameterized with that value to correctly find the canonical data key.

func HookWeakDecodeFromSlice

func HookWeakDecodeFromSlice(from, to reflect.Type, data interface{}) (interface{}, error)

HookWeakDecodeFromSlice looks for []map[string]interface{} and []interface{} in the source data. If the target is not a slice or array it attempts to unpack 1 item out of the slice. If there are more items the source data is left unmodified, allowing mapstructure to handle and report the decode error caused by mismatched types. The []interface{} is handled so that all slice types are behave the same way, and for the rare case when a raw structure is re-encoded to JSON, which will produce the []interface{}.

If this hook is being used on a "second pass" decode to decode an opaque configuration into a type, the DecodeConfig should set WeaklyTypedInput=true, (or another hook) to convert any scalar values into a slice of one value when the target is a slice. This is necessary because this hook would have converted the initial slices into single values on the first pass.

Background

HCL allows for repeated blocks which forces it to store structures as []map[string]interface{} instead of map[string]interface{}. This is an ambiguity which makes the generated structures incompatible with the corresponding JSON data.

This hook allows config to be read from the HCL format into a raw structure, and later decoded into a strongly typed structure.