# Abra

A small [clojure][1] library for reverse-routing in [compojure][2]
applications.

[1]: http://clojure.org
[2]: https://github.com/weavejester/compojure

# Usage

Include `abra` by adding the following to your dependencies:

    :::clojure
    [org.clojars.czan/abra "0.1.2"]

At the very bottom of your middleware stack (closest to your actual
handlers), apply the `abra.core/wrap-reverse-routing` middleware (any
lower-level middleware must then be applied with
`abra.core/add-middleware`).

Instead of `compojure.core/`{`defroutes`,`routes`,`context`}, use
`abra.core/`{`defroutes`,`routes`,`context`}.

As an example:

    :::clojure
    (require '[abra.core :refer [routes context] :as abra])
    (def app (-> (routes (context "/api" []
                           (-> #'api-routes
                               (abra/add-middleware api)))
                         (-> #'site-routes
                             (abra/add-middleware site)))
                  abra/wrap-reverse-routing))

When giving a route a name, wrap it in a call to
`abra.core/register-route`:

    :::clojure
    (defroutes site-routes
      (register-route :username
        (GET "/username/" []
          (str "a username"))))

`register-route` currently only supports the standard `compojure`
methods: `GET`, `POST`, `PUT`, `DELETE`, `HEAD`, `OPTIONS`, `PATCH`
and `ANY`.

To later retrieve this url, use the `abra.core/url-for` function:

    :::clojure
    (defroutes api-routes
      (GET "/" []
        (str "url: " (url-for :username))))

The `url-for` function at present does not indicate the method to be
used for the url, although this information may be exposed in future.

A route may also require parameters, in which case the `url-for`
function must be provided the correct number of additional parameters:

    :::clojure
    (defroutes test-routes
      (context "/user/:id" [id]
        (register-route :user-attr
          (GET "/:attr" [attr]
            (str id "::" attr))))
      (GET "/" []
        (str (url-for :user-attr 10 "name"))))