From cb0297ac8586491f755721e916624165d991eef3 Mon Sep 17 00:00:00 2001
From: Tommi Reiman <tommi@iki.fi>
Date: Mon, 25 Jun 2018 10:33:27 +0300
Subject: [PATCH] reverse-routing docs

---
 doc/basics/name_based_routing.md | 18 +++++++++++++
 doc/ring/reverse_routing.md      | 43 ++++++++++++++++++--------------
 2 files changed, 42 insertions(+), 19 deletions(-)

diff --git a/doc/basics/name_based_routing.md b/doc/basics/name_based_routing.md
index 3e5c7d8c..4687dbdc 100644
--- a/doc/basics/name_based_routing.md
+++ b/doc/basics/name_based_routing.md
@@ -81,3 +81,21 @@ There is also a exception throwing version:
 (r/match-by-name! router ::user)
 ; ExceptionInfo missing path-params for route /api/user/:id: #{:id}
 ```
+
+To turn a Match into a path, there is `reitit.core/match->path`:
+
+```clj
+(-> router
+    (r/match-by-name ::user {:id 1})
+    (r/match->path))
+; "/api/user/1"
+```
+
+It can take an optional map of query-parameters too:
+
+```clj
+(-> router
+    (r/match-by-name ::user {:id 1})
+    (r/match->path {:iso "möly"}))
+; "/api/user/1?iso=m%C3%B6ly"    
+```
diff --git a/doc/ring/reverse_routing.md b/doc/ring/reverse_routing.md
index 9cfd61c7..e2d7b5af 100644
--- a/doc/ring/reverse_routing.md
+++ b/doc/ring/reverse_routing.md
@@ -1,8 +1,8 @@
 # Reverse routing with Ring
 
-Both the `router` and the `match` are injected into Ring Request (as `::r/router` and `::r/match`) by the `reitit.ring/ring-handler` and with that, available to middleware and endpoints.
+Both the `router` and the `match` are injected into Ring Request (as `::r/router` and `::r/match`) by the `reitit.ring/ring-handler` and with that, available to middleware and endpoints. To convert a `Match` into a path, one can use `r/match->path`, which optionally takes a map of query-parameters too.
 
-Below is an example how to use the `router` to do reverse routing from a ring handler:
+Below is an example how to do reverse routing from a ring handler:
 
 ```clj
 (require '[reitit.core :as r])
@@ -11,23 +11,28 @@ Below is an example how to use the `router` to do reverse routing from a ring ha
 (def app
   (ring/ring-handler
     (ring/router
-      [["/users" {:get (fn [{:keys [::r/router]}]
-                         {:status 200
-                          :body (for [i (range 10)]
-                                  {:uri (:path (r/match-by-name router ::user {:id i}))})})}]
-       ["/users/:id" {:name ::user
-                      :get (constantly {:status 200, :body "user..."})}]])))
+      [["/users"
+        {:get (fn [{:keys [::r/router]}]
+                {:status 200
+                 :body (for [i (range 10)]
+                         {:uri (-> router
+                                   (r/match-by-name ::user {:id i})
+                                   ;; with extra query-params
+                                   (r/match->path {:iso "möly"}))})})}]
+       ["/users/:id"
+        {:name ::user
+         :get (constantly {:status 200, :body "user..."})}]])))
 
 (app {:request-method :get, :uri "/users"})
-;{:status 200,
-; :body [{:uri "/users/0"}
-;        {:uri "/users/1"}
-;        {:uri "/users/2"}
-;        {:uri "/users/3"}
-;        {:uri "/users/4"}
-;        {:uri "/users/5"}
-;        {:uri "/users/6"}
-;        {:uri "/users/7"}
-;        {:uri "/users/8"}
-;        {:uri "/users/9"}]}
+; {:status 200,
+;  :body ({:uri "/users/0?iso=m%C3%B6ly"}
+;         {:uri "/users/1?iso=m%C3%B6ly"}
+;         {:uri "/users/2?iso=m%C3%B6ly"}
+;         {:uri "/users/3?iso=m%C3%B6ly"}
+;         {:uri "/users/4?iso=m%C3%B6ly"}
+;         {:uri "/users/5?iso=m%C3%B6ly"}
+;         {:uri "/users/6?iso=m%C3%B6ly"}
+;         {:uri "/users/7?iso=m%C3%B6ly"}
+;         {:uri "/users/8?iso=m%C3%B6ly"}
+;         {:uri "/users/9?iso=m%C3%B6ly"})}
 ```