bind

README

bind is a library for binding HTTP request parameters to Go objects.

See the godoc

Documentation

Overview

Package bind converts between form encoding and Go values.

It comes with binders for all values, time.Time, arbitrary structs, and slices. In particular, binding functions are provided for the following types:

• bool
• float32, float64
• int, int8, int16, int32, int64
• uint, uint8, uint16, uint32, uint64
• string
• struct
• a pointer to any supported type
• a slice of any supported type
• time.Time
• uploaded files (as io.Reader, io.ReadSeeker, *os.File, []byte, *multipart.FileHeader)

Callers may also hook into the process and provide a custom binding function.

Example

This example binds data from embedded URL arguments, the query string, and a posted form.

POST /accounts/:accountId/users/?op=UPDATE

<form>
 <input name="user.Id">
 <input name="user.Name">
 <input name="user.Phones[0].Label">
 <input name="user.Phones[0].Number">
 <input name="user.Phones[1].Label">
 <input name="user.Phones[1].Number">
 <input name="user.Labels[]">
 <input name="user.Labels[]">
</form>

type Phone struct { Label, Number string }
type User struct {
  Id     uint32
  Phones []Phone
  Labels []string
}

var (
  params = mux.Vars(req) // embedded URL args
  id     uint32
  op     string
  user   User
)
handleErrors(
  bind.Map(params).Field(&id, "accountId"),
  bind.Request(req).Field(&op, "op")
  bind.Request(req).Field(&user, "user"),
)

Booleans

Booleans are converted to Go by comparing against the following strings:

TRUE: "true", "1",  "on"
FALSE: "false", "0", ""

The "on" / "" syntax is supported as the default behavior for HTML checkboxes.

Date Time

The SQL standard time formats [“2006-01-02”, “2006-01-02 15:04”] are recognized by the default datetime binder.

More may be added by the application to the TimeFormats variable, like this:

 func init() {
	 bind.TimeFormats = append(bind.TimeFormats, "01/02/2006")
 }

File Uploads

File uploads may be bound to any of the following types:

• *os.File
• []byte
• io.Reader
• io.ReadSeeker
• *multipart.FileHeader

This is a wrapper around the upload handling provided by Go’s multipart package. The bytes stay in memory unless they exceed a threshold (10MB by default), in which case they are written to a temp file.

Note: Binding a file upload to os.File requires it to be written to a temp file (if it wasn’t already), making it less efficient than the other types.

Slices

Both indexed and unindexed slices are supported.

These two forms are bound as unordered slices:

<form>
 <input name="ids">
 <input name="ids">
 <input name="ids">
</form>

<form>
 <input name="ids[]">
 <input name="ids[]">
 <input name="ids[]">
</form>

This is bound as an ordered slice:

<form>
 <input name="ids[0]">
 <input name="ids[1]">
 <input name="ids[2]">
</form>

The two forms may be combined, with unindexed elements filling any gaps between indexed elements.

<form>
 <input name="ids[]">
 <input name="ids[]">
 <input name="ids[5]">
</form>

Note that if the slice element is a struct, it must use the indexed notation.

Structs

Structs are bound using a dot notation. For example:

<form>
 <input name="user.Name">
 <input name="user.Phones[0].Label">
 <input name="user.Phones[0].Number">
 <input name="user.Phones[1].Label">
 <input name="user.Phones[1].Number">
</form>

Struct fields must be exported to be bound.

Additionally, all params may be bound as members of a struct, rather than extracting a single field.

<form>
 <input name="Name">
 <input name="Phones[0].Label">
 <input name="Phones[0].Number">
 <input name="Phones[1].Label">
 <input name="Phones[1].Number">
</form>

var user User
err := bind.Request(req).All(&user)

Index

• Variables
• type Binder
  • func Map(m map[string]string) Binder
  • func Request(req *http.Request) Binder
  • func Values(params map[string][]string) Binder
  • func (b Binder) All(dst interface{}) (err error)
  • func (b Binder) Field(dst interface{}, name string) (err error)
• type Error
  • func (err Error) Error() string
• type Func

Variables

var (
	// KindBinders is a lookup from the kind of a type to the bind.Func that binds
	// it. It is less specific than the TypeBinders and used as a fallback.
	KindBinders map[reflect.Kind]Func

	// TypeBinders is a lookup from a specific type to the bind.Func that binds it.
	// Applications may add custom binders to this map to override the default behavior.
	TypeBinders map[reflect.Type]Func

	// TimeFormats are the time layout strings used to attempt to parse data into a time.Time.
	// They are attempted in order.
	TimeFormats = []string{"2006-01-02 15:04", "2006-01-02"}
)

Types

type Binder

type Binder struct {
	Values map[string][]string
	Files  map[string][]*multipart.FileHeader
}

Binder handles binding of parameter maps to Go data structures.

func Map

func Map(m map[string]string) Binder

Map returns a binder for the given parameter map

func Request

func Request(req *http.Request) Binder

Request returns a binder initialized with the request's form and query string data (including multipart forms).

func Values

func Values(params map[string][]string) Binder

Values returns a binder for the given query parameter map

func (Binder) All

func (b Binder) All(dst interface{}) (err error)

All unpacks the entire set of form data into the given struct.

func (Binder) Field

func (b Binder) Field(dst interface{}, name string) (err error)

Field binds the given destination to a field of the given name from one or more values in this binder. The destination must be a pointer. Returns an error of type bind.Error upon any sort of failure.

type Error

type Error struct {
	Field   string
	Message string
}

func (Error) Error

func (err Error) Error() string

type Func

type Func func(b Binder, name string, dst reflect.Value) error

Func is a binding function that is responsible for extracting and converting the relevant parameters from the binder and writing the result to the given destination.