schema

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 Load() function:

values := map[string][]string{
	"Name":  {"John"},
	"Phone": {"999-999-999"},
}
person := new(Person)
schema.Load(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.

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);

- structs;

- slices of any of the above types or maps with string keys and any of the above types;

- types with one of the above underlying types.

- a pointer to any of the above types.

Non-supported types are simply ignored.

Nested structs are scanned recursivelly and the source keys must use dotted notation for that. So for example, when filling the struct Person below:

type Phone struct {
	Label  string
	Number string
}

type Person struct {
	Name  string
	Phone Phone
}

...it will search for keys "Name", "Phone.Label" and "Phone.Number" in the source map. Dotted names are needed to avoid name clashes. 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.Label">
	<input type="text" name="Phones.Number">
	<input type="text" name="Phones.Label">
	<input type="text" name="Phones.Number">
	<input type="text" name="Phones.Label">
	<input type="text" name="Phones.Number">
</form>

Maps can only have a string as key, and use the same dotted notation. So for the struct:

type Person struct {
	Name   string
	Scores map[string]int
}

...we can define a form like:

<form>
	<input type="text" name="Name">
	<input type="text" name="Scores.Math" value="7">
	<input type="text" name="Scores.RocketScience" value="1">
	<input type="text" name="Scores.Go" value="9">
</form>

...and the resulting Scores map will be:

map[string]int{
	"Math":          7,
	"RocketScience": 1,
	"Go":            9,
}

As you see, not everybody is good at rocket science!

Index

• func AddTypeConverter(rt reflect.Type, conv TypeConv)
• func Load(i interface{}, data map[string][]string) error
• type SchemaError
  • func (e *SchemaError) Add(err error, key string, index int)
  • func (e *SchemaError) Err(key string) []error
  • func (e *SchemaError) Error() string
  • func (e *SchemaError) Errors() map[string][]error
  • func (e *SchemaError) New() string
• type TypeConv
• type ValueError
  • func (e *ValueError) Add(err error)
  • func (e *ValueError) Error() string
  • func (e *ValueError) Errors() []error

Functions

func AddTypeConverter

func AddTypeConverter(rt reflect.Type, conv TypeConv)

AddTypeConverter adds a function to perform conversions from the basic type to a more complex type.

This can be used to define properties of types that are "alias" to basic types.

    type TString string

    type TMyRec struct {
	       Prop1 TString
    }

In that case, the Load function would fail without a converter since a simple "String" cannot be set on a TString property So we write the function to perform de conversion

func ConvStringToString(v reflect.Value) reflect.Value {
		return reflect.ValueOf(TString(v.String()))
}

And register that function for later use AddTypeConverter(reflect.TypeOf(TString("")), ConvStringToTString) Then the Load function can resolve the conversion.

func Load

func Load(i interface{}, data map[string][]string) error

Load fills a struct with form values.

The first parameter must be a pointer to a struct. The second is a map, typically url.Values, http.Request.Form or http.Request.MultipartForm.

This function is capable of filling nested structs recursivelly using map keys as "paths" in dotted notation.

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

Types

type SchemaError

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

SchemaError stores global errors and validation errors for field values.

Global errors are stored using an empty string key.

func (*SchemaError) Add

func (e *SchemaError) Add(err error, key string, index int)

func (*SchemaError) Err

func (e *SchemaError) Err(key string) []error

func (*SchemaError) Error

func (e *SchemaError) Error() string

func (*SchemaError) Errors

func (e *SchemaError) Errors() map[string][]error

func (*SchemaError) New

func (e *SchemaError) New() string

type TypeConv

type TypeConv func(basic reflect.Value) reflect.Value

Converts values from one type to another.

type ValueError

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

ValueError stores errors for a single value.

The same value can be validated more than once, so it can have multiple errors.

func (*ValueError) Add

func (e *ValueError) Add(err error)

func (*ValueError) Error

func (e *ValueError) Error() string

func (*ValueError) Errors

func (e *ValueError) Errors() []error