= cowboy_router(3)

== Name

cowboy_router - router middleware

== Description

The `cowboy_router` middleware maps the requested host and
path to the handler to be used for processing the request.
It uses the dispatch rules compiled from the routes given
to the `compile/1` function for this purpose. It adds the
handler name and options to the environment as the values
`handler` and `handler_opts` respectively.

=== Environment input

dispatch = dispatch_rules():: Dispatch table.

=== Environment output

handler = module():: Handler module.
handler_opts = any():: Handler options.

== Types

=== bindings() = [{atom(), binary()}]

List of bindings found during routing.

=== dispatch_rules() - opaque to the user

Rules for dispatching request used by Cowboy.

=== routes() = [{Host, Paths} | {Host, cowboy:fields(), Paths}]

With types:

* Host = Path = '_' | iodata()
* Paths = [{Path, Handler, Opts} | {Path, cowboy:fields(), Handler, HandlerOpts}]
* Handler = module()
* HandlerOpts = any()

Human readable list of routes mapping hosts and paths to handlers.

The syntax for routes is defined in the user guide.

=== tokens() = [binary()]

List of host_info and path_info tokens found during routing.

== Exports

=== compile(routes()) -> dispatch_rules()

Compile the routes for use by Cowboy.