Update README
diff --git a/README.md b/README.md index 31d4b84..4877fe2 100644 --- a/README.md +++ b/README.md
@@ -17,54 +17,30 @@ $ go get github.com/mitchellh/mapstructure ``` -## Example +## Usage & Example -```go -import ( - "fmt" - "github.com/mitchellh/mapstructure" -) +For usage and examples see the [Godoc](http://godoc.org/github.com/mitchellh/mapstructure). -type Person struct { - Name string - Age int - Emails []string - Extra map[string]string +The `Decode` function has examples assocaited with it there. + +## But Why?! + +Go offers fantastic standard libraries for decoding formats such as JSON. +The standard method is to have a struct pre-created, and populate that struct +from the bytes of the encoded format. This is great, but the problem is if +you have configuration or an encoding that changes slightly depending on +specific fields. For example, consider this JSON: + +```json +{ + "type": "person", + "name": "Mitchell" } - -// This input can come from anywhere, but typically comes from -// something like decoding JSON where we're not quite sure of the -// struct initially. -input := map[string]interface{}{ - "name": "Mitchell", - "age": 91, - "emails": []string{"one", "two", "three"}, - "extra": map[string]string{ - "twitter": "mitchellh", - }, -} - -var result Person -err := mapstructure.Decode(input, &result) -if err != nil { - panic(err) -} - -// The value of "result" now contains what you would expect. The decoding -// process is properly type-checked and human-friendly errors are returned, -// if any. -fmt.Printf("%#v", result) ``` -If decoding fails for any reason, very helpful errors are returned. For -example, the string format of a `mapstructure.Error` may look like this: - -``` -5 error(s) decoding: - -* 'Name' expected type 'string', got 'int' -* 'Age' expected type 'int', got 'string' -* 'Emails[0]' expected type 'string', got 'int' -* 'Emails[1]' expected type 'string', got 'int' -* 'Emails[2]' expected type 'string', got 'int' -``` +Perhaps we can't populate a specific structure without first reading +the "type" field from the JSON. We could always do two passes over the +decoding of the JSON (reading the "type" first, and the rest later). +However, it is much simpler to just decode this into a `map[string]interface{}` +structure, read the "type" key, then use something like this library +to decode it into the proper structure.