Documentation
¶
Overview ¶
Package builders provides builders for HTTP requests and forms.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func NewRequest ¶
func NewRequest( ctx context.Context, c Header, method, url string, setters ...RequestOption, ) (*http.Request, error)
NewRequest creates a new request.
func Values ¶ added in v0.9.4
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 have their fields processed recursively and are encoded including parent fields in value names for scoping. For example,
"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 ¶ added in v0.9.4
Encoder is an interface implemented by any type that wishes to encode itself into URL values in a non-standard way.
type FormBuilder ¶
type FormBuilder interface {
io.Closer
CreateFormFile(fieldname string, file *os.File) error
CreateFormFileReader(fieldname string, r io.Reader, filename string) error
WriteField(fieldname, value string) error
FormDataContentType() string
}
FormBuilder is an interface for building forms.
func NewFormBuilder ¶
func NewFormBuilder(body io.Writer) FormBuilder
NewFormBuilder creates a new DefaultFormBuilder.
type Querier ¶ added in v0.9.4
Querier is an interface for a request querier.
It allows for modifying the URL before it is sent.
type RequestBuilder ¶
type RequestBuilder interface {
Build(
ctx context.Context,
method, url string,
body any,
header http.Header,
) (*http.Request, error)
}
RequestBuilder is an interface for building requests.
func NewRequestBuilder ¶
func NewRequestBuilder() RequestBuilder
NewRequestBuilder creates a new default request builder.
type RequestOption ¶
type RequestOption func(*requestOptions)
RequestOption is an option for a request.
func WithContentType ¶
func WithContentType(contentType string) RequestOption
WithContentType sets the content type for a request.
func WithQuerier ¶ added in v0.9.4
func WithQuerier(querier Querier) RequestOption
WithQuerier sets the querier for a request.
type URLComputer ¶ added in v0.9.4
type URLComputer interface {
ComputeURLs()
}
URLComputer computes URLs for a given client.
Source Files