trout

     1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/doc.go	Mon Mar 16 00:10:38 2015 -0400
     1.3 @@ -0,0 +1,66 @@
     1.4 +/*
     1.5 +Package trout provides an opinionated router that's implemented
     1.6 +using a basic trie.
     1.7 +
     1.8 +The router is opinionated and biased towards basic RESTful
     1.9 +services. Its main constraint is that its URL templating is very
    1.10 +basic and has no support for regular expressions, prefix matching,
    1.11 +or anything other than a direct equality comparison, unlike many
    1.12 +routing libraries.
    1.13 +
    1.14 +The router is specifically designed to support users that want to
    1.15 +return correct information with HEAD requests, so it enables users
    1.16 +to retrieve a list of HTTP methods an Endpoint is configured to
    1.17 +respond to. It will not return the configurations an Endpoint is
    1.18 +implicitly configured to respond to by associated a Handler with the
    1.19 +Endpoint itself. These HTTP methods can be accessed through the
    1.20 +Trout-Methods header that is injected into the http.Request object.
    1.21 +Each method will be its own string in the slice.
    1.22 +
    1.23 +The router is also specifically designed to differentiate between a
    1.24 +404 (Not Found) response and a 405 (Method Not Allowed) response. It
    1.25 +will use the configured Handle404 http.Handler when no Endpoint is found
    1.26 +that matches the http.Request's Path property. It will use the
    1.27 +configured Handle405 http.Handler when an Endpoint is found for the
    1.28 +http.Request's Path, but the http.Request's Method has no Handler
    1.29 +associated with it. Setting a default http.Handler for the Endpoint will
    1.30 +result in the Handle405 http.Handler never being used for that Endpoint.
    1.31 +
    1.32 +To map an Endpoint to a http.Handler:
    1.33 +
    1.34 +	var router trout.Router
    1.35 +	router.Endpoint("/posts/{slug}/comments/{id}").Handler(postsHandler)
    1.36 +
    1.37 +All requests that match that URL structure will be passed to the postsHandler,
    1.38 +no matter what HTTP method they use.
    1.39 +
    1.40 +To map specific Methods to a http.Handler:
    1.41 +
    1.42 +	var router trout.Router
    1.43 +	router.Endpoint("/posts/{slug}").Methods("GET", "POST").Handler(postsHandler)
    1.44 +
    1.45 +Only requests that match that URL structure will be passed to the postsHandler,
    1.46 +and only if they use the GET or POST HTTP method.
    1.47 +
    1.48 +To access the URL parameter values inside a request, use the RequestVars helper:
    1.49 +
    1.50 +	func handler(w http.ResponseWriter, r *http.Request) {
    1.51 +		vars := trout.RequestVars(r)
    1.52 +		...
    1.53 +	}
    1.54 +
    1.55 +This will return an http.Header object containing the parameter values. They are
    1.56 +passed into the http.Handler by injecting them into the http.Request's Header property,
    1.57 +with the header key of "Trout-Params-{parameter}". The RequestVars helper is just a
    1.58 +convenience function to strip the prefix. Parameters are always passed without the curly
    1.59 +braces. Finally, if a parameter name is used multiple times in a single URL template, values
    1.60 +will be stored in the slice in the order they appeared in the template:
    1.61 +
    1.62 +	// for the template /posts/{id}/comments/{id}
    1.63 +	// filled with /posts/hello-world/comments/1
    1.64 +	vars := trout.RequestVars(r)
    1.65 +	fmt.Println(vars.Get("id")) // outputs `hello-world`
    1.66 +	fmt.Println(vars[http.CanonicalHeaderKey("id")]) // outputs `["hello-world", "1"]`
    1.67 +	fmt.Println(vars[http.CanonicalHeaderKey("id"})][1]) // outputs `1`
    1.68 +*/
    1.69 +package trout