summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--README.md62
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"))))