schema

package module
v1.4.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jun 29, 2024 License: BSD-3-Clause Imports: 7 Imported by: 2,572

README

gorilla/schema

testing codecov godoc sourcegraph

Gorilla Logo

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
}

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.

Setting Defaults

It is possible to set default values when encoding/decoding by using the default tag option. The value of default is applied when a field has a zero value, a pointer has a nil value, or a slice is empty.

type Person struct {
    Phone string `schema:"phone,default:+123456"`          // custom name
    Age int     `schema:"age,default:21"`
	Admin bool    `schema:"admin,default:false"`
	Balance float64 `schema:"balance,default:10.0"`
    Friends []string `schema:friends,default:john|bob`
}

The default tag option is supported for the following types:

  • bool
  • float variants (float32, float64)
  • int variants (int, int8, int16, int32, int64)
  • uint variants (uint, uint8, uint16, uint32, uint64)
  • string
  • a slice of the above types. As shown in the example above, | should be used to separate between slice items.
  • a pointer to one of the above types (pointer to slice and slice of pointers are not supported).

[!NOTE]
Because primitive types like int, float, bool, unint and their variants have their default (or zero) values set by Golang, it is not possible to distinguish them from a provided value when decoding/encoding form values. In this case, the value provided by the default option tag will be always applied. For example, let's assume that the value submitted in the form for balance is 0.0 then the default of 10.0 will be applied, even if 0.0 is part of the form data for the balance field. In such cases, it is highly recommended to use pointers to allow schema to distinguish between when a form field has no provided value and when a form has a value equal to the corresponding default set by Golang for a particular type. If the type of the Balance field above is changed to *float64, then the zero value would be nil. In this case, if the form data value for balance is 0.0, then the default will not be applied.

License

BSD licensed. See the LICENSE file for details.

Documentation

Overview

Package gorilla/schema fills a struct with form values.

The basic usage is really simple. Given this struct:

type Person struct {
	Name  string
	Phone string
}

...we can fill it passing a map to the Decode() function:

values := map[string][]string{
	"Name":  {"John"},
	"Phone": {"999-999-999"},
}
person := new(Person)
decoder := schema.NewDecoder()
decoder.Decode(person, values)

This is just a simple example and it doesn't make a lot of sense to create the map manually. Typically it will come from a http.Request object and will be of type url.Values, http.Request.Form, or http.Request.MultipartForm:

func MyHandler(w http.ResponseWriter, r *http.Request) {
	err := r.ParseForm()

	if err != nil {
		// Handle error
	}

	decoder := schema.NewDecoder()
	// 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
}

Note: it is a good idea to 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()

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"`  // custom name
	Phone string `schema:"phone"` // custom name
	Admin bool   `schema:"-"`     // this field is never set
}

The supported field types in the destination 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

Non-supported types are simply ignored, however custom types can be registered to be converted.

To fill nested structs, keys must use a dotted notation as the "path" for the field. So for example, to fill the struct Person below:

type Phone struct {
	Label  string
	Number string
}

type Person struct {
	Name  string
	Phone Phone
}

...the source map must have the keys "Name", "Phone.Label" and "Phone.Number". This means that an HTML form to fill a Person struct must look like this:

<form>
	<input type="text" name="Name">
	<input type="text" name="Phone.Label">
	<input type="text" name="Phone.Number">
</form>

Single values are filled using the first value for a key from the source map. Slices are filled using all values for a key from the source map. So to fill a Person with multiple Phone values, like:

type Person struct {
	Name   string
	Phones []Phone
}

...an HTML form that accepts three Phone values would look like this:

<form>
	<input type="text" name="Name">
	<input type="text" name="Phones.0.Label">
	<input type="text" name="Phones.0.Number">
	<input type="text" name="Phones.1.Label">
	<input type="text" name="Phones.1.Number">
	<input type="text" name="Phones.2.Label">
	<input type="text" name="Phones.2.Number">
</form>

Notice that only for slices of structs the slice index is required. This is needed for disambiguation: if the nested struct also had a slice field, we could not translate multiple values to it if we did not use an index for the parent struct.

There's also the possibility to create a custom type that implements the TextUnmarshaler interface, and in this case there's no need to register a converter, like:

type Person struct {
  Emails []Email
}

type Email struct {
  *mail.Address
}

func (e *Email) UnmarshalText(text []byte) (err error) {
	e.Address, err = mail.ParseAddress(string(text))
	return
}

...an HTML form that accepts three Email values would look like this:

<form>
	<input type="email" name="Emails.0">
	<input type="email" name="Emails.1">
	<input type="email" name="Emails.2">
</form>

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type ConversionError

type ConversionError struct {
	Key   string       // key from the source map.
	Type  reflect.Type // expected type of elem
	Index int          // index for multi-value fields; -1 for single-value fields.
	Err   error        // low-level error (when it exists)
}

ConversionError stores information about a failed conversion.

func (ConversionError) Error

func (e ConversionError) Error() string

type Converter

type Converter func(string) reflect.Value

type Decoder

type Decoder struct {
	// contains filtered or unexported fields
}

Decoder decodes values from a map[string][]string to a struct.

func NewDecoder

func NewDecoder() *Decoder

NewDecoder returns a new Decoder.

func (*Decoder) Decode

func (d *Decoder) Decode(dst interface{}, src map[string][]string) error

Decode decodes a map[string][]string to a struct.

The first parameter must be a pointer to a struct.

The second parameter is a map, typically url.Values from an HTTP request. Keys are "paths" in dotted notation to the struct fields and nested structs.

See the package documentation for a full explanation of the mechanics.

func (*Decoder) IgnoreUnknownKeys

func (d *Decoder) IgnoreUnknownKeys(i bool)

IgnoreUnknownKeys controls the behaviour when the decoder encounters unknown keys in the map. If i is true and an unknown field is encountered, it is ignored. This is similar to how unknown keys are handled by encoding/json. If i is false then Decode will return an error. Note that any valid keys will still be decoded in to the target struct.

To preserve backwards compatibility, the default value is false.

func (*Decoder) MaxSize added in v1.4.1

func (d *Decoder) MaxSize(size int)

MaxSize limits the size of slices for URL nested arrays or object arrays. Choose MaxSize carefully; large values may create many zero-value slice elements. Example: "items.100000=apple" would create a slice with 100,000 empty strings.

func (*Decoder) RegisterConverter

func (d *Decoder) RegisterConverter(value interface{}, converterFunc Converter)

RegisterConverter registers a converter function for a custom type.

func (*Decoder) SetAliasTag

func (d *Decoder) SetAliasTag(tag string)

SetAliasTag changes the tag used to locate custom field aliases. The default tag is "schema".

func (*Decoder) ZeroEmpty

func (d *Decoder) ZeroEmpty(z bool)

ZeroEmpty controls the behaviour when the decoder encounters empty values in a map. If z is true and a key in the map has the empty string as a value then the corresponding struct field is set to the zero value. If z is false then empty strings are ignored.

The default value is false, that is empty values do not change the value of the struct field.

type EmptyFieldError added in v1.1.0

type EmptyFieldError struct {
	Key string // required key in the source map.
}

EmptyFieldError stores information about an empty required field.

func (EmptyFieldError) Error added in v1.1.0

func (e EmptyFieldError) Error() string

type Encoder

type Encoder struct {
	// contains filtered or unexported fields
}

Encoder encodes values from a struct into url.Values.

func NewEncoder

func NewEncoder() *Encoder

NewEncoder returns a new Encoder with defaults.

func (*Encoder) Encode

func (e *Encoder) Encode(src interface{}, dst map[string][]string) error

Encode encodes a struct into map[string][]string.

Intended for use with url.Values.

func (*Encoder) RegisterEncoder

func (e *Encoder) RegisterEncoder(value interface{}, encoder func(reflect.Value) string)

RegisterEncoder registers a converter for encoding a custom type.

func (*Encoder) SetAliasTag

func (e *Encoder) SetAliasTag(tag string)

SetAliasTag changes the tag used to locate custom field aliases. The default tag is "schema".

type MultiError

type MultiError map[string]error

MultiError stores multiple decoding errors.

Borrowed from the App Engine SDK.

func (MultiError) Error

func (e MultiError) Error() string

type UnknownKeyError added in v1.1.0

type UnknownKeyError struct {
	Key string // key from the source map.
}

UnknownKeyError stores information about an unknown key in the source map.

func (UnknownKeyError) Error added in v1.1.0

func (e UnknownKeyError) Error() string

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL