pat

Documentation

Overview

Package pat is a URL-matching domain-specific language for Goji.

Quick Reference

The following table gives an overview of the language this package accepts. See the subsequent sections for a more detailed explanation of what each pattern does.

Pattern			Matches			Does Not Match

/			/			/hello

/hello			/hello			/hi
						/hello/

/user/:name		/user/carl		/user/carl/photos
			/user/alice		/user/carl/
						/user/

/:file.:ext		/data.json		/.json
			/info.txt		/data.
			/data.tar.gz		/data.json/download

/user/*			/user/			/user
			/user/carl
			/user/carl/photos

Static Paths

Most URL paths may be specified directly: the pattern "/hello" matches URLs with precisely that path ("/hello/", for instance, is treated as distinct).

Note that this package operates on raw (i.e., escaped) paths (see the documentation for net/url.URL.EscapedPath). In order to match a character that can appear escaped in a URL path, use its percent-encoded form.

Named Matches

Named matches allow URL paths to contain any value in a particular path segment. Such matches are denoted by a leading ":", for example ":name" in the rule "/user/:name", and permit any non-empty value in that position. For instance, in the previous "/user/:name" example, the path "/user/carl" is matched, while "/user/" or "/user/carl/" (note the trailing slash) are not matched. Pat rules can contain any number of named matches.

Named matches set URL variables by comparing pattern names to the segments they matched. In our "/user/:name" example, a request for "/user/carl" would bind the "name" variable to the value "carl". Use the Param function to extract these variables from the request context. Variable names in a single pattern must be unique.

Matches are ordinarily delimited by slashes ("/"), but several other characters are accepted as delimiters (with slightly different semantics): the period ("."), semicolon (";"), and comma (",") characters. For instance, given the pattern "/:file.:ext", the request "/data.json" would match, binding "file" to "data" and "ext" to "json". Note that these special characters are treated slightly differently than slashes: the above pattern also matches the path "/data.tar.gz", with "ext" getting set to "tar.gz"; and the pattern "/:file" matches names with dots in them (like "data.json").

Prefix Matches

Pat can also match prefixes of routes using wildcards. Prefix wildcard routes end with "/*", and match just the path segments preceding the asterisk. For instance, the pattern "/user/*" will match "/user/" and "/user/carl/photos" but not "/user" (note the lack of a trailing slash).

The unmatched suffix, including the leading slash ("/"), are placed into the request context, which allows subsequent routing (e.g., a subrouter) to continue from where this pattern left off. For instance, in the "/user/*" pattern from above, a request for "/user/carl/photos" will consume the "/user" prefix, leaving the path "/carl/photos" for subsequent patterns to handle. A subrouter pattern for "/:name/photos" would match this remaining path segment, for instance.

Index

• func Param(r *http.Request, name string) string
• type Pattern
  • func Delete(pat string) *Pattern
  • func Get(pat string) *Pattern
  • func Head(pat string) *Pattern
  • func New(pat string) *Pattern
  • func NewWithMethods(pat string, methods ...string) *Pattern
  • func Options(pat string) *Pattern
  • func Patch(pat string) *Pattern
  • func Post(pat string) *Pattern
  • func Put(pat string) *Pattern
  • func (p *Pattern) HTTPMethods() map[string]struct{}
  • func (p *Pattern) Match(r *http.Request) *http.Request
  • func (p *Pattern) PathPrefix() string
  • func (p *Pattern) String() string

Functions

func Param

func Param(r *http.Request, name string) string

Param returns the bound parameter with the given name. For instance, given the route:

/user/:name

and the URL Path:

/user/carl

a call to Param(r, "name") would return the string "carl". It is the caller's responsibility to ensure that the variable has been bound. Attempts to access variables that have not been set (or which have been invalidly set) are considered programmer errors and will trigger a panic.

Types

type Pattern

type Pattern struct {
	// contains filtered or unexported fields
}

Pattern implements goji.Pattern using a path-matching domain specific language. See the package documentation for more information about the semantics of this object.

func Delete

func Delete(pat string) *Pattern

Delete returns a Pat route that only matches the DELETE HTTP method.

func Get

func Get(pat string) *Pattern

Get returns a Pat route that only matches the GET and HEAD HTTP method. HEAD requests are handled transparently by net/http.

func Head

func Head(pat string) *Pattern

Head returns a Pat route that only matches the HEAD HTTP method.

func New

func New(pat string) *Pattern

New returns a new Pattern from the given Pat route. See the package documentation for more information about what syntax is accepted by this function.

func NewWithMethods

func NewWithMethods(pat string, methods ...string) *Pattern

NewWithMethods returns a Pat route that matches http methods that are provided

func Options

func Options(pat string) *Pattern

Options returns a Pat route that only matches the OPTIONS HTTP method.

func Patch

func Patch(pat string) *Pattern

Patch returns a Pat route that only matches the PATCH HTTP method.

func Post

func Post(pat string) *Pattern

Post returns a Pat route that only matches the POST HTTP method.

func Put

func Put(pat string) *Pattern

Put returns a Pat route that only matches the PUT HTTP method.

func (*Pattern) HTTPMethods

func (p *Pattern) HTTPMethods() map[string]struct{}

HTTPMethods returns a set of HTTP methods that all requests that this Pattern matches must be in, or nil if it's not possible to determine which HTTP methods might be matched.

This function satisfies goji's HTTPMethods Pattern optimization.

func (*Pattern) Match

func (p *Pattern) Match(r *http.Request) *http.Request

Match runs the Pat pattern on the given request, returning a non-nil output request if the input request matches the pattern.

This function satisfies goji.Pattern.

func (*Pattern) PathPrefix

func (p *Pattern) PathPrefix() string

PathPrefix returns a string prefix that the Paths of all requests that this Pattern accepts must contain.

This function satisfies goji's PathPrefix Pattern optimization.

func (*Pattern) String

func (p *Pattern) String() string

String returns the pattern string that was used to create this Pattern.