doc: document match-by-name :url-encode? option

for #778 #519

CHANGELOG.md

@@ -12,6 +12,12 @@ We use [Break Versioning][breakver]. The version numbers follow a `<major>.<mino
 
 [breakver]: https://github.com/ptaoussanis/encore/blob/master/BREAK-VERSIONING.md
 
+## UNRELEASED
+
+* **FIX** redirect-trailing-slash-handler won't make external redirects. [#776](https://github.com/metosin/reitit/pull/776)
+* Allow colons in bracket parameter syntax. [#770](https://github.com/metosin/reitit/pull/770)
+* Add `url-encode?` option to `match-by-name`. [#778](https://github.com/metosin/reitit/pull/778)
+
 ## 0.10.0 (2026-01-09)
 
 * Improve & document how response schemas get picked in per-content-type coercion. See [docs](./doc/ring/coercion.md#per-content-type-coercion). [#745](https://github.com/metosin/reitit/issues/745).

doc/basics/name_based_routing.md

@@ -75,6 +75,17 @@ Path-parameters are automatically coerced into strings, with the help of (curren
 ;        :path-params {:id "1"}}
 ```
 
+In case you want to do something like generate a template path for documentation, you can disable url-encoding:
+
+```clj
+(r/match-by-name router ::user {:id "<id goes here>"} {:url-encode? false})
+; #reitit.core.Match{:template "/api/user/:id"
+;                    :data {:name :user/user}
+;                    :path "/api/user/<id goes here>"
+;                    :result nil
+;                    :path-params {:id "<id goes here>"}}
+```
+
 There is also an exception throwing version:
 
 ```clj
@@ -97,5 +108,5 @@ It can take an optional map of query-parameters too:
 (-> router
     (r/match-by-name ::user {:id 1})
     (r/match->path {:iso "möly"}))
-; "/api/user/1?iso=m%C3%B6ly"    
+; "/api/user/1?iso=m%C3%B6ly"
 ```

modules/reitit-core/src/reitit/core.cljc

@@ -46,7 +46,7 @@
   (options [this])
   (route-names [this])
   (match-by-path [this path])
-  (match-by-name [this name] [this name path-params]))
+  (match-by-name [this name] [this name path-params] [this name path-params opts]))
 
 (defn router? [x]
   (satisfies? Router x))
@@ -122,9 +122,11 @@
        (match-by-name [_ name]
          (if-let [match (impl/fast-get lookup name)]
            (match nil)))
-       (match-by-name [_ name path-params]
+       (match-by-name [r name path-params]
+         (match-by-name r name path-params nil))
+       (match-by-name [_ name path-params opts]
          (if-let [match (impl/fast-get lookup name)]
-           (match (impl/path-params path-params))))))))
+           (match (impl/path-params path-params opts))))))))
 
 (defn lookup-router
   "Creates a lookup-router from resolved routes and optional
@@ -161,9 +163,11 @@
        (match-by-name [_ name]
          (if-let [match (impl/fast-get lookup name)]
            (match nil)))
-       (match-by-name [_ name path-params]
+       (match-by-name [r name path-params]
+         (match-by-name r name path-params nil))
+       (match-by-name [_ name path-params opts]
          (if-let [match (impl/fast-get lookup name)]
-           (match (impl/path-params path-params))))))))
+           (match (impl/path-params path-params opts))))))))
 
 (defn trie-router
   "Creates a special prefix-tree router from resolved routes and optional
@@ -208,9 +212,11 @@
        (match-by-name [_ name]
          (if-let [match (impl/fast-get lookup name)]
            (match nil)))
-       (match-by-name [_ name path-params]
+       (match-by-name [r name path-params]
+         (match-by-name r name path-params nil))
+       (match-by-name [_ name path-params opts]
          (if-let [match (impl/fast-get lookup name)]
-           (match (impl/path-params path-params))))))))
+           (match (impl/path-params path-params opts))))))))
 
 (defn single-static-path-router
   "Creates a fast router of 1 static route(s) and optional
@@ -238,8 +244,10 @@
          (if (#?(:clj .equals :cljs =) p path) match))
        (match-by-name [_ name]
          (if (= n name) match))
-       (match-by-name [_ name path-params]
-         (if (= n name) (impl/fast-assoc match :path-params (impl/path-params path-params))))))))
+       (match-by-name [r name path-params]
+         (match-by-name r name path-params nil))
+       (match-by-name [_ name path-params opts]
+         (if (= n name) (impl/fast-assoc match :path-params (impl/path-params path-params opts))))))))
 
 (defn mixed-router
   "Creates two routers: [[lookup-router]] or [[single-static-path-router]] for
@@ -268,9 +276,11 @@
        (match-by-name [_ name]
          (or (match-by-name static-router name)
              (match-by-name wildcard-router name)))
-       (match-by-name [_ name path-params]
-         (or (match-by-name static-router name path-params)
-             (match-by-name wildcard-router name path-params)))))))
+       (match-by-name [r name path-params]
+         (match-by-name r name path-params nil))
+       (match-by-name [_ name path-params opts]
+         (or (match-by-name static-router name path-params opts)
+             (match-by-name wildcard-router name path-params opts)))))))
 
 (defn quarantine-router
   "Creates two routers: [[mixed-router]] for non-conflicting routes
@@ -299,9 +309,11 @@
        (match-by-name [_ name]
          (or (match-by-name mixed-router name)
              (match-by-name linear-router name)))
-       (match-by-name [_ name path-params]
-         (or (match-by-name mixed-router name path-params)
-             (match-by-name linear-router name path-params)))))))
+       (match-by-name [r name path-params]
+         (match-by-name r name path-params nil))
+       (match-by-name [_ name path-params opts]
+         (or (match-by-name mixed-router name path-params opts)
+             (match-by-name linear-router name path-params opts)))))))
 
 ;;
 ;; Creating Routers

modules/reitit-core/src/reitit/impl.cljc

@@ -297,8 +297,11 @@
 
 (defn path-params
   "Convert parameters' values into URL-encoded strings, suitable for URL paths"
-  [params]
-  (maybe-map-values #(url-encode (into-string %)) params))
+  ([params] (path-params params nil))
+  ([params {:keys [url-encode?] :or {url-encode? true}}]
+   (if url-encode?
+     (maybe-map-values #(url-encode (into-string %)) params)
+     (maybe-map-values #(into-string %) params))))
 
 (defn- query-parameter [k v]
   (str (form-encode (into-string k))

test/cljc/reitit/core_test.cljc

@@ -33,6 +33,12 @@
                      :path "/api/ipa/large"
                      :path-params {:size "large"}})
                    (r/match-by-name router ::beer {:size "large"})))
+            (is (= (r/map->Match
+                    {:template "/api/ipa/:size"
+                     :data {:name ::beer}
+                     :path "/api/ipa/:large"
+                     :path-params {:size ":large"}})
+                   (r/match-by-name router ::beer {:size ":large"} {:url-encode? false})))
             (is (= (r/map->Match
                     {:template "/api/ipa/:size"
                      :data {:name ::beer}

test/cljc/reitit/impl_test.cljc

@@ -41,7 +41,33 @@
                             :u #uuid "c2541900-17a7-4353-9024-db8ac258ba4e"
                             :k :kikka
                             :qk ::kikka
-                            :nil nil}))))
+                            :nil nil})))
+  (is (= {:n "1"
+          :n1 "-1"
+          :n2 "1"
+          :n3 "1"
+          :n4 "1"
+          :n5 "1"
+          :d "2.2"
+          :b "true"
+          :s "kikka"
+          :u "c2541900-17a7-4353-9024-db8ac258ba4e"
+          :k "kikka"
+          :qk "reitit.impl-test/kikka"
+          :nil nil}
+         (impl/path-params {:n 1
+                            :n1 -1
+                            :n2 (long 1)
+                            :n3 (int 1)
+                            :n4 (short 1)
+                            :n5 (byte 1)
+                            :d 2.2
+                            :b true
+                            :s "kikka"
+                            :u #uuid "c2541900-17a7-4353-9024-db8ac258ba4e"
+                            :k :kikka
+                            :qk ::kikka
+                            :nil nil} {:url-encode? false}))))
 
 (deftest query-params-test
   (are [x y]