package reverse
import "github.com/gorilla/reverse"
Installation | Overview | API | Files
Installation
$ go get github.com/gorilla/reverse
Overview
Package gorilla/reverse is a set of utilities to create request routers.
If provides interfaces to match and extract variables from an HTTP request and build URLs for registered routes. It also has a variety of matcher implementations for all kinds of request attributes, among other utilities.
For example, the Regexp type produces reversible regular expressions that can be used to generate URLs for a regexp-based mux. To demonstrate, let's compile a simple regexp:
regexp, err := reverse.CompileRegexp(`/foo/1(\d+)3`)
Now we can call regexp.Revert() passing variables to fill the capturing groups. Because our variable is not named, we use an empty string as key for url.Values, like this:
// url is "/foo/123".
url, err := regexp.Revert(url.Values{"": {"2"}})
Non-capturing groups are ignored, but named capturing groups can be filled normally. Just set the key in url.Values:
regexp, err := reverse.CompileRegexp(`/foo/1(?P<two>\d+)3`)
if err != nil {
panic(err)
}
// url is "/foo/123".
url, err := re.Revert(url.Values{"two": {"2"}})
There are a few limitations that can't be changed:
1. Nested capturing groups are ignored; only the outermost groups become a placeholder. So in `1(\d+([a-z]+))3` there is only one placeholder although there are two capturing groups: re.Revert(url.Values{"": {"2", "a"}}) results in "123" and not "12a3".
2. Literals inside capturing groups are ignored; the whole group becomes a placeholder.
API
Package Files
type All
type All []Matcher
All is a set of matchers, and all of them must match.
func NewAll
func NewAll(matchers []Matcher) All
NewAll returns a group of matchers that succeeds only if all of them match.
func (All) Match
func (m All) Match(r *http.Request) bool
type Builder
type Builder interface {
Build(*url.URL, url.Values) error
}Builder builds a URL based on positional and/or named variables.
type Extractor
type Extractor interface {
Extract(*Result, *http.Request)
}Extractor extracts variables from a request.
type Func
type Func func(*http.Request) bool
Func is a function signature for custom matchers.
func (Func) Match
func (m Func) Match(r *http.Request) bool
type GorillaHost
type GorillaHost struct {
Regexp
}GorillaHost matches a URL host using Gorilla's special syntax for named groups: `{name:regexp}`.
func NewGorillaHost
func NewGorillaHost(pattern string) (*GorillaHost, error)
func (*GorillaHost) Build
func (m *GorillaHost) Build(u *url.URL, values url.Values) error
Build builds the URL host using the given positional and named variables, and writes it to the given URL.
func (*GorillaHost) Extract
func (m *GorillaHost) Extract(result *Result, r *http.Request)
Extract returns positional and named variables extracted from the URL host.
func (*GorillaHost) Match
func (m *GorillaHost) Match(r *http.Request) bool
type GorillaPath
type GorillaPath struct {
Regexp
// contains filtered or unexported fields
}GorillaPath matches a URL path using Gorilla's special syntax for named groups: `{name:regexp}`.
func NewGorillaPath
func NewGorillaPath(pattern string, strictSlash bool) (*GorillaPath, error)
func (*GorillaPath) Build
func (m *GorillaPath) Build(u *url.URL, values url.Values) error
Build builds the URL path using the given positional and named variables, and writes it to the given URL.
func (*GorillaPath) Extract
func (m *GorillaPath) Extract(result *Result, r *http.Request)
Extract returns positional and named variables extracted from the URL path.
func (*GorillaPath) Match
func (m *GorillaPath) Match(r *http.Request) bool
type GorillaPathPrefix
type GorillaPathPrefix struct {
Regexp
}GorillaPathPrefix matches a URL path prefix using Gorilla's special syntax for named groups: `{name:regexp}`.
func NewGorillaPathPrefix
func NewGorillaPathPrefix(pattern string) (*GorillaPathPrefix, error)
func (*GorillaPathPrefix) Build
func (m *GorillaPathPrefix) Build(u *url.URL, values url.Values) error
Build builds the URL path using the given positional and named variables, and writes it to the given URL.
func (*GorillaPathPrefix) Extract
func (m *GorillaPathPrefix) Extract(result *Result, r *http.Request)
Extract returns positional and named variables extracted from the URL path.
func (*GorillaPathPrefix) Match
func (m *GorillaPathPrefix) Match(r *http.Request) bool
type Header
type Header map[string]string
Header matches request headers. All values, if non-empty, must match. Empty values only check if the header is present.
func NewHeader
func NewHeader(m map[string]string) Header
NewHeader returns a header matcher, converting keys to the canonical form.
func (Header) Match
func (m Header) Match(r *http.Request) bool
type Host
type Host string
Host matches a static URL host.
func NewHost
func NewHost(host string) Host
NewHost returns a static URL host matcher.
func (Host) Match
func (m Host) Match(r *http.Request) bool
type Matcher
type Matcher interface {
Match(*http.Request) bool
}Matcher matches a request.
type Method
type Method []string
Method matches the request method. One of the values must match.
func NewMethod
func NewMethod(m []string) Method
NewMethod retuns a request method matcher, converting values to upper-case.
func (Method) Match
func (m Method) Match(r *http.Request) bool
type None
type None bool
None never matches.
func NewNone
func NewNone() *None
NewNone returns a matcher that never matches.
func (*None) Match
func (m *None) Match(r *http.Request) bool
type One
type One []Matcher
One is a set of matchers, and at least one of them must match.
func NewOne
func NewOne(matchers []Matcher) One
NewOne returns a group of matchers that succeeds if one of them matches.
func (One) Match
func (m One) Match(r *http.Request) bool
type Path
type Path string
Path matches a static URL path.
func NewPath
func NewPath(path string) Path
NewPath returns a static URL path matcher.
func (Path) Match
func (m Path) Match(r *http.Request) bool
type PathPrefix
type PathPrefix string
PathPrefix matches a static URL path prefix.
func NewPathPrefix
func NewPathPrefix(prefix string) PathPrefix
NewPathPrefix returns a static URL path prefix matcher.
func (PathPrefix) Match
func (m PathPrefix) Match(r *http.Request) bool
type PathRedirect
type PathRedirect string
PathRedirect matches a static URL path and redirects to the trailing-slash or non-trailing-slash version if it differs.
func NewPathRedirect
func NewPathRedirect(path string) PathRedirect
NewPathRedirect returns a static URL path matcher that redirects if the trailing slash differs.
func (PathRedirect) Extract
func (m PathRedirect) Extract(result *Result, r *http.Request)
func (PathRedirect) Match
func (m PathRedirect) Match(r *http.Request) bool
type Query
type Query map[string]string
Query matches URL queries. All values, if non-empty, must match. Empty values only check if the query is present.
func NewQuery
func NewQuery(m map[string]string) Query
NewQuery returns a URL query matcher.
func (Query) Match
func (m Query) Match(r *http.Request) bool
type Regexp
type Regexp struct {
// contains filtered or unexported fields
}Regexp stores a regular expression that can be "reverted" or "built": outermost capturing groups become placeholders to be filled by variables.
func CompileRegexp
func CompileRegexp(pattern string) (*Regexp, error)
CompileRegexp compiles a regular expression pattern and creates a template to revert it.
func (*Regexp) Compiled
func (r *Regexp) Compiled() *regexp.Regexp
Compiled returns the compiled regular expression to be used for matching.
func (*Regexp) Groups
func (r *Regexp) Groups() []string
Groups returns an ordered list of the outermost capturing groups found in the regexp.
Positional groups are listed as an empty string and named groups use the group name.
func (*Regexp) Indices
func (r *Regexp) Indices() []int
Indices returns the indices of the outermost capturing groups found in the regexp.
Not all indices may be present because nested capturing groups are ignored.
func (*Regexp) MatchString
func (r *Regexp) MatchString(s string) bool
Match returns whether the regexp matches the given string.
func (*Regexp) Revert
func (r *Regexp) Revert(values url.Values) (string, error)
Revert builds a string for this regexp using the given values. Positional values use an empty string as key.
The values are modified in place, and only the unused ones are left.
func (*Regexp) RevertValid
func (r *Regexp) RevertValid(values url.Values) (string, error)
RevertValid is the same as Revert but it also validates the resulting string matching it against the compiled regexp.
The values are modified in place, and only the unused ones are left.
func (*Regexp) Template
func (r *Regexp) Template() string
Template returns the reverse template for the regexp, in fmt syntax.
func (*Regexp) Values
func (r *Regexp) Values(s string) url.Values
Values matches the regexp and returns the results for positional and named groups. Positional values are stored using an empty string as key. If the string doesn't match it returns nil.
type RegexpHost
type RegexpHost struct {
Regexp
}RegexpHost matches the URL host against a regular expression. The outermost capturing groups are extracted and the host can be reverted.
func NewRegexpHost
func NewRegexpHost(pattern string) (*RegexpHost, error)
NewRegexpHost returns a regexp matcher for the given URL host pattern.
func (*RegexpHost) Build
func (m *RegexpHost) Build(u *url.URL, values url.Values) error
Build builds the URL host using the given positional and named variables, and writes it to the given URL.
func (*RegexpHost) Extract
func (m *RegexpHost) Extract(result *Result, r *http.Request)
Extract returns positional and named variables extracted from the URL host.
func (*RegexpHost) Match
func (m *RegexpHost) Match(r *http.Request) bool
type RegexpPath
type RegexpPath struct {
Regexp
}RegexpPath matches the URL path against a regular expression. The outermost capturing groups are extracted and the path can be reverted.
func NewRegexpPath
func NewRegexpPath(pattern string) (*RegexpPath, error)
NewRegexpPath returns a regexp matcher for the given URL path pattern.
func (*RegexpPath) Build
func (m *RegexpPath) Build(u *url.URL, values url.Values) error
Build builds the URL path using the given positional and named variables, and writes it to the given URL.
func (*RegexpPath) Extract
func (m *RegexpPath) Extract(result *Result, r *http.Request)
Extract returns positional and named variables extracted from the URL path.
func (*RegexpPath) Match
func (m *RegexpPath) Match(r *http.Request) bool
type Result
type Result struct {
Handler http.Handler
Values url.Values
}Result stores the results from a match.
type Scheme
type Scheme []string
Scheme matches the URL scheme. One of the values must match.
func NewScheme
func NewScheme(m []string) Scheme
NewScheme retuns a URL scheme matcher, converting values to lower-case.
func (Scheme) Match
func (m Scheme) Match(r *http.Request) bool