mustermann 0.0.1
Sign up to get free protection for your applications and to get access to all the features.
- data/.gitignore +17 -0
- data/.rspec +2 -0
- data/.test_queue_stats +0 -0
- data/.travis.yml +6 -0
- data/Gemfile +2 -0
- data/LICENSE +22 -0
- data/README.md +644 -0
- data/Rakefile +3 -0
- data/bench/capturing.rb +24 -0
- data/bench/simple_vs_sinatra.rb +23 -0
- data/bench/template_vs_addressable.rb +23 -0
- data/lib/mustermann.rb +40 -0
- data/lib/mustermann/ast.rb +403 -0
- data/lib/mustermann/error.rb +14 -0
- data/lib/mustermann/extension.rb +52 -0
- data/lib/mustermann/identity.rb +19 -0
- data/lib/mustermann/pattern.rb +142 -0
- data/lib/mustermann/rails.rb +26 -0
- data/lib/mustermann/regexp_based.rb +30 -0
- data/lib/mustermann/shell.rb +22 -0
- data/lib/mustermann/simple.rb +35 -0
- data/lib/mustermann/simple_match.rb +30 -0
- data/lib/mustermann/sinatra.rb +32 -0
- data/lib/mustermann/template.rb +140 -0
- data/lib/mustermann/version.rb +3 -0
- data/mustermann.gemspec +28 -0
- data/spec/ast_spec.rb +8 -0
- data/spec/extension_spec.rb +153 -0
- data/spec/identity_spec.rb +82 -0
- data/spec/mustermann_spec.rb +0 -0
- data/spec/pattern_spec.rb +16 -0
- data/spec/rails_spec.rb +453 -0
- data/spec/regexp_based_spec.rb +8 -0
- data/spec/shell_spec.rb +108 -0
- data/spec/simple_match_spec.rb +10 -0
- data/spec/simple_spec.rb +236 -0
- data/spec/sinatra_spec.rb +554 -0
- data/spec/support.rb +78 -0
- data/spec/template_spec.rb +814 -0
- metadata +227 -0
data/.gitignore
ADDED
data/.rspec
ADDED
data/.test_queue_stats
ADDED
Binary file
|
data/.travis.yml
ADDED
data/Gemfile
ADDED
data/LICENSE
ADDED
@@ -0,0 +1,22 @@
|
|
1
|
+
Copyright (c) 2013 Konstantin Haase
|
2
|
+
|
3
|
+
Permission is hereby granted, free of charge, to any person
|
4
|
+
obtaining a copy of this software and associated documentation
|
5
|
+
files (the "Software"), to deal in the Software without
|
6
|
+
restriction, including without limitation the rights to use,
|
7
|
+
copy, modify, merge, publish, distribute, sublicense, and/or sell
|
8
|
+
copies of the Software, and to permit persons to whom the
|
9
|
+
Software is furnished to do so, subject to the following
|
10
|
+
conditions:
|
11
|
+
|
12
|
+
The above copyright notice and this permission notice shall be
|
13
|
+
included in all copies or substantial portions of the Software.
|
14
|
+
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
16
|
+
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
|
17
|
+
OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
|
18
|
+
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
|
19
|
+
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
|
20
|
+
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
|
21
|
+
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
|
22
|
+
OTHER DEALINGS IN THE SOFTWARE.
|
data/README.md
ADDED
@@ -0,0 +1,644 @@
|
|
1
|
+
# Mustermann
|
2
|
+
|
3
|
+
[![Build Status](https://travis-ci.org/rkh/mustermann.png?branch=master)](https://travis-ci.org/rkh/mustermann)
|
4
|
+
[![Coverage Status](https://coveralls.io/repos/rkh/mustermann/badge.png?branch=master)](https://coveralls.io/r/rkh/mustermann)
|
5
|
+
[![Code Climate](https://codeclimate.com/github/rkh/mustermann.png)](https://codeclimate.com/github/rkh/mustermann)
|
6
|
+
[![Dependency Status](https://gemnasium.com/rkh/mustermann.png)](https://gemnasium.com/rkh/mustermann)
|
7
|
+
[![Gem Version](https://badge.fury.io/rb/mustermann.png)](http://badge.fury.io/rb/mustermann)
|
8
|
+
|
9
|
+
Welcome to [Mustermann](http://en.wikipedia.org/wiki/List_of_placeholder_names_by_language#German). Mustermann is your personal string matching expert. As an expert in the field of strings and patterns, Mustermann also has no runtime dependencies and is fully covered with specs and documentation.
|
10
|
+
|
11
|
+
Given a string pattern, Mustermann will turn it into an object that behaves like a regular expression and has comparable performance characteristics.
|
12
|
+
|
13
|
+
``` ruby
|
14
|
+
if '/foo/bar' =~ Mustermann.new('/foo/*')
|
15
|
+
puts 'it works!'
|
16
|
+
end
|
17
|
+
|
18
|
+
case 'something.png'
|
19
|
+
when Mustermann.new('foo/*') then puts "prefixed with foo"
|
20
|
+
when Mustermann.new('*.pdf') then puts "it's a PDF"
|
21
|
+
when Mustermann.new('*.png') then puts "it's an image"
|
22
|
+
end
|
23
|
+
```
|
24
|
+
|
25
|
+
Besides being a `Regexp` look-alike, Mustermann also adds a `params` method, that will give you a Sinatra-style hash:
|
26
|
+
|
27
|
+
``` ruby
|
28
|
+
pattern = Mustermann.new('/:prefix/*.*')
|
29
|
+
pattern.params('/a/b.c') # => { "prefix" => "a", splat => ["b", "c"] }
|
30
|
+
```
|
31
|
+
|
32
|
+
It's generally a good idea to reuse pattern objects, since as much computation as possible is happening during object creation, so that the actual matching is quite fast.
|
33
|
+
|
34
|
+
## Types and Options
|
35
|
+
|
36
|
+
You can pass in additional options to take fine grained control over the pattern:
|
37
|
+
|
38
|
+
``` ruby
|
39
|
+
Mustermann.new('/:foo.:bar', capture: :alpha) # :foo and :bar will only match alphabetic character
|
40
|
+
```
|
41
|
+
|
42
|
+
In fact, you can even completely change the pattern type:
|
43
|
+
|
44
|
+
``` ruby
|
45
|
+
Mustermann.new('/**/*.png', type: :shell)
|
46
|
+
```
|
47
|
+
|
48
|
+
The available types are:
|
49
|
+
|
50
|
+
<table>
|
51
|
+
<thead>
|
52
|
+
<tr>
|
53
|
+
<th>Type</th>
|
54
|
+
<th>Description</th>
|
55
|
+
<th>Example</th>
|
56
|
+
<th>Available Options</th>
|
57
|
+
</tr>
|
58
|
+
</thead>
|
59
|
+
<tbody>
|
60
|
+
<tr>
|
61
|
+
<th><a href="#identity"><tt>identity</tt></a></th>
|
62
|
+
<td>URI unescaped input string has to match exactly</td>
|
63
|
+
<td><tt>/image.png</tt></td>
|
64
|
+
<td>
|
65
|
+
<a href="#ignore_unknown_options"><tt>ignore_unknown_options</tt></a>,
|
66
|
+
<a href="#uri_decode"><tt>uri_decode</tt></a>
|
67
|
+
</td>
|
68
|
+
</tr>
|
69
|
+
<tr>
|
70
|
+
<th><a href="#rails"><tt>rails</tt></a></th>
|
71
|
+
<td>Rails style patterns</td>
|
72
|
+
<td><tt>/:slug(.:ext)</tt></td>
|
73
|
+
<td>
|
74
|
+
<a href="#capture"><tt>capture</tt></a>,
|
75
|
+
<a href="#except"><tt>except</tt></a>,
|
76
|
+
<a href="#greedy"><tt>greedy</tt></a>,
|
77
|
+
<a href="#ignore_unknown_options"><tt>ignore_unknown_options</tt></a>,
|
78
|
+
<a href="#space_matches_plus"><tt>space_matches_plus</tt></a>,
|
79
|
+
<a href="#uri_decode"><tt>uri_decode</tt></a>
|
80
|
+
</td>
|
81
|
+
</tr>
|
82
|
+
<tr>
|
83
|
+
<th><a href="#shell"><tt>shell</tt></th>
|
84
|
+
<td>Unix style patterns</td>
|
85
|
+
<td><tt>/*.{png,jpg}</tt></td>
|
86
|
+
<td>
|
87
|
+
<a href="#ignore_unknown_options"><tt>ignore_unknown_options</tt></a>,
|
88
|
+
<a href="#uri_decode"><tt>uri_decode</tt></a>
|
89
|
+
</td>
|
90
|
+
</tr>
|
91
|
+
<tr>
|
92
|
+
<th><a href="#simple"><tt>simple</tt></a></th>
|
93
|
+
<td>Sinatra 1.3 style patterns</td>
|
94
|
+
<td><tt>/:slug.:ext</tt></td>
|
95
|
+
<td>
|
96
|
+
<a href="#greedy"><tt>greedy</tt></a>,
|
97
|
+
<a href="#ignore_unknown_options"><tt>ignore_unknown_options</tt></a>,
|
98
|
+
<a href="#space_matches_plus"><tt>space_matches_plus</tt></a>,
|
99
|
+
<a href="#uri_decode"><tt>uri_decode</tt></a>
|
100
|
+
</td>
|
101
|
+
</tr>
|
102
|
+
<tr>
|
103
|
+
<th><a href="#sinatra"><tt>sinatra</tt></a></th>
|
104
|
+
<td>Sinatra 2.0 style patterns (default)</td>
|
105
|
+
<td><tt>/:slug(.:ext)?</tt></td>
|
106
|
+
<td>
|
107
|
+
<a href="#capture"><tt>capture</tt></a>,
|
108
|
+
<a href="#except"><tt>except</tt></a>,
|
109
|
+
<a href="#greedy"><tt>greedy</tt></a>,
|
110
|
+
<a href="#ignore_unknown_options"><tt>ignore_unknown_options</tt></a>,
|
111
|
+
<a href="#space_matches_plus"><tt>space_matches_plus</tt></a>,
|
112
|
+
<a href="#uri_decode"><tt>uri_decode</tt></a>
|
113
|
+
</td>
|
114
|
+
</tr>
|
115
|
+
<tr>
|
116
|
+
<th><a href="#template"><tt>template</tt></a></th>
|
117
|
+
<td><a href="http://tools.ietf.org/html/rfc6570">URI templates</a></td>
|
118
|
+
<td><tt>/dictionary/{term}</tt></td>
|
119
|
+
<td>
|
120
|
+
<a href="#capture"><tt>capture</tt></a>,
|
121
|
+
<a href="#except"><tt>except</tt></a>,
|
122
|
+
<a href="#greedy"><tt>greedy</tt></a>,
|
123
|
+
<a href="#ignore_unknown_options"><tt>ignore_unknown_options</tt></a>,
|
124
|
+
<a href="#space_matches_plus"><tt>space_matches_plus</tt></a>,
|
125
|
+
<a href="#uri_decode"><tt>uri_decode</tt></a>
|
126
|
+
</td>
|
127
|
+
</tr>
|
128
|
+
</tbody>
|
129
|
+
</table>
|
130
|
+
|
131
|
+
See below for more details.
|
132
|
+
|
133
|
+
## Sinatra Integration
|
134
|
+
|
135
|
+
All patterns implement `match`, which means they can be dropped into Sinatra and other Rack routers:
|
136
|
+
|
137
|
+
``` ruby
|
138
|
+
require 'sinatra'
|
139
|
+
require 'mustermann'
|
140
|
+
|
141
|
+
get Mustermann.new('/:foo') do
|
142
|
+
params[:foo]
|
143
|
+
end
|
144
|
+
```
|
145
|
+
|
146
|
+
In fact, since using this with Sinatra is the main use case, it comes with a build-in extension for **Sinatra 1.x**.
|
147
|
+
|
148
|
+
``` ruby
|
149
|
+
require 'sinatra'
|
150
|
+
require 'mustermann'
|
151
|
+
|
152
|
+
register Mustermann
|
153
|
+
|
154
|
+
# this will use Mustermann rather than the built-in pattern matching
|
155
|
+
get '/:slug(.ext)?' do
|
156
|
+
params[:slug]
|
157
|
+
end
|
158
|
+
```
|
159
|
+
|
160
|
+
### Configuration
|
161
|
+
|
162
|
+
You can change what pattern type you want to use for your app via the `pattern` option:
|
163
|
+
|
164
|
+
``` ruby
|
165
|
+
require 'sinatra/base'
|
166
|
+
require 'mustermann'
|
167
|
+
|
168
|
+
class MyApp < Sinatra::Base
|
169
|
+
register Mustermann
|
170
|
+
set :pattern, type: :shell
|
171
|
+
|
172
|
+
get '/images/*.png' do
|
173
|
+
send_file request.path_info
|
174
|
+
end
|
175
|
+
|
176
|
+
get '/index{.htm,.html,}' do
|
177
|
+
erb :index
|
178
|
+
end
|
179
|
+
end
|
180
|
+
```
|
181
|
+
|
182
|
+
You can use the same setting for options:
|
183
|
+
|
184
|
+
``` ruby
|
185
|
+
require 'sinatra'
|
186
|
+
require 'mustermann'
|
187
|
+
|
188
|
+
register Mustermann
|
189
|
+
set :pattern, capture: { ext: %w[png jpg html txt] }
|
190
|
+
|
191
|
+
get '/:slug(.:ext)?' do
|
192
|
+
# slug will be 'foo' for '/foo.png'
|
193
|
+
# slug will be 'foo.bar' for '/foo.bar'
|
194
|
+
# slug will be 'foo.bar' for '/foo.bar.html'
|
195
|
+
params[:slug]
|
196
|
+
end
|
197
|
+
```
|
198
|
+
|
199
|
+
It is also possible to pass in options to a specific route:
|
200
|
+
|
201
|
+
``` ruby
|
202
|
+
require 'sinatra'
|
203
|
+
require 'mustermann'
|
204
|
+
|
205
|
+
register Mustermann
|
206
|
+
|
207
|
+
get '/:slug(.:ext)?', pattern: { greedy: false } do
|
208
|
+
# slug will be 'foo' for '/foo.png'
|
209
|
+
# slug will be 'foo' for '/foo.bar'
|
210
|
+
# slug will be 'foo' for '/foo.bar.html'
|
211
|
+
params[:slug]
|
212
|
+
end
|
213
|
+
```
|
214
|
+
|
215
|
+
Of course, all of the above can be combined.
|
216
|
+
Moreover, the `capture` and the `except` option can be passed to route directly.
|
217
|
+
And yes, this also works with `before` and `after` filters.
|
218
|
+
|
219
|
+
``` ruby
|
220
|
+
require 'sinatra/base'
|
221
|
+
require 'sinatra/respond_with'
|
222
|
+
require 'mustermann'
|
223
|
+
|
224
|
+
class MyApp < Sinatra::Base
|
225
|
+
register Mustermann, Sinatra::RespondWith
|
226
|
+
set :pattern, capture: { id: /\d+/ } # id will only match digits
|
227
|
+
|
228
|
+
# only capture extensions known to Rack
|
229
|
+
before '*:ext', capture: Rack::Mime::MIME_TYPES.keys do
|
230
|
+
content_type params[:ext] # set Content-Type
|
231
|
+
request.path_info = params[:splat].first # drop the extension
|
232
|
+
end
|
233
|
+
|
234
|
+
get '/:id' do
|
235
|
+
not_found unless page = Page.find params[:id]
|
236
|
+
respond_with(page)
|
237
|
+
end
|
238
|
+
end
|
239
|
+
```
|
240
|
+
|
241
|
+
### Why would I want this?
|
242
|
+
|
243
|
+
* It gives you fine grained control over the pattern matching
|
244
|
+
* Allows you to use different pattern styles in your app
|
245
|
+
* The default is more robust and powerful than the built-in patterns
|
246
|
+
* Sinatra 2.0 will use Mustermann internally
|
247
|
+
* Better exceptions for broken route syntax
|
248
|
+
|
249
|
+
### Why not include this in Sinatra 1.x?
|
250
|
+
|
251
|
+
* It would introduce breaking changes, even though these would be minor
|
252
|
+
* Like Sinatra 2.0, Mustermann requires Ruby 2.0 or newer
|
253
|
+
|
254
|
+
|
255
|
+
## Partial Loading and Thread Safety
|
256
|
+
|
257
|
+
Pattern objects are generally assumed to be thread-safe. You can easily match strings against the same pattern object concurrently.
|
258
|
+
|
259
|
+
Mustermann will only load the pattern implementation you need. For example, `mustermann/rails` is loaded the first time you invoke `Mustermann.new(..., type: :rails)`. This part might not be thread-safe, depending on your Ruby implementation.
|
260
|
+
|
261
|
+
In the common use cases, that is Sinatra and similar, patterns are compiled on the main thread during the application load phase, so this is a non-issue there.
|
262
|
+
|
263
|
+
To avoid this, you can load the pattern types you need manually:
|
264
|
+
|
265
|
+
``` ruby
|
266
|
+
require 'mustermann/sinatra'
|
267
|
+
Mustermann::Sinatra.new('/:foo')
|
268
|
+
```
|
269
|
+
|
270
|
+
## Options
|
271
|
+
|
272
|
+
### `capture`
|
273
|
+
|
274
|
+
Supported by: `rails`, `sinatra`, `template`
|
275
|
+
|
276
|
+
**Sinatra**, **URI template** and **Rails** patterns support changing the way named captures work via the `capture` options.
|
277
|
+
|
278
|
+
Possible values for a capture:
|
279
|
+
|
280
|
+
``` ruby
|
281
|
+
# String: Matches the given string (or any URI encoded version of it)
|
282
|
+
Mustermann.new('/index.:ext', capture: 'png')
|
283
|
+
|
284
|
+
# Regexp: Matches the Regular expression
|
285
|
+
Mustermann.new('/:id', capture: /\d+/)
|
286
|
+
|
287
|
+
# Symbol: Matches POSIX character class
|
288
|
+
Mustermann.new('/:id', capture: :digit)
|
289
|
+
|
290
|
+
# Array of the above: Matches anything in the array
|
291
|
+
Mustermann.new('/:id_or_slug', capture: [/\d+/, :word])
|
292
|
+
|
293
|
+
# Hash of the above: Looks up the hash entry by capture name and uses value for matching
|
294
|
+
Mustermann.new('/:id.:ext', capture: { id: /\d+/, ext: ['png', 'jpg'] })
|
295
|
+
```
|
296
|
+
|
297
|
+
Available POSIX character classes are: `:alnum`, `:alpha`, `:blank`, `:cntrl`, `:digit`, `:graph`, `:lower`, `:print`, `:punct`, `:space`, `:upper`, `:xdigit`, `:word` and `:ascii`.
|
298
|
+
|
299
|
+
### `except`
|
300
|
+
|
301
|
+
Supported by: `rails`, `sinatra`, `template`
|
302
|
+
|
303
|
+
Given you supply a second pattern via the except option. Any string that would match the primary pattern but also matches the except pattern will not result in a successful match. Feel free to read that again. Or just take a look at this example:
|
304
|
+
|
305
|
+
``` ruby
|
306
|
+
pattern = Mustermann.new('/auth/*', except: '/auth/login')
|
307
|
+
pattern === '/auth/dunno' # => true
|
308
|
+
pattern === '/auth/login' # => false
|
309
|
+
```
|
310
|
+
|
311
|
+
Now, as said above, `except` treats the value as a pattern:
|
312
|
+
|
313
|
+
``` ruby
|
314
|
+
pattern = Mustermann.new('/*anything', type: :rails, except: '/*anything.png')
|
315
|
+
pattern === '/foo.jpg' # => true
|
316
|
+
pattern === '/foo.png' # => false
|
317
|
+
```
|
318
|
+
|
319
|
+
### `greedy`
|
320
|
+
|
321
|
+
Supported by: `rails`, `simple`, `sinatra`, `template`. Default value: `true`
|
322
|
+
|
323
|
+
**Simple** patterns are greedy, meaning that for the pattern `:foo:bar?`, everything will be captured as `foo`, `bar` will always be `nil`. By setting `greedy` to `false`, `foo` will capture as little as possible (which in this case would only be the first letter), leaving the rest to `bar`.
|
324
|
+
|
325
|
+
**Sinatra**, **URI template** and **Rails** patterns are semi-greedy. This means `:foo(.:bar)?` (`:foo(.:bar)` for Rails patterns) will capture everything before the *last* dot as `foo`. For these two pattern types, you can switch into non-greedy mode by setting the `greedy` option to false. In that case `foo` will only capture the part before the *first* dot.
|
326
|
+
|
327
|
+
Semi-greedy behavior is not specific to dots, it works with all characters or strings. For instance, `:a(foo:b)` will capture everything before the *last* `foo` as `a`, and `:foo(bar)?` will not capture a `bar` at the end.
|
328
|
+
|
329
|
+
``` ruby
|
330
|
+
pattern = Mustermann.new(':a.:b', greedy: true)
|
331
|
+
pattern.match('a.b.c.d') # => #<MatchData a:"a.b.c" b:"d">
|
332
|
+
|
333
|
+
pattern = Mustermann.new(':a.:b', greedy: false)
|
334
|
+
pattern.match('a.b.c.d') # => #<MatchData a:"a" b:"b.c.d">
|
335
|
+
```
|
336
|
+
|
337
|
+
### `space_matches_plus`
|
338
|
+
|
339
|
+
Supported by: `rails`, `simple`, `sinatra`, `template`. Default value: `true`
|
340
|
+
|
341
|
+
**Sinatra**, **Simple**, **URI template** and **Rails** patterns will by default also match a plus sign for a space in the pattern:
|
342
|
+
|
343
|
+
``` ruby
|
344
|
+
Mustermann.new('a b') === 'a+b' # => true
|
345
|
+
```
|
346
|
+
|
347
|
+
You can disable this behavior via `space_matches_plus`:
|
348
|
+
|
349
|
+
``` ruby
|
350
|
+
Mustermann.new('a b', space_matches_plus: false) === 'a+b' # => false
|
351
|
+
```
|
352
|
+
|
353
|
+
**Important:** This setting has no effect on captures, captures will always keep plus signs as plus sings and spaces as spaces:
|
354
|
+
|
355
|
+
``` ruby
|
356
|
+
pattern = Mustermann.new(':x')
|
357
|
+
pattern.match('a b')[:x] # => 'a b'
|
358
|
+
pattern.match('a+b')[:x] # => 'a+b'
|
359
|
+
````
|
360
|
+
|
361
|
+
### `uri_decode`
|
362
|
+
|
363
|
+
Supported by all patterns. Default value: `true`
|
364
|
+
|
365
|
+
Usually, characters in the pattern will also match the URI encoded version of these characters:
|
366
|
+
|
367
|
+
``` ruby
|
368
|
+
Mustermann.new('a b') === 'a b' # => true
|
369
|
+
Mustermann.new('a b') === 'a%20b' # => true
|
370
|
+
```
|
371
|
+
|
372
|
+
You can avoid this by setting `uri_decode` to `false`:
|
373
|
+
|
374
|
+
``` ruby
|
375
|
+
Mustermann.new('a b', uri_decode: false) === 'a b' # => true
|
376
|
+
Mustermann.new('a b', uri_decode: false) === 'a%20b' # => false
|
377
|
+
```
|
378
|
+
|
379
|
+
### `ignore_unknown_options`
|
380
|
+
|
381
|
+
Supported by all patterns. Default value: `false`
|
382
|
+
|
383
|
+
If you pass an option in that is not supported by the specific pattern type, Mustermann will raise an `ArgumentError`.
|
384
|
+
By setting `ignore_unknown_options` to `true`, it will happily ignore the option.
|
385
|
+
|
386
|
+
## Pattern Types
|
387
|
+
|
388
|
+
### `identity`
|
389
|
+
|
390
|
+
Patterns that are no real patterns, just string matching.
|
391
|
+
|
392
|
+
<table>
|
393
|
+
<thead>
|
394
|
+
<tr>
|
395
|
+
<th>Syntax Element</th>
|
396
|
+
<th>Description</th>
|
397
|
+
</tr>
|
398
|
+
</thead>
|
399
|
+
<tbody>
|
400
|
+
<tr>
|
401
|
+
<td><i>any character</i></td>
|
402
|
+
<td>Matches exactly that character or a URI escaped version of it.</td>
|
403
|
+
</tr>
|
404
|
+
</tbody>
|
405
|
+
</table>
|
406
|
+
|
407
|
+
### `rails`
|
408
|
+
|
409
|
+
Patterns with the syntax used in Rails route definitions.
|
410
|
+
|
411
|
+
<table>
|
412
|
+
<thead>
|
413
|
+
<tr>
|
414
|
+
<th>Syntax Element</th>
|
415
|
+
<th>Description</th>
|
416
|
+
</tr>
|
417
|
+
</thead>
|
418
|
+
<tbody>
|
419
|
+
<tr>
|
420
|
+
<td><b>:</b><i>name</i></td>
|
421
|
+
<td>
|
422
|
+
Captures anything but a forward slash in a semi-greedy fashion. Capture is named <i>name</i>.
|
423
|
+
Capture behavior can be modified with <a href="#capture"><tt>capture</tt></a> and <a href="#greedy"><tt>greedy</tt></a> option.
|
424
|
+
</td>
|
425
|
+
</tr>
|
426
|
+
<tr>
|
427
|
+
<td><b>*</b><i>name</i></td>
|
428
|
+
<td>
|
429
|
+
Captures anything in a non-greedy fashion. Capture is named <i>name</i>.
|
430
|
+
</td>
|
431
|
+
</tr>
|
432
|
+
<tr>
|
433
|
+
<td><b>(</b><i>expression</i><b>)</b></td>
|
434
|
+
<td>Enclosed <i>expression</i> is optional.</td>
|
435
|
+
</tr>
|
436
|
+
<tr>
|
437
|
+
<td><b>/</b></td>
|
438
|
+
<td>
|
439
|
+
Matches forward slash. Does not match URI encoded version of forward slash.
|
440
|
+
</td>
|
441
|
+
</tr>
|
442
|
+
<tr>
|
443
|
+
<td><i>any other character</i></td>
|
444
|
+
<td>Matches exactly that character or a URI encoded version of it.</td>
|
445
|
+
</tr>
|
446
|
+
</tbody>
|
447
|
+
</table>
|
448
|
+
|
449
|
+
### `shell`
|
450
|
+
|
451
|
+
Shell patterns, as used in Bash or with `Dir.glob`.
|
452
|
+
|
453
|
+
<table>
|
454
|
+
<thead>
|
455
|
+
<tr>
|
456
|
+
<th>Syntax Element</th>
|
457
|
+
<th>Description</th>
|
458
|
+
</tr>
|
459
|
+
</thead>
|
460
|
+
<tbody>
|
461
|
+
<tr>
|
462
|
+
<td><b>*</b></td>
|
463
|
+
<td>Matches anything but a slash.</td>
|
464
|
+
</tr>
|
465
|
+
<tr>
|
466
|
+
<td><b>**</b></td>
|
467
|
+
<td>Matches anything.</td>
|
468
|
+
</tr>
|
469
|
+
<tr>
|
470
|
+
<td><b>[</b><i>set</i><b>]</b></td>
|
471
|
+
<td>Matches one character in <i>set</i>.</td>
|
472
|
+
</tr>
|
473
|
+
<tr>
|
474
|
+
<td><b>{</b><i>a</i>,<i>b</i><b>}</b></td>
|
475
|
+
<td>Matches <i>a</i> or <i>b</i>.</td>
|
476
|
+
</tr>
|
477
|
+
<tr>
|
478
|
+
<td><b>\</b><i>x</i></td>
|
479
|
+
<td>Matches <i>x</i> or URI encoded version of <i>x</i>. For instance <tt>\*</tt> matches <tt>*</tt>.</td>
|
480
|
+
</tr>
|
481
|
+
<tr>
|
482
|
+
<td><i>any other character</i></td>
|
483
|
+
<td>Matches exactly that character or a URI encoded version of it.</td>
|
484
|
+
</tr>
|
485
|
+
</tbody>
|
486
|
+
</table>
|
487
|
+
|
488
|
+
### `simple`
|
489
|
+
|
490
|
+
Patterns as used by Sinatra 1.3. Useful for porting an application that relies on this behavior to a later Sinatra version and to make sure [Sinatra 2.0](#sinatra) patterns do not decrease performance.
|
491
|
+
|
492
|
+
<table>
|
493
|
+
<thead>
|
494
|
+
<tr>
|
495
|
+
<th>Syntax Element</th>
|
496
|
+
<th>Description</th>
|
497
|
+
</tr>
|
498
|
+
</thead>
|
499
|
+
<tbody>
|
500
|
+
<tr>
|
501
|
+
<td><b>:</b><i>name</i></td>
|
502
|
+
<td>
|
503
|
+
Captures anything but a forward slash in a greedy fashion. Capture is named <i>name</i>.
|
504
|
+
</td>
|
505
|
+
</tr>
|
506
|
+
<tr>
|
507
|
+
<td><b>*</b></td>
|
508
|
+
<td>
|
509
|
+
Captures anything in a non-greedy fashion. Capture is named splat.
|
510
|
+
It is always an array of captures, as you can use <tt>*</tt> more than once in a pattern.
|
511
|
+
</td>
|
512
|
+
</tr>
|
513
|
+
<tr>
|
514
|
+
<td><i>x</i><b>?</b></td>
|
515
|
+
<td>Makes <i>x</i> optional. For instance <tt>foo?</tt> matches <tt>foo</tt> or <tt>fo</tt>.</td>
|
516
|
+
</tr>
|
517
|
+
<tr>
|
518
|
+
<td><b>/</b></td>
|
519
|
+
<td>
|
520
|
+
Matches forward slash. Does not match URI encoded version of forward slash.
|
521
|
+
</td>
|
522
|
+
</tr>
|
523
|
+
<tr>
|
524
|
+
<td><i>any special character</i></td>
|
525
|
+
<td>Matches exactly that character or a URI encoded version of it.</td>
|
526
|
+
</tr>
|
527
|
+
<tr>
|
528
|
+
<td><i>any other character</i></td>
|
529
|
+
<td>Matches exactly that character.</td>
|
530
|
+
</tr>
|
531
|
+
</tbody>
|
532
|
+
</table>
|
533
|
+
|
534
|
+
### `sinatra`
|
535
|
+
|
536
|
+
Sinatra 2.0 style patterns. The default used by Mustermann.
|
537
|
+
|
538
|
+
<table>
|
539
|
+
<thead>
|
540
|
+
<tr>
|
541
|
+
<th>Syntax Element</th>
|
542
|
+
<th>Description</th>
|
543
|
+
</tr>
|
544
|
+
</thead>
|
545
|
+
<tbody>
|
546
|
+
<tr>
|
547
|
+
<td><b>:</b><i>name</i></td>
|
548
|
+
<td>
|
549
|
+
Captures anything but a forward slash in a semi-greedy fashion. Capture is named <i>name</i>.
|
550
|
+
Capture behavior can be modified with <a href="#capture"><tt>capture</tt></a> and <a href="#greedy"><tt>greedy</tt></a> option.
|
551
|
+
</td>
|
552
|
+
</tr>
|
553
|
+
<tr>
|
554
|
+
<td><b>*</b></td>
|
555
|
+
<td>
|
556
|
+
Captures anything in a non-greedy fashion. Capture is named splat.
|
557
|
+
It is always an array of captures, as you can use <tt>*</tt> more than once in a pattern.
|
558
|
+
</td>
|
559
|
+
</tr>
|
560
|
+
<tr>
|
561
|
+
<td><b>(</b><i>expression</i><b>)</b></td>
|
562
|
+
<td>
|
563
|
+
Enclosed <i>expression</i> is a group. Useful when combined with <tt>?</tt> to make it optional,
|
564
|
+
or to separate two elements that would otherwise be parsed as one.
|
565
|
+
</td>
|
566
|
+
</tr>
|
567
|
+
<tr>
|
568
|
+
<td><i>x</i><b>?</b></td>
|
569
|
+
<td>Makes <i>x</i> optional. For instance <tt>(foo)?</tt> matches <tt>foo</tt> or an empty string.</td>
|
570
|
+
</tr>
|
571
|
+
<tr>
|
572
|
+
<td><b>/</b></td>
|
573
|
+
<td>
|
574
|
+
Matches forward slash. Does not match URI encoded version of forward slash.
|
575
|
+
</td>
|
576
|
+
</tr>
|
577
|
+
<tr>
|
578
|
+
<td><b>\</b><i>x</i></td>
|
579
|
+
<td>Matches <i>x</i> or URI encoded version of <i>x</i>. For instance <tt>\*</tt> matches <tt>*</tt>.</td>
|
580
|
+
</tr>
|
581
|
+
<tr>
|
582
|
+
<td><i>any other character</i></td>
|
583
|
+
<td>Matches exactly that character or a URI encoded version of it.</td>
|
584
|
+
</tr>
|
585
|
+
</tbody>
|
586
|
+
</table>
|
587
|
+
|
588
|
+
### `template`
|
589
|
+
|
590
|
+
Parses fully expanded URI templates as specified by [RFC 6570](http://tools.ietf.org/html/rfc6570).
|
591
|
+
|
592
|
+
Note that it differs from URI templates in that it takes the unescaped version of special character instead of the escaped version.
|
593
|
+
|
594
|
+
<table>
|
595
|
+
<thead>
|
596
|
+
<tr>
|
597
|
+
<th>Syntax Element</th>
|
598
|
+
<th>Description</th>
|
599
|
+
</tr>
|
600
|
+
</thead>
|
601
|
+
<tbody>
|
602
|
+
<tr>
|
603
|
+
<td><b>{</b><i>o</i> <i>var</i> <i>m</i><b>,</b> <i>var</i> <i>m</i><b>,</b> ...<b>}</b></td>
|
604
|
+
<td>
|
605
|
+
Captures expansion.
|
606
|
+
Operator <i>o</i>: <code>+ # . / ; ? &</tt> or none.
|
607
|
+
Modifier <i>m</i>: <code>:num *</tt> or none.
|
608
|
+
</td>
|
609
|
+
</tr>
|
610
|
+
<tr>
|
611
|
+
<td><b>/</b></td>
|
612
|
+
<td>
|
613
|
+
Matches forward slash. Does not match URI encoded version of forward slash.
|
614
|
+
</td>
|
615
|
+
</tr>
|
616
|
+
<tr>
|
617
|
+
<td><i>any other character</i></td>
|
618
|
+
<td>Matches exactly that character or a URI encoded version of it.</td>
|
619
|
+
</tr>
|
620
|
+
</tbody>
|
621
|
+
</table>
|
622
|
+
|
623
|
+
The operators `+` and `#` will always match non-greedy, whereas all other operators match semi-greedy by default.
|
624
|
+
All modifiers and operators are supported. However, it does not parse lists as single values without the *explode* modifier (aka *star*).
|
625
|
+
Parametric operators (`;`, `?` and `&`) currently only match parameters in given order.
|
626
|
+
|
627
|
+
``` ruby
|
628
|
+
pattern = Mustermann.new("{/segments*}/{page}{.ext,cmpr:2}", type: :template)
|
629
|
+
pattern.params("/a/b/c.tar.gz") # => {"segments"=>["a","b"], "page"=>"c", "ext"=>"tar", "cmpr"=>"gz"}
|
630
|
+
```
|
631
|
+
|
632
|
+
Please keep the following in mind:
|
633
|
+
|
634
|
+
> "Some URI Templates can be used in reverse for the purpose of variable matching: comparing the template to a fully formed URI in order to extract the variable parts from that URI and assign them to the named variables. Variable matching only works well if the template expressions are delimited by the beginning or end of the URI or by characters that cannot be part of the expansion, such as reserved characters surrounding a simple string expression. In general, regular expression languages are better suited for variable matching."
|
635
|
+
> — *RFC 6570, Sec 1.5: "Limitations"*
|
636
|
+
|
637
|
+
If you reuse the exact same templates and expose them via an external API meant for expansion,
|
638
|
+
you should set `uri_decode` to `false` in order to conform with the specification.
|
639
|
+
|
640
|
+
If you are looking for an alternative implementation that also supports expanding, check out [addressable](http://addressable.rubyforge.org/).
|
641
|
+
|
642
|
+
## Versioning
|
643
|
+
|
644
|
+
Mustermann follows [Semantic Versioning](http://semver.org/).
|