module Roda::RodaPlugins::SymbolMatchers

  1. lib/roda/plugins/symbol_matchers.rb

The symbol_matchers plugin allows you do define custom regexps to use for specific symbols. For example, if you have a route such as:

r.on :username do |username|
  # ...

By default this will match all nonempty segments. However, if your usernames must be 6-20 characters, and can only contain a-z and 0-9, you can do:

plugin :symbol_matchers
symbol_matcher :username, /([a-z0-9]{6,20})/

Then the route will only if the path is /foobar123, but not if it is /foo, /FooBar123, or /foobar_123.

By default, this plugin sets up the following symbol matchers:


/(\d+)/, a decimal segment


/(.*)/, all remaining characters, if any


/(\w+)/, a alphanumeric segment

If the placeholder_string_matchers plugin is loaded, this feature also applies to placeholders in strings, so the following:

r.on "users/:username" do |username|
  # ...

Would match /users/foobar123, but not /users/foo, /users/FooBar123, or /users/foobar_123.

If using this plugin with the params_capturing plugin, this plugin should be loaded first.

You can provide a block when calling symbol_matcher, and it will be called for all matches to allow for type conversion. The block must return an array:

symbol_matcher(:date, /(\d\d\d\d)-(\d\d)-(\d\d)/) do |y, m, d|
  [, m.to_i, d.to_i)]

route do |r|
  r.on :date do |date|
    # date is an instance of Date

If you have a segment match the passed regexp, but decide during block processing that you do not want to treat it as a match, you can have the block return nil or false. This is useful if you want to make sure you are using valid data:

symbol_matcher(:date, /(\d\d\d\d)-(\d\d)-(\d\d)/) do |y, m, d|
  y = y.to_i
  m = m.to_i
  d = d.to_i
  [, m, d)] if Date.valid_date?(y, m, d)

However, if providing a block to the symbol_matchers plugin, the symbol may not work with the params_capturing plugin.


Public Class

  1. configure
  2. load_dependencies

Public Class methods

[show source]
   # File lib/roda/plugins/symbol_matchers.rb
74 def self.configure(app)
75   app.symbol_matcher(:d, /(\d+)/)
76   app.symbol_matcher(:w, /(\w+)/)
77   app.symbol_matcher(:rest, /(.*)/)
78 end
[show source]
   # File lib/roda/plugins/symbol_matchers.rb
70 def self.load_dependencies(app)
71   app.plugin :_symbol_regexp_matchers
72 end