summaryrefslogtreecommitdiff
path: root/vendor/github.com/go-playground/form/v4/doc.go
diff options
context:
space:
mode:
authorLibravatar Terin Stock <terinjokes@gmail.com>2025-03-09 17:47:56 +0100
committerLibravatar Terin Stock <terinjokes@gmail.com>2025-03-10 01:59:49 +0100
commit3ac1ee16f377d31a0fb80c8dae28b6239ac4229e (patch)
treef61faa581feaaeaba2542b9f2b8234a590684413 /vendor/github.com/go-playground/form/v4/doc.go
parent[chore] update URLs to forked source (diff)
downloadgotosocial-3ac1ee16f377d31a0fb80c8dae28b6239ac4229e.tar.xz
[chore] remove vendor
Diffstat (limited to 'vendor/github.com/go-playground/form/v4/doc.go')
-rw-r--r--vendor/github.com/go-playground/form/v4/doc.go275
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