opts

func BuildQueryString ¶

func BuildQueryString(opts any) (url.Values, error)

BuildQueryString is a function to be used by request methods with opts structs. It's inspired by gophercloud.BuildQueryString with partially stricter behavior. It accepts a tagged structure and expands it into a URL struct. Field names are converted into query parameters based on a "q" tag. For example:

type Something struct {
   Bar string `q:"x_bar"`
   Baz int    `q:"lorem_ipsum"`
}
instance := Something{
   Bar: "AAA",
   Baz: 1,
}

will be converted into

?x_bar=AAA&lorem_ipsum=1

On configuration errors (e.g. non-struct opts, opts with non-q-tagged fields) the function panics. On user errors (e.g. missing required field) an error is returned. On success, url.Values are returned according to the opts.

This function understands and expects the same values for the "q" tag as opts.ParseQueryString. See documentation over there for details.

func ParseQueryString ¶

func ParseQueryString[T any](query url.Values) (T, error)

ParseQueryString parses the query parameters of url.Values into an opt struct. Fields are mapped by their "q" tag, mirroring the behavior of opts.BuildQueryString. For example:

type Something struct {
   Bar string `q:"x_bar"`
   Baz int    `q:"lorem_ipsum"`
}

and a request with the query string

?x_bar=AAA&lorem_ipsum=1

will produce

result := Something{
   Bar: "AAA",
   Baz: 1,
}

On configuration errors (e.g. non-struct opts, opts with non-q-tagged fields) the function panics. On user errors (unknown query parameter, type conversion failure, missing required field) an error is returned. On success, the returned opts are populated according to the http.Request.

The parser supports all scalars except complex. Additionally, it allows Slices (for multiple values), option.Option (recommended for optional values) and pointers (as alternative to option.Option) of these. Maps are supported when the key and value types are supported. Only selected structs work (embedded structs and time.Time). Some inputs might work but are untested.

Slice fields use repeated query parameters:

Foo []string `q:"foo"`                       // ?foo=a&foo=b

Map fields accept plain repeated key:value pairs:

Bar map[string]string `q:"bar"`              // ?bar=k1:v1&bar=k2:v2

time.Time fields support the formats RFC3339Nano, RFC3339, DateTime, DateOnly, Unix (seconds since epoch). A single "format" option must be set, to limit what the parser accepts:

Baz time.Time `q:"baz,format:RFC3339"`       // ?baz=1999-01-01T00:00:00

A "required" option can be set to define that a missing value will produce an error.

Quux string `q:"quux,required"`               // ?foo=bar --> error

Bool fields can use a "value" option to participate in value-discriminant parsing. Multiple bool fields sharing the same key each declare a specific value they match. When the query contains that value for the key, the corresponding bool is set to true:

WithDetails       bool `q:"with,value:details"`
WithSubresources  bool `q:"with,value:subresources"`
WithSubcapacities bool `q:"with,value:subcapacities"`

Given the query string ?with=details&with=subcapacities, WithDetails and WithSubcapacities will be true while WithSubresources remains false.