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.

It 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 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