File: README.md

package info (click to toggle)
clout-clojure 2.1.2-1
  • links: PTS, VCS
  • area: main
  • in suites: bullseye, buster, sid
  • size: 128 kB
  • ctags: 4
  • sloc: xml: 93; makefile: 24
file content (136 lines) | stat: -rw-r--r-- 2,732 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
# Clout

[![Build Status](https://travis-ci.org/weavejester/clout.svg?branch=master)](https://travis-ci.org/weavejester/clout)

Clout is a library for matching [Ring][1] HTTP requests. It uses the same
routing syntax as used by popular Ruby web frameworks like Ruby on Rails and
Sinatra.

[1]: https://github.com/ring-clojure/ring

## Installation

Add the following to your project.clj dependencies:

```clj
[clout "2.1.2"]
```

## Usage

Require Clout in the normal way:

```clj
(require '[clout.core :as clout])
```

These following examples also make use of the [Ring-Mock][2] library
to generate Ring request maps:

[2]: https://github.com/ring-clojure/ring-mock

```clj
(require '[ring.mock.request :as mock])
```

Routes can match by keyword:

```clj
(clout/route-matches
 "/article/:title"
 (mock/request :get "/article/clojure"))

=> {:title "clojure"}
```

Or with wildcards:

```clj
(clout/route-matches
 "/public/*"
 (mock/request :get "/public/style/screen.css"))
 
=> {:* "style/screen.css"}
```

Clout can also match absolute routes:

```clj
(clout/route-matches
 "http://subdomain.example.com/"
 (mock/request :get "http://subdomain.example.com/"))

=> {}
```
And scheme-relative routes:

```clj
(clout/route-matches
 "//subdomain.example.com/"
 (mock/request :get "http://subdomain.example.com/"))

=> {}

(clout/route-matches
 "//subdomain.example.com/"
 (mock/request :get "https://subdomain.example.com/"))
 
=> {}
```

Clout supports both keywords and wildcards. Keywords (like ":title") will
match any character but the following: `/ . , ; ?`. Wildcards (*) will match
anything.

If a route does not match, nil is returned:

```clj
(clout/route-matches "/products" (mock/request :get "/articles"))

=> nil
```

For additional performance, you can choose to pre-compile a route:

```clj
(def user-route
  (clout/route-compile "/user/:id"))

(clout/route-matches user-route (mock/request :get "/user/10"))

=> {:id "10"}
```

When compiling a route, you can specify a map of regular expressions to use
for different keywords. This allows more specific routing:

```clj
(def user-route
  (clout/route-compile "/user/:id" {:id #"\d+"}))

(clout/route-matches user-route (mock/request :get "/user/10"))

=> {:user "10"}

(clout/route-matches user-route (mock/request :get "/user/jsmith"))

=> nil
```

You can also specify regular expressions inline in braces after the
keyword:

```clj
(def user-route
  (clout/route-compile "/user/:id{\\d+}"))
```

Note that regular expression escape sequences (like `\d`) need to be
double-escaped when placed inline in a string.

## License

Copyright © 2015 James Reeves

Distributed under the Eclipse Public License either version 1.0 or (at
your option) any later version.