Package pat
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.
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.
Pattern implements goji.Pattern using a path-matching domain specific language.
See the package documentation for more information about the semantics of this
object.
type Pattern struct {
}
func Delete(pat string) *Pattern
Delete returns a Pat route that only matches the DELETE HTTP method.
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(pat string) *Pattern
Head returns a Pat route that only matches the HEAD HTTP method.
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(pat string, methods ...string) *Pattern
NewWithMethods returns a Pat route that matches http methods that are provided
func Options(pat string) *Pattern
Options returns a Pat route that only matches the OPTIONS HTTP method.
func Patch(pat string) *Pattern
Patch returns a Pat route that only matches the PATCH HTTP method.
func Post(pat string) *Pattern
Post returns a Pat route that only matches the POST HTTP method.
func Put(pat string) *Pattern
Put returns a Pat route that only matches the PUT HTTP method.
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 (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.