Introduction of RouteGroup concept

RouteGroup is a simple route mapper that delegates to an underlying Router
instance when mapping paths and takes no part in handling of requests
resulting in zero added per-request cost.

Implemented as a simple struct to keep in the spirit of httprouter's design.

Potential improvement being to create an interface for the common functions of
Router and RouteGroup.

Author: dbudworth

README.md

@@ -35,6 +35,8 @@ to the correct URL.
 just give the path segment a name and the router delivers the dynamic value to
 you. Because of the design of the router, path parameters are very cheap.
 
+**RouteGroups:** A way to create groups of routes without incuring any per-request overhead.
+
 **Zero Garbage:** The matching and dispatching process generates zero bytes of
 garbage. In fact, the only heap allocations that are made, is by building the
 slice of the key-value pairs for path parameters. If the request path contains

routegroup.go

@@ -0,0 +1,67 @@
+package httprouter
+
+import (
+	"net/http"
+)
+
+type RouteGroup struct {
+	r *Router
+	p string
+}
+
+func newRouteGroup(r *Router, path string) *RouteGroup {
+	if path[0] != '/' {
+		panic("path must begin with '/' in path '" + path + "'")
+	}
+
+	//Strip traling / (if present) as all added sub paths must start with a /
+	if path[len(path)-1] == '/' {
+		path = path[:len(path)-1]
+	}
+	return &RouteGroup{r: r, p: path}
+}
+
+func (r *RouteGroup) NewGroup(path string) *RouteGroup {
+	return newRouteGroup(r.r, r.subPath(path))
+}
+
+func (r *RouteGroup) Handle(method, path string, handle Handle) {
+	r.r.Handle(method, r.subPath(path), handle)
+}
+
+func (r *RouteGroup) Handler(method, path string, handler http.Handler) {
+	r.r.Handler(method, r.subPath(path), handler)
+}
+
+func (r *RouteGroup) HandlerFunc(method, path string, handler http.HandlerFunc) {
+	r.r.HandlerFunc(method, r.subPath(path), handler)
+}
+
+func (r *RouteGroup) GET(path string, handle Handle) {
+	r.Handle("GET", path, handle)
+}
+func (r *RouteGroup) HEAD(path string, handle Handle) {
+	r.Handle("HEAD", path, handle)
+}
+func (r *RouteGroup) OPTIONS(path string, handle Handle) {
+	r.Handle("OPTIONS", path, handle)
+}
+func (r *RouteGroup) POST(path string, handle Handle) {
+	r.Handle("POST", path, handle)
+}
+func (r *RouteGroup) PUT(path string, handle Handle) {
+	r.Handle("PUT", path, handle)
+}
+func (r *RouteGroup) PATCH(path string, handle Handle) {
+	r.Handle("PATCH", path, handle)
+}
+func (r *RouteGroup) DELETE(path string, handle Handle) {
+	r.Handle("DELETE", path, handle)
+}
+
+func (r *RouteGroup) subPath(path string) string {
+	if path[0] != '/' {
+		panic("path must start with a '/'")
+	}
+	return r.p + path
+}

routegroup_test.go

@@ -0,0 +1,117 @@
+package httprouter
+
+import (
+	"net/http"
+	"testing"
+)
+
+func TestRouteGroupOfARouteGroup(t *testing.T) {
+	var get bool
+	router := New()
+	foo := router.NewGroup("/foo") // creates /foo group
+	bar := foo.NewGroup("/bar")
+
+	bar.GET("/GET", func(w http.ResponseWriter, r *http.Request, _ Params) {
+		get = true
+	})
+
+	w := new(mockResponseWriter)
+
+	r, _ := http.NewRequest("GET", "/foo/bar/GET", nil)
+	router.ServeHTTP(w, r)
+	if !get {
+		t.Error("routing GET /foo/bar/GET failed")
+	}
+
+}
+
+func TestRouteGroupAPI(t *testing.T) {
+	var get, head, options, post, put, patch, delete, handler, handlerFunc bool
+
+	httpHandler := handlerStruct{&handler}
+
+	router := New()
+	group := router.NewGroup("/foo") // creates /foo group
+
+	group.GET("/GET", func(w http.ResponseWriter, r *http.Request, _ Params) {
+		get = true
+	})
+	group.HEAD("/GET", func(w http.ResponseWriter, r *http.Request, _ Params) {
+		head = true
+	})
+	group.OPTIONS("/GET", func(w http.ResponseWriter, r *http.Request, _ Params) {
+		options = true
+	})
+	group.POST("/POST", func(w http.ResponseWriter, r *http.Request, _ Params) {
+		post = true
+	})
+	group.PUT("/PUT", func(w http.ResponseWriter, r *http.Request, _ Params) {
+		put = true
+	})
+	group.PATCH("/PATCH", func(w http.ResponseWriter, r *http.Request, _ Params) {
+		patch = true
+	})
+	group.DELETE("/DELETE", func(w http.ResponseWriter, r *http.Request, _ Params) {
+		delete = true
+	})
+	group.Handler("GET", "/Handler", httpHandler)
+	group.HandlerFunc("GET", "/HandlerFunc", func(w http.ResponseWriter, r *http.Request) {
+		handlerFunc = true
+	})
+
+	w := new(mockResponseWriter)
+
+	r, _ := http.NewRequest("GET", "/foo/GET", nil)
+	router.ServeHTTP(w, r)
+	if !get {
+		t.Error("routing /foo/GET failed")
+	}
+
+	r, _ = http.NewRequest("HEAD", "/foo/GET", nil)
+	router.ServeHTTP(w, r)
+	if !head {
+		t.Error("routing HEAD failed")
+	}
+
+	r, _ = http.NewRequest("OPTIONS", "/foo/GET", nil)
+	router.ServeHTTP(w, r)
+	if !options {
+		t.Error("routing OPTIONS failed")
+	}
+
+	r, _ = http.NewRequest("POST", "/foo/POST", nil)
+	router.ServeHTTP(w, r)
+	if !post {
+		t.Error("routing POST failed")
+	}
+
+	r, _ = http.NewRequest("PUT", "/foo/PUT", nil)
+	router.ServeHTTP(w, r)
+	if !put {
+		t.Error("routing PUT failed")
+	}
+
+	r, _ = http.NewRequest("PATCH", "/foo/PATCH", nil)
+	router.ServeHTTP(w, r)
+	if !patch {
+		t.Error("routing PATCH failed")
+	}
+
+	r, _ = http.NewRequest("DELETE", "/foo/DELETE", nil)
+	router.ServeHTTP(w, r)
+	if !delete {
+		t.Error("routing DELETE failed")
+	}
+
+	r, _ = http.NewRequest("GET", "/foo/Handler", nil)
+	router.ServeHTTP(w, r)
+	if !handler {
+		t.Error("routing Handler failed")
+	}
+
+	r, _ = http.NewRequest("GET", "/foo/HandlerFunc", nil)
+	router.ServeHTTP(w, r)
+	if !handlerFunc {
+		t.Error("routing HandlerFunc failed")
+	}
+}

router.go

@@ -168,6 +168,10 @@ func New() *Router {
 	}
 }
 
+func (r *Router) NewGroup(path string) *RouteGroup {
+	return newRouteGroup(r, path)
+}
+
 // GET is a shortcut for router.Handle("GET", path, handle)
 func (r *Router) GET(path string, handle Handle) {
 	r.Handle("GET", path, handle)