Merge pull request #115 from jnichols-git/beta.4

jnichols-git · web-flow · commit ff8371b9100c · 2023-12-24T17:05:21.000-05:00
make route/router public, fix user guide
diff --git a/Makefile b/Makefile
@@ -1,6 +1,6 @@
 FORCE:
 
-test:
+test: FORCE
 	go test -coverprofile cicd/cover.out ./...
 
 cover: test
diff --git a/docs/user-guide.md b/docs/user-guide.md
@@ -1,16 +1,15 @@
 # Matcha User Guide
 
-- [Matcha User Guide](#matcha-user-guide)
-	- [Basics](#basics)
-		- [Hello World](#hello-world)
-		- [Echo Server with Route Parameters](#echo-server-with-route-parameters)
-		- [File Server with Partial Routes](#file-server-with-partial-routes)
-	- [Advanced Usage](#advanced-usage)
-		- [Mounting Subrouters](#mounting-subrouters)
-		- [Middleware](#middleware)
-		- [Requirements](#requirements)
-	- [FAQ](#faq)
-		- [Why are some of my routes not matched when they should be?](#why-are-some-of-my-routes-not-matched-when-they-should-be)
+- [Basics](#basics)
+	- [Hello World](#hello-world)
+	- [Echo Server with Route Parameters](#echo-server-with-route-parameters)
+	- [File Server with Partial Routes](#file-server-with-partial-routes)
+- [Advanced Usage](#advanced-usage)
+	- [Mounting Subrouters](#mounting-subrouters)
+	- [Middleware](#middleware)
+	- [Requirements](#requirements)
+- [FAQ](#faq)
+	- [Why are some of my routes not matched when they should be?](#why-are-some-of-my-routes-not-matched-when-they-should-be)
 
 Hello! This is a step-by-step guide to using Matcha for HTTP handling in Go.
 
@@ -20,7 +19,9 @@ There are a few examples in the `examples` directory to show basic usage.
 
 ### Hello World
 
-You can use `matcha.Router` to create a new Router and `router.HandleFunc` to handle a request path.
+You can use `matcha.Router` to create a new Router and `router.HandleFunc` to
+handle a request path. Routers are type `*router.Router` if you need to store
+it.
 
 ```go
 package main
@@ -190,14 +191,12 @@ $
 Requirements are defined in `require` as a `func(*http.Request) bool`. If you need more tools to check routes, you can `Require` a requirement with any Route. If this function returns false for any request, the route is not matched, but it can still match any routes after.
 
 ```go
-webRoute, err := route.New(
+webRoute, err := matcha.Route(
     http.MethodGet, "/",
-    route.Require(require.HostPorts("https://[www.|]jnichols.info")),
-)
-apiRoute, err := route.New(
+).Require(require.HostPorts("https://[www.|]jnichols.info"))
+apiRoute, err := matcha.Route(
     http.MethodGet, "/",
-    require.HostPorts("https://api.jnichols.info"),
-)
+).Require(require.HostPorts("https://api.jnichols.info"))
 ```
 
 ## FAQ
diff --git a/internal/tree/tree.go b/internal/tree/tree.go
@@ -8,8 +8,8 @@ import (
 	"sync/atomic"
 
 	"github.com/jnichols-git/matcha/v2/internal/path"
-	"github.com/jnichols-git/matcha/v2/internal/route"
 	"github.com/jnichols-git/matcha/v2/require"
+	"github.com/jnichols-git/matcha/v2/route"
 )
 
 const NO_LEAF_ID = int64(0)
diff --git a/internal/tree/tree_bench_test.go b/internal/tree/tree_bench_test.go
@@ -5,7 +5,7 @@ import (
 	"net/http"
 	"testing"
 
-	"github.com/jnichols-git/matcha/v2/internal/route"
+	"github.com/jnichols-git/matcha/v2/route"
 )
 
 var routes []string = []string{
diff --git a/internal/tree/tree_test.go b/internal/tree/tree_test.go
@@ -6,8 +6,8 @@ import (
 	"testing"
 
 	"github.com/jnichols-git/matcha/v2/internal/rctx"
-	"github.com/jnichols-git/matcha/v2/internal/route"
 	"github.com/jnichols-git/matcha/v2/require"
+	"github.com/jnichols-git/matcha/v2/route"
 )
 
 func TestTree(t *testing.T) {
diff --git a/matcha.go b/matcha.go
@@ -4,8 +4,8 @@ import (
 	"net/http"
 
 	"github.com/jnichols-git/matcha/v2/internal/rctx"
-	"github.com/jnichols-git/matcha/v2/internal/route"
-	"github.com/jnichols-git/matcha/v2/internal/router"
+	"github.com/jnichols-git/matcha/v2/route"
+	"github.com/jnichols-git/matcha/v2/router"
 )
 
 func Route(method, expr string) (r *route.Route, err error) {
diff --git a/route/part.go b/route/part.go
diff --git a/route/route.go b/route/route.go
diff --git a/route/route_bench_test.go b/route/route_bench_test.go
diff --git a/route/util.go b/route/util.go
diff --git a/route/util_test.go b/route/util_test.go
diff --git a/router/router.go b/router/router.go
@@ -5,8 +5,8 @@ import (
 
 	"github.com/jnichols-git/matcha/v2/internal/path"
 	"github.com/jnichols-git/matcha/v2/internal/rctx"
-	"github.com/jnichols-git/matcha/v2/internal/route"
 	"github.com/jnichols-git/matcha/v2/internal/tree"
+	"github.com/jnichols-git/matcha/v2/route"
 	"github.com/jnichols-git/matcha/v2/teaware"
 )
 
@@ -29,16 +29,17 @@ func Default() *Router {
 		notfound:  http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { w.WriteHeader(http.StatusNotFound) }),
 		maxParams: rctx.DefaultMaxParams,
 	}
-	r.Reload()
+	r.reload()
 	return r
 }
 
 // Attach middleware to the router.
 //
 // See interface Router.
-func (rt *Router) Use(mws ...teaware.Middleware) {
+func (rt *Router) Use(mws ...teaware.Middleware) *Router {
 	rt.mws = append(rt.mws, mws...)
-	rt.Reload()
+	rt.reload()
+	return rt
 }
 
 func register(rt *Router, r *route.Route, h http.Handler) {
@@ -50,7 +51,7 @@ func register(rt *Router, r *route.Route, h http.Handler) {
 	} else {
 		rt.handlers[id] = nil
 	}
-	rt.Reload()
+	rt.reload()
 }
 
 // Add a route to the router.
@@ -119,18 +120,18 @@ func (rt *Router) Mount(rpath string, h http.Handler, methods ...string) error {
 		r.Use(trim)
 		rt.HandleRoute(r, h)
 	}
-	rt.Reload()
+	rt.reload()
 	return nil
 }
 
 // Set the handler for instances where no route is found.
 //
 // See interface Router.
-func (rt *Router) AddNotFound(h http.Handler) {
+func (rt *Router) HandleNotFound(h http.Handler) {
 	rt.notfound = h
 }
 
-func (rt *Router) Reload() {
+func (rt *Router) reload() {
 	var h http.Handler = http.HandlerFunc(rt.matchRoute)
 	h = teaware.Handler(h, rt.mws...)
 	rt.compiled = h
diff --git a/router/router_bench_test.go b/router/router_bench_test.go
@@ -5,7 +5,7 @@ import (
 	"net/http"
 	"testing"
 
-	"github.com/jnichols-git/matcha/v2/internal/route"
+	"github.com/jnichols-git/matcha/v2/route"
 )
 
 // mock response writer, taken from go-http-routing-benchmark
diff --git a/router/router_test.go b/router/router_test.go
@@ -16,7 +16,7 @@ import (
 	"github.com/jnichols-git/matcha/v2/teaware"
 
 	"github.com/jnichols-git/matcha/v2/internal/rctx"
-	"github.com/jnichols-git/matcha/v2/internal/route"
+	"github.com/jnichols-git/matcha/v2/route"
 )
 
 // Return a handler that writes OK to all requests
@@ -325,7 +325,7 @@ func TestCORS(t *testing.T) {
 		w.WriteHeader(http.StatusNoContent)
 	})
 	r.Handle(http.MethodGet, "/", okHandler("ok"))
-	r.AddNotFound(nfHandler())
+	r.HandleNotFound(nfHandler())
 	s := httptest.NewServer(r)
 
 	runEvalRequest(t, s, "/", reqGenHeaders(http.MethodGet, http.Header{"Origin": {"test-origin"}}), map[string]any{
diff --git a/test/v1_test.go b/test/v1_test.go
@@ -7,8 +7,8 @@ import (
 	"sync"
 	"testing"
 
-	"github.com/jnichols-git/matcha/v2/internal/route"
-	"github.com/jnichols-git/matcha/v2/internal/router"
+	"github.com/jnichols-git/matcha/v2"
+	"github.com/jnichols-git/matcha/v2/route"
 )
 
 /*
@@ -73,9 +73,9 @@ func handleOK(w http.ResponseWriter, req *http.Request) {
 
 // Just to check!
 func TestAPIv1(t *testing.T) {
-	rt := router.Default()
+	rt := matcha.Router()
 	for _, tr := range apiRoutes {
-		r := route.Declare(tr.method, tr.path)
+		r, _ := matcha.Route(tr.method, tr.path)
 		r.Use(tr.mws...)
 		r.Require(tr.rqs...)
 		rt.HandleRouteFunc(r, handleOK)
@@ -96,7 +96,7 @@ func TestAPIv1(t *testing.T) {
 // BENCHMARKS: MockBoards API
 
 func BenchmarkAPIv1(b *testing.B) {
-	rt := router.Default()
+	rt := matcha.Router()
 	for _, tr := range apiRoutes {
 		r, err := route.New(tr.method, tr.path)
 		if err != nil {
@@ -136,7 +136,7 @@ func BenchmarkAPIv1(b *testing.B) {
 }
 
 func BenchmarkStrippedAPI(b *testing.B) {
-	rt := router.Default()
+	rt := matcha.Router()
 	for _, tr := range apiRoutes {
 		r, err := route.New(tr.method, tr.path)
 		if err != nil {
diff --git a/test/v2_test.go b/test/v2_test.go
@@ -6,8 +6,8 @@ import (
 	"sync"
 	"testing"
 
-	"github.com/jnichols-git/matcha/v2/internal/route"
-	"github.com/jnichols-git/matcha/v2/internal/router"
+	"github.com/jnichols-git/matcha/v2/route"
+	"github.com/jnichols-git/matcha/v2/router"
 )
 
 /*

Original file line number	Diff line number	Diff line change
`@@ -8,8 +8,8 @@ import (`
`8`	`8`	`"sync/atomic"`
`9`	`9`
`10`	`10`	`"github.com/jnichols-git/matcha/v2/internal/path"`
`11`		`- "github.com/jnichols-git/matcha/v2/internal/route"`
`12`	`11`	`"github.com/jnichols-git/matcha/v2/require"`
	`12`	`+ "github.com/jnichols-git/matcha/v2/route"`
`13`	`13`	`)`
`14`	`14`
`15`	`15`	`const NO_LEAF_ID = int64(0)`
Original file line number	Diff line number	Diff line change
`@@ -5,7 +5,7 @@ import (`
`5`	`5`	`"net/http"`
`6`	`6`	`"testing"`
`7`	`7`
`8`		`- "github.com/jnichols-git/matcha/v2/internal/route"`
	`8`	`+ "github.com/jnichols-git/matcha/v2/route"`
`9`	`9`	`)`
`10`	`10`
`11`	`11`	`var routes []string = []string{`
Original file line number	Diff line number	Diff line change
`@@ -6,8 +6,8 @@ import (`
`6`	`6`	`"testing"`
`7`	`7`
`8`	`8`	`"github.com/jnichols-git/matcha/v2/internal/rctx"`
`9`		`- "github.com/jnichols-git/matcha/v2/internal/route"`
`10`	`9`	`"github.com/jnichols-git/matcha/v2/require"`
	`10`	`+ "github.com/jnichols-git/matcha/v2/route"`
`11`	`11`	`)`
`12`	`12`
`13`	`13`	`func TestTree(t *testing.T) {`
Original file line number	Diff line number	Diff line change
`@@ -4,8 +4,8 @@ import (`
`4`	`4`	`"net/http"`
`5`	`5`
`6`	`6`	`"github.com/jnichols-git/matcha/v2/internal/rctx"`
`7`		`- "github.com/jnichols-git/matcha/v2/internal/route"`
`8`		`- "github.com/jnichols-git/matcha/v2/internal/router"`
	`7`	`+ "github.com/jnichols-git/matcha/v2/route"`
	`8`	`+ "github.com/jnichols-git/matcha/v2/router"`
`9`	`9`	`)`
`10`	`10`
`11`	`11`	`func Route(method, expr string) (r *route.Route, err error) {`