query

Documentation

Overview

Package query implements encoding of structs into URL query parameters.

As a simple example:

type Options struct {
	Query   string `url:"q"`
	ShowAll bool   `url:"all"`
	Page    int    `url:"page"`
}

opt := Options{ "foo", true, 2 }
v, _ := query.Values(opt)
fmt.Print(v.Encode()) // will output: "q=foo&all=true&page=2"

The exact mapping between Go values and url.Values is described in the documentation for the Values() function.

Index

• func Values(v interface{}) (url.Values, error)
• type Encoder

Functions

func Values

func Values(v interface{}) (url.Values, error)

Values returns the url.Values encoding of v.

Values expects to be passed a struct, and traverses it recursively using the following encoding rules.

Each exported struct field is encoded as a URL parameter unless

• the field's tag is "-", or
• the field is empty and its tag specifies the "omitempty" option

The empty values are false, 0, any nil pointer or interface value, any array slice, map, or string of length zero, and any type (such as time.Time) that returns true for IsZero().

The URL parameter name defaults to the struct field name but can be specified in the struct field's tag value. The "url" key in the struct field's tag value is the key name, followed by an optional comma and options. For example:

// Field is ignored by this package.
Field int `url:"-"`

// Field appears as URL parameter "myName".
Field int `url:"myName"`

// Field appears as URL parameter "myName" and the field is omitted if
// its value is empty
Field int `url:"myName,omitempty"`

// Field appears as URL parameter "Field" (the default), but the field
// is skipped if empty.  Note the leading comma.
Field int `url:",omitempty"`

For encoding individual field values, the following type-dependent rules apply:

Boolean values default to encoding as the strings "true" or "false". Including the "int" option signals that the field should be encoded as the strings "1" or "0".

time.Time values default to encoding as RFC3339 timestamps. Including the "unix" option signals that the field should be encoded as a Unix time (see time.Unix()). The "unixmilli" and "unixnano" options will encode the number of milliseconds and nanoseconds, respectively, since January 1, 1970 (see time.UnixNano()). Including the "layout" struct tag (separate from the "url" tag) will use the value of the "layout" tag as a layout passed to time.Format. For example:

// Encode a time.Time as YYYY-MM-DD
Field time.Time `layout:"2006-01-02"`

Slice and Array values default to encoding as multiple URL values of the same name. Including the "comma" option signals that the field should be encoded as a single comma-delimited value. Including the "space" option similarly encodes the value as a single space-delimited string. Including the "semicolon" option will encode the value as a semicolon-delimited string. Including the "brackets" option signals that the multiple URL values should have "[]" appended to the value name. "numbered" will append a number to the end of each incidence of the value name, example: name0=value0&name1=value1, etc. Including the "del" struct tag (separate from the "url" tag) will use the value of the "del" tag as the delimiter. For example:

// Encode a slice of bools as ints ("1" for true, "0" for false),
// separated by exclamation points "!".
Field []bool `url:",int" del:"!"`

Anonymous struct fields are usually encoded as if their inner exported fields were fields in the outer struct, subject to the standard Go visibility rules. An anonymous struct field with a name given in its URL tag is treated as having that name, rather than being anonymous.

Non-nil pointer values are encoded as the value pointed to.

Nested structs are encoded including parent fields in value names for scoping. e.g:

"user[name]=acme&user[addr][postcode]=1234&user[addr][city]=SFO"

All other values are encoded using their default string representation.

Multiple fields that encode to the same URL parameter name will be included as multiple URL values of the same name.

Types

type Encoder

type Encoder interface {
	EncodeValues(key string, v *url.Values) error
}

Encoder is an interface implemented by any type that wishes to encode itself into URL values in a non-standard way.