diff options
Diffstat (limited to 'guide')
| -rw-r--r-- | guide/middlewares.md | 2 | ||||
| -rw-r--r-- | guide/routing.md | 46 |
2 files changed, 30 insertions, 18 deletions
diff --git a/guide/middlewares.md b/guide/middlewares.md index 2f583cf..0ab6dc2 100644 --- a/guide/middlewares.md +++ b/guide/middlewares.md @@ -61,8 +61,6 @@ environment values to perform. Routing middleware ------------------ -@todo Routing middleware value is renamed very soon. - The routing middleware requires the `dispatch` value. If routing succeeds, it will put the handler name and options in the `handler` and `handler_opts` values of the environment, respectively. diff --git a/guide/routing.md b/guide/routing.md index 2970b39..9d5c5af 100644 --- a/guide/routing.md +++ b/guide/routing.md @@ -1,9 +1,6 @@ Routing ======= -@todo Note that this documentation is for the new routing interface -not available in master at this point. - Purpose ------- @@ -49,9 +46,9 @@ Finally, each path contains matching rules for the path along with optional constraints, and gives us the handler module to be used along with options that will be given to it on initialization. -``` -Path1 = {PathMatch, Handler, Module}. -Path2 = {PathMatch, Constraints, Handler, Module}. +``` erlang +Path1 = {PathMatch, Handler, Opts}. +Path2 = {PathMatch, Constraints, Handler, Opts}. ``` Continue reading to learn more about the match syntax and the optional @@ -112,11 +109,11 @@ HostMatch = ":subdomain.example.org". ``` If these two end up matching when routing, you will end up with two -bindings defined, `subdomain` and `hat_name`, each containing the +bindings defined, `subdomain` and `name`, each containing the segment value where they were defined. For example, the URL `http://test.example.org/hats/wild_cowboy_legendary/prices` will result in having the value `test` bound to the name `subdomain` -and the value `wild_cowboy_legendary` bound to the name `hat_name`. +and the value `wild_cowboy_legendary` bound to the name `name`. They can later be retrieved using `cowboy_req:binding/{2,3}`. The binding name must be given as an atom. @@ -156,9 +153,9 @@ PathMatch = "/hats/[...]". HostMatch = "[...]ninenines.eu". ``` -Finally, if a binding appears twice in the routing rules, then the -match will succeed only if they share the same value. This copies -the Erlang pattern matching behavior. +If a binding appears twice in the routing rules, then the match +will succeed only if they share the same value. This copies the +Erlang pattern matching behavior. ``` erlang PathMatch = "/hats/:name/:name". @@ -180,12 +177,28 @@ PathMatch = "/:user/[...]". HostMatch = ":user.github.com". ``` +Finally, there are two special match values that can be used. The +first is the atom `'_'` which will match any host or path. + +``` erlang +PathMatch = '_'. +HostMatch = '_'. +``` + +The second is the special host match `"*"` which will match the +wildcard path, generally used alongside the `OPTIONS` method. + +``` erlang +HostMatch = "*". +``` + Constraints ----------- After the matching has completed, the resulting bindings can be tested -against a set of constraints. The match will succeed only if they all -succeed. +against a set of constraints. Constraints are only tested when the +binding is defined. They run in the order you defined them. The match +will succeed only if they all succeed. They are always given as a two or three elements tuple, where the first element is the name of the binding, the second element is the constraint's @@ -194,7 +207,7 @@ name, and the optional third element is the constraint's arguments. The following constraints are currently defined: * {Name, int} - * {Name, function, (fun(Value) -> true | {true, NewValue} | false)} + * {Name, function, fun ((Value) -> true | {true, NewValue} | false)} The `int` constraint will check if the binding is a binary string representing an integer, and if it is, will convert the value to integer. @@ -202,6 +215,7 @@ representing an integer, and if it is, will convert the value to integer. The `function` constraint will pass the binding value to a user specified function that receives the binary value as its only argument and must return whether it fulfills the constraint, optionally modifying the value. +The value thus returned can be of any type. Note that constraint functions SHOULD be pure and MUST NOT crash. @@ -212,10 +226,10 @@ The structure defined in this chapter needs to be compiled before it is passed to Cowboy. This allows Cowboy to efficiently lookup the correct handler to run instead of having to parse the routes repeatedly. -This can be done with a simple call to `cowboy_routing:compile/1`. +This can be done with a simple call to `cowboy_router:compile/1`. ``` erlang -{ok, Routes} = cowboy_routing:compile([ +{ok, Routes} = cowboy_router:compile([ %% {HostMatch, list({PathMatch, Handler, Opts})} {'_', [{'_', my_handler, []}]} ]), |