Skip to content
This repository was archived by the owner on Jul 22, 2024. It is now read-only.

Commit 2fb8a82

Browse files
authored
Merge pull request #227 from dnephin/document-decode-with-squash
Update godoc about DecodeHooks and squash
2 parents 95075d6 + 35a4b15 commit 2fb8a82

File tree

1 file changed

+22
-7
lines changed

1 file changed

+22
-7
lines changed

mapstructure.go

+22-7
Original file line numberDiff line numberDiff line change
@@ -72,6 +72,17 @@
7272
// "name": "alice",
7373
// }
7474
//
75+
// When decoding from a struct to a map, the squash tag squashes the struct
76+
// fields into a single map. Using the example structs from above:
77+
//
78+
// Friend{Person: Person{Name: "alice"}}
79+
//
80+
// Will be decoded into a map:
81+
//
82+
// map[string]interface{}{
83+
// "name": "alice",
84+
// }
85+
//
7586
// DecoderConfig has a field that changes the behavior of mapstructure
7687
// to always squash embedded structs.
7788
//
@@ -161,10 +172,11 @@ import (
161172
// data transformations. See "DecodeHook" in the DecoderConfig
162173
// struct.
163174
//
164-
// The type should be DecodeHookFuncType or DecodeHookFuncKind.
165-
// Either is accepted. Types are a superset of Kinds (Types can return
166-
// Kinds) and are generally a richer thing to use, but Kinds are simpler
167-
// if you only need those.
175+
// The type must be one of DecodeHookFuncType, DecodeHookFuncKind, or
176+
// DecodeHookFuncValue.
177+
// Values are a superset of Types (Values can return types), and Types are a
178+
// superset of Kinds (Types can return Kinds) and are generally a richer thing
179+
// to use, but Kinds are simpler if you only need those.
168180
//
169181
// The reason DecodeHookFunc is multi-typed is for backwards compatibility:
170182
// we started with Kinds and then realized Types were the better solution,
@@ -189,10 +201,13 @@ type DecodeHookFuncValue func(from reflect.Value, to reflect.Value) (interface{}
189201
type DecoderConfig struct {
190202
// DecodeHook, if set, will be called before any decoding and any
191203
// type conversion (if WeaklyTypedInput is on). This lets you modify
192-
// the values before they're set down onto the resulting struct.
204+
// the values before they're set down onto the resulting struct. The
205+
// DecodeHook is called for every map and value in the input. This means
206+
// that if a struct has embedded fields with squash tags the decode hook
207+
// is called only once with all of the input data, not once for each
208+
// embedded struct.
193209
//
194-
// If an error is returned, the entire decode will fail with that
195-
// error.
210+
// If an error is returned, the entire decode will fail with that error.
196211
DecodeHook DecodeHookFunc
197212

198213
// If ErrorUnused is true, then it is an error for there to exist

0 commit comments

Comments
 (0)