Add a readme in case other people want to use it

1 files changed, 62 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..be9f685
--- /dev/null
+++ b/README.md
@@ -0,0 +1,62 @@
+# 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:
+
+    [org.clojars.czan/abra "0.1.0"]
+
+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:
+
+    (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`:
+
+    (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` and `ANY`.
+
+To later retrieve this url, use the `abra.core/url-for` function:
+
+    (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:
+
+    (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"))))