pat

README

pat (formerly pat.go) - A Sinatra style pattern muxer for Go's net/http library

INSTALL

$ go get github.com/bmizerany/pat

USE

package main

import (
	"io"
	"net/http"
	"github.com/bmizerany/pat"
	"log"
)

// hello world, the web server
func HelloServer(w http.ResponseWriter, req *http.Request) {
	io.WriteString(w, "hello, "+req.URL.Query().Get(":name")+"!\n")
}

func main() {
	m := pat.New()
	m.Get("/hello/:name", http.HandlerFunc(HelloServer))

	// Register this pat with the default serve mux so that other packages
	// may also be exported. (i.e. /debug/pprof/*)
	http.Handle("/", m)
	err := http.ListenAndServe(":12345", nil)
	if err != nil {
		log.Fatal("ListenAndServe: ", err)
	}
}

It's that simple.

For more information, see: http://godoc.org/github.com/bmizerany/pat

CONTRIBUTORS

• Alexis Svinartchouk (@zvin)
• Blake Mizerany (@bmizerany)
• Brian Ketelsen (@bketelsen)
• Bryan Matsuo (@bmatsuo)
• Caleb Spare (@cespare)
• Evan Shaw (@edsrzf)
• Gary Burd (@garyburd)
• George Rogers (@georgerogers42)
• Keith Rarick (@kr)
• Matt Williams (@mattyw)
• Mike Stipicevic (@wickedchicken)
• Nick Saika (@nesv)
• Timothy Cyrus (@tcyrus)
• binqin (@binku87)

LICENSE

Copyright (C) 2012 by Keith Rarick, Blake Mizerany

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Documentation

Overview

Package pat implements a simple URL pattern muxer

Index

• Constants
• func Tail(pat, path string) string
• type MiddlewareFunc
  • func (mw MiddlewareFunc) Middleware(handler http.Handler) http.Handler
• type PatternServeMux
  • func New() *PatternServeMux
  • func (p *PatternServeMux) Add(meth, pat string, h http.Handler)
  • func (p *PatternServeMux) Del(pat string, h http.Handler)
  • func (p *PatternServeMux) Get(pat string, h http.Handler)
  • func (p *PatternServeMux) Head(pat string, h http.Handler)
  • func (p *PatternServeMux) Options(pat string, h http.Handler)
  • func (p *PatternServeMux) Patch(pat string, h http.Handler)
  • func (p *PatternServeMux) Post(pat string, h http.Handler)
  • func (p *PatternServeMux) Put(pat string, h http.Handler)
  • func (p *PatternServeMux) ServeHTTP(w http.ResponseWriter, r *http.Request)
  • func (p *PatternServeMux) Use(mwf ...MiddlewareFunc)

Constants

const (
	// RouteKey is inspired by mux and other routers to preserve the matched
	// pattern that can be referenced in the lifetime of a handler.
	// This is useful for telemetry and instrumentation to use the pattern
	// AND not the whole URL, which can result in cardinality explosion.
	// For compatibility with most other mux like gorilla, mux, use count=1
	RouteKey contextKey = iota + 1
)

Functions

func Tail

func Tail(pat, path string) string

Tail returns the trailing string in path after the final slash for a pat ending with a slash.

Examples:

Tail("/hello/:title/", "/hello/mr/mizerany") == "mizerany"
Tail("/:a/", "/x/y/z")                       == "y/z"

Types

type MiddlewareFunc

type MiddlewareFunc func(http.Handler) http.Handler

MiddlewareFunc is a function which receives an http.Handler and returns another http.Handler. Typically, the returned handler is a closure which does something with the http.ResponseWriter and http.Request passed to it, and then calls the handler passed as parameter to the MiddlewareFunc.

func (MiddlewareFunc) Middleware

func (mw MiddlewareFunc) Middleware(handler http.Handler) http.Handler

Middleware allows MiddlewareFunc to implement the middleware interface.

type PatternServeMux

type PatternServeMux struct {
	// NotFound, if set, is used whenever the request doesn't match any
	// pattern for its method. NotFound should be set before serving any
	// requests.
	NotFound http.Handler
	// contains filtered or unexported fields
}

PatternServeMux is an HTTP request multiplexer. It matches the URL of each incoming request against a list of registered patterns with their associated methods and calls the handler for the pattern that most closely matches the URL.

Pattern matching attempts each pattern in the order in which they were registered.

Patterns may contain literals or captures. Capture names start with a colon and consist of letters A-Z, a-z, _, and 0-9. The rest of the pattern matches literally. The portion of the URL matching each name ends with an occurrence of the character in the pattern immediately following the name, or a /, whichever comes first. It is possible for a name to match the empty string.

Example pattern with one capture:

/hello/:name

Will match:

/hello/blake
/hello/keith

Will not match:

/hello/blake/
/hello/blake/foo
/foo
/foo/bar

Example 2:

/hello/:name/

Will match:

/hello/blake/
/hello/keith/foo
/hello/blake
/hello/keith

Will not match:

/foo
/foo/bar

A pattern ending with a slash will add an implicit redirect for its non-slash version. For example: Get("/foo/", handler) also registers Get("/foo", handler) as a redirect. You may override it by registering Get("/foo", anotherhandler) before the slash version.

Retrieve the capture from the r.URL.Query().Get(":name") in a handler (note the colon). If a capture name appears more than once, the additional values are appended to the previous values (see http://golang.org/pkg/net/url/#Values)

A trivial example server is:

package main

import (
	"io"
	"net/http"
	"github.com/bmizerany/pat"
	"log"
)

// hello world, the web server
func HelloServer(w http.ResponseWriter, req *http.Request) {
	io.WriteString(w, "hello, "+req.URL.Query().Get(":name")+"!\n")
}

func main() {
	m := pat.New()
	m.Get("/hello/:name", http.HandlerFunc(HelloServer))

	// Register this pat with the default serve mux so that other packages
	// may also be exported. (i.e. /debug/pprof/*)
	http.Handle("/", m)
	err := http.ListenAndServe(":12345", nil)
	if err != nil {
		log.Fatal("ListenAndServe: ", err)
	}
}

When "Method Not Allowed":

Pat knows what methods are allowed given a pattern and a URI. For convenience, PatternServeMux will add the Allow header for requests that match a pattern for a method other than the method requested and set the Status to "405 Method Not Allowed".

If the NotFound handler is set, then it is used whenever the pattern doesn't match the request path for the current method (and the Allow header is not altered).

func New

func New() *PatternServeMux

New returns a new PatternServeMux.

func (*PatternServeMux) Add

func (p *PatternServeMux) Add(meth, pat string, h http.Handler)

Add will register a pattern with a handler for meth requests.

func (*PatternServeMux) Del

func (p *PatternServeMux) Del(pat string, h http.Handler)

Del will register a pattern with a handler for DELETE requests.

func (*PatternServeMux) Get

func (p *PatternServeMux) Get(pat string, h http.Handler)

Get will register a pattern with a handler for GET requests. It also registers pat for HEAD requests. If this needs to be overridden, use Head before Get with pat.

func (*PatternServeMux) Head

func (p *PatternServeMux) Head(pat string, h http.Handler)

Head will register a pattern with a handler for HEAD requests.

func (*PatternServeMux) Options

func (p *PatternServeMux) Options(pat string, h http.Handler)

Options will register a pattern with a handler for OPTIONS requests.

func (*PatternServeMux) Patch

func (p *PatternServeMux) Patch(pat string, h http.Handler)

Patch will register a pattern with a handler for PATCH requests.

func (*PatternServeMux) Post

func (p *PatternServeMux) Post(pat string, h http.Handler)

Post will register a pattern with a handler for POST requests.

func (*PatternServeMux) Put

func (p *PatternServeMux) Put(pat string, h http.Handler)

Put will register a pattern with a handler for PUT requests.

func (*PatternServeMux) ServeHTTP

func (p *PatternServeMux) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP matches r.URL.Path against its routing table using the rules described above.

func (*PatternServeMux) Use

func (p *PatternServeMux) Use(mwf ...MiddlewareFunc)

Use appends a MiddlewareFunc to the chain. Middleware can be used to intercept or otherwise modify requests and/or responses, and are executed in the order that they are applied to the Router.