diff options
Diffstat (limited to 'vendor/github.com/go-playground/form/v4/doc.go')
| -rw-r--r-- | vendor/github.com/go-playground/form/v4/doc.go | 275 |
1 files changed, 0 insertions, 275 deletions
diff --git a/vendor/github.com/go-playground/form/v4/doc.go b/vendor/github.com/go-playground/form/v4/doc.go deleted file mode 100644 index f553dac2c..000000000 --- a/vendor/github.com/go-playground/form/v4/doc.go +++ /dev/null @@ -1,275 +0,0 @@ -/* -Package form Decodes url.Values into Go value(s) and Encodes Go value(s) into url.Values. - - -It has the following features: - - - Primitives types cause zero allocations. - - Supports map of almost all types. - - Supports both Numbered and Normal arrays eg. "Array[0]" and just "Array" - with multiple values passed. - - Slice honours the specified index. eg. if "Slice[2]" is the only Slice - value passed down, it will be put at index 2; if slice isn't big enough - it will be expanded. - - Array honours the specified index. eg. if "Array[2]" is the only Array - value passed down, it will be put at index 2; if array isn't big enough - a warning will be printed and value ignored. - - Only creates objects as necessary eg. if no `array` or `map` values are - passed down, the `array` and `map` are left as their default values in - the struct. - - Allows for Custom Type registration. - - Handles time.Time using RFC3339 time format by default, - but can easily be changed by registering a Custom Type, see below. - - Handles Encoding & Decoding of almost all Go types eg. can Decode into - struct, array, map, int... and Encode a struct, array, map, int... - -Common Questions - -Questions - - Does it support encoding.TextUnmarshaler? - No because TextUnmarshaler only accepts []byte but posted values can have - multiple values, so is not suitable. - - Mixing array/slice with array[idx]/slice[idx], in which order are they parsed? - array/slice then array[idx]/slice[idx] - -Supported Types - -out of the box supported types - - - string - - bool - - int, int8, int16, int32, int64 - - uint, uint8, uint16, uint32, uint64 - - float32, float64 - - struct and anonymous struct - - interface{} - - time.Time` - by default using RFC3339 - - a `pointer` to one of the above types - - slice, array - - map - - `custom types` can override any of the above types - - many other types may be supported inherently (eg. bson.ObjectId is - type ObjectId string, which will get populated by the string type - - **NOTE**: map, struct and slice nesting are ad infinitum. - -Usage - -symbols - - - Use symbol `.` for separating fields/structs. (eg. `structfield.field`) - - Use `[index or key]` for access to index of a slice/array or key for map. - (eg. `arrayfield[0]`, `mapfield[keyvalue]`) - -html - - <form method="POST"> - <input type="text" name="Name" value="joeybloggs"/> - <input type="text" name="Age" value="3"/> - <input type="text" name="Gender" value="Male"/> - <input type="text" name="Address[0].Name" value="26 Here Blvd."/> - <input type="text" name="Address[0].Phone" value="9(999)999-9999"/> - <input type="text" name="Address[1].Name" value="26 There Blvd."/> - <input type="text" name="Address[1].Phone" value="1(111)111-1111"/> - <input type="text" name="active" value="true"/> - <input type="text" name="MapExample[key]" value="value"/> - <input type="text" name="NestedMap[key][key]" value="value"/> - <input type="text" name="NestedArray[0][0]" value="value"/> - <input type="submit"/> - </form> - -Example - -example decoding the above HTML - - package main - - import ( - "fmt" - "log" - "net/url" - - "github.com/go-playground/form/v4" - ) - - // Address contains address information - type Address struct { - Name string - Phone string - } - - // User contains user information - type User struct { - Name string - Age uint8 - Gender string - Address []Address - Active bool `form:"active"` - MapExample map[string]string - NestedMap map[string]map[string]string - NestedArray [][]string - } - - // use a single instance of Decoder, it caches struct info - var decoder *form.Decoder - - func main() { - decoder = form.NewDecoder() - - // this simulates the results of http.Request's ParseForm() function - values := parseForm() - - var user User - - // must pass a pointer - err := decoder.Decode(&user, values) - if err != nil { - log.Panic(err) - } - - fmt.Printf("%#v\n", user) - } - - // this simulates the results of http.Request's ParseForm() function - func parseForm() url.Values { - return url.Values{ - "Name": []string{"joeybloggs"}, - "Age": []string{"3"}, - "Gender": []string{"Male"}, - "Address[0].Name": []string{"26 Here Blvd."}, - "Address[0].Phone": []string{"9(999)999-9999"}, - "Address[1].Name": []string{"26 There Blvd."}, - "Address[1].Phone": []string{"1(111)111-1111"}, - "active": []string{"true"}, - "MapExample[key]": []string{"value"}, - "NestedMap[key][key]": []string{"value"}, - "NestedArray[0][0]": []string{"value"}, - } - } - -example encoding - - package main - - import ( - "fmt" - "log" - - "github.com/go-playground/form/v4" - ) - - // Address contains address information - type Address struct { - Name string - Phone string - } - - // User contains user information - type User struct { - Name string - Age uint8 - Gender string - Address []Address - Active bool `form:"active"` - MapExample map[string]string - NestedMap map[string]map[string]string - NestedArray [][]string - } - - // use a single instance of Encoder, it caches struct info - var encoder *form.Encoder - - func main() { - encoder = form.NewEncoder() - - user := User{ - Name: "joeybloggs", - Age: 3, - Gender: "Male", - Address: []Address{ - {Name: "26 Here Blvd.", Phone: "9(999)999-9999"}, - {Name: "26 There Blvd.", Phone: "1(111)111-1111"}, - }, - Active: true, - MapExample: map[string]string{"key": "value"}, - NestedMap: map[string]map[string]string{"key": {"key": "value"}}, - NestedArray: [][]string{{"value"}}, - } - - // must pass a pointer - values, err := encoder.Encode(&user) - if err != nil { - log.Panic(err) - } - - fmt.Printf("%#v\n", values) - } - - -Registering Custom Types - -Decoder - - decoder.RegisterCustomTypeFunc(func(vals []string) (interface{}, error) { - return time.Parse("2006-01-02", vals[0]) - }, time.Time{}) - - ADDITIONAL: if a struct type is registered, the function will only be called - if a url.Value exists for the struct and not just the struct fields - eg. url.Values{"User":"Name%3Djoeybloggs"} will call the custom type function - with 'User' as the type, however url.Values{"User.Name":"joeybloggs"} will not. - -Encoder - - encoder.RegisterCustomTypeFunc(func(x interface{}) ([]string, error) { - return []string{x.(time.Time).Format("2006-01-02")}, nil - }, time.Time{}) - - -Ignoring Fields - -you can tell form to ignore fields using `-` in the tag - - type MyStruct struct { - Field string `form:"-"` - } - -Omitempty - -you can tell form to omit empty fields using `,omitempty` or `FieldName,omitempty` in the tag - - type MyStruct struct { - Field string `form:",omitempty"` - Field2 string `form:"CustomFieldName,omitempty"` - } - - -Notes - -To maximize compatibility with other systems the Encoder attempts -to avoid using array indexes in url.Values if at all possible. - - eg. - - // A struct field of - Field []string{"1", "2", "3"} - - // will be output a url.Value as - "Field": []string{"1", "2", "3"} - - and not - "Field[0]": []string{"1"} - "Field[1]": []string{"2"} - "Field[2]": []string{"3"} - - // however there are times where it is unavoidable, like with pointers - i := int(1) - Field []*string{nil, nil, &i} - - // to avoid index 1 and 2 must use index - "Field[2]": []string{"1"} - -*/ -package form |