muhfaris / schema

schema

The Gorilla project has been archived, and is no longer under active maintainenance. You can read more here: https://github.com/gorilla#gorilla-toolkit

---

Package gorilla/schema converts structs to and from form values.

Example

Here's a quick example: we parse POST form values and then decode them into a struct:

// Set a Decoder instance as a package global, because it caches
// meta-data about structs, and an instance can be shared safely.
var decoder = schema.NewDecoder()

type Person struct {
    Name  string
    Phone string
}

func MyHandler(w http.ResponseWriter, r *http.Request) {
    err := r.ParseForm()
    if err != nil {
        // Handle error
    }

    var person Person

    // r.PostForm is a map of our POST form values
    err = decoder.Decode(&person, r.PostForm)
    if err != nil {
        // Handle error
    }

    // Do something with person.Name or person.Phone
}

Or parse GET from query

// Set a Decoder instance as a package global, because it caches
// meta-data about structs, and an instance can be shared safely.
var decoder = schema.NewDecoder()

type Person struct {
    Name  string `schema:"name"`
    Phone string `schema:"phone"`
}

func GetMyHandler(w http.ResponseWriter, r *http.Request) {
    var person Person

    err = decoder.Decode(&person, r.URL.Query())
    if err != nil {
        // Handle error
    }

    // Do something with person.Name or person.Phone
}

// curl http://localhost/get-my-handler?name=muhfaris&phone=0812345678

Conversely, contents of a struct can be encoded into form values. Here's a variant of the previous example using the Encoder:

var encoder = schema.NewEncoder()

func MyHttpRequest() {
    person := Person{"Jane Doe", "555-5555"}
    form := url.Values{}

    err := encoder.Encode(person, form)

    if err != nil {
        // Handle error
    }

    // Use form values, for example, with an http client
    client := new(http.Client)
    res, err := client.PostForm("http://my-api.test", form)
}

To define custom names for fields, use a struct tag "schema". To not populate certain fields, use a dash for the name and it will be ignored:

type Person struct {
    Name  string `schema:"name,required"`  // custom name, must be supplied
    Phone string `schema:"phone"`          // custom name
    Admin bool   `schema:"-"`              // this field is never set
}

The supported field types in the struct are:

• bool
• float variants (float32, float64)
• int variants (int, int8, int16, int32, int64)
• string
• uint variants (uint, uint8, uint16, uint32, uint64)
• struct
• a pointer to one of the above types
• a slice or a pointer to a slice of one of the above types

Unsupported types are simply ignored, however custom types can be registered to be converted.

Register a Custom Converter

Below the sample, a custom converter parses array data into an array string.

You have requested /search?roles=user,admin,manager, the expectation the query will be parsed into []string.

type User struct {
    Roles []string `schema: "roles"`
}

var user User

decoder.RegisterConverter([]string{}, func(input string) reflect.Value {
	return reflect.ValueOf(strings.Split(input, ","))
})

if err := decoder.Decode(&user, r.URL().Quer()); err != nil {
    // do something
}

License

BSD licensed. See the LICENSE file for details.