Module: Wayfarer::Routing::DSL

Included in:
Route
Defined in:
lib/wayfarer/routing/dsl.rb

Overview

Routing DSL that declares a tree of Routes. Routing trees decide whether a URL gets processed. Each route has a matcher which is a predicate. Routes are searched depth-first by a PathFinder.

When you call a DSL method on a route, you declare a child route on the route. You can pass a keyword list and a block when you call DSL methods. Keyword lists result in route chains. For example, if you declare:

route.host "example.com", path: ":foo", query: { page: 1 }

The last route with the query matcher is returned, and the hierarchy is host > path > query.

To append multiple child rules, pass a block within which you can call DSL methods to declare child routes:

route.host "example.com" do
  path ":foo"
  query page: 1
end

The query matcher is returned again, but the hierarchy is host > path, host > query.

See Also:

Instance Method Summary collapse

Instance Method Details

#custom {|root, uri, task| ... } ⇒ Wayfarer::Routing::Route

Match URLs dynamically by declaring a route from a block during route evaluation. Custom matchers are passed a transient root route which will be followed. Custom matchers match when their dynamically declared subtree matches the URL.

Examples:

Batch routing

route.custom do |root, _uri, task|
  database_record = Crawl.find_by(batch: task.batch)
  root.host(database_record.hostname_to_crawl).to(:index)
end

Parameters:

  • options (Hash)

Yields:

Yield Parameters:

Returns:



175
176
177
 
# File 'lib/wayfarer/routing/dsl.rb', line 175

def custom(**, &block)
  child_route(Matchers::Custom.new(block), klass: SubRoute, **)
end

#host(host) {|route| ... } ⇒ Wayfarer::Routing::Route

Match hostnames excluding the port number.

  • String is compared literally
  • Regexp is matched against the host

This matcher doesn't collect params.

Examples:

Literal host

route.host("example.com").to(:home)

Regular expression

route.host(/example\.com/) do
  path "users/:id", to: :user
end

Parameters:

  • host (String, Regexp)
  • options (Hash)

Yields:

  • (route)

Returns:



72
73
74
 
# File 'lib/wayfarer/routing/dsl.rb', line 72

def host(host, **, &)
  child_route(Matchers::Host.new(host), **, &)
end

#path(path) {|route| ... } ⇒ Wayfarer::Routing::Route

Match and consume path fragments. You can use Sinatra-style pattern matching to extract data from segments.

This matcher doesn't collect params. A leading slash is enforced on the path string.

Examples:

Capture segment

route.path(":segment").to(:show)

Nested paths

route.path("/").path("foo").path(":id").to(:detail)

Parameters:

  • path (String)
  • options (Hash)

Yields:

  • (route)

Returns:

See Also:



92
93
94
95
96
 
# File 'lib/wayfarer/routing/dsl.rb', line 92

def path(path, **, &)
  path = File.join(File::SEPARATOR, path)

  child_route(Matchers::Path.new(path), **, &)
end

#query(fields) {|route| ... } ⇒ Wayfarer::Routing::Route

Match query parameters.

Each key/value pair must be present at least once; if multiple values occur the last one wins (like Rack).

Supported value types:

  • String - exact match
  • Regexp - regular expression match
  • Integer - exact numeric match
  • Range - inclusive numeric range

This matcher doesn't collect params.

Examples:

Simple parameter

route.query(foo: "bar").to(:index)

Page range

route.query(page: 5..12).to(:index)

Parameters:

  • fields (Hash{Symbol,String => String,Regexp,Integer,Range})
  • options (Hash)

Yields:

  • (route)

Returns:



121
122
123
 
# File 'lib/wayfarer/routing/dsl.rb', line 121

def query(fields, **, &)
  child_route(Matchers::Query.new(fields), **, &)
end

#scheme(scheme) {|route| ... } ⇒ Wayfarer::Routing::Route

Match URL schemes (protocols).

This matcher doesn't collect params.

Examples:

HTTPS vs HTTP

route.scheme(:https).to(:tls)
route.scheme(:http).to(:plain)

Parameters:

  • scheme (String, Symbol)
  • options (Hash)

Yields:

  • (route)

Returns:



137
138
139
 
# File 'lib/wayfarer/routing/dsl.rb', line 137

def scheme(scheme, **, &)
  child_route(Matchers::Scheme.new(scheme), **, &)
end

#to(action) {|route| ... } ⇒ Wayfarer::Routing::TargetRoute

Declares the action for the current route branch. An action is a symbol for an instance method, or a Handler.

In case of conflicting actions for a matching route path, the last matched action takes precedence.

Examples:

Last action wins

route.to(:alpha).to(:beta) # => routes to :beta

Parameters:

Yields:

  • (route)

Returns:



154
155
156
 
# File 'lib/wayfarer/routing/dsl.rb', line 154

def to(action, **, &)
  child_route(nil, action: action, klass: TargetRoute, **, &)
end

#url(url) {|route| ... } ⇒ Wayfarer::Routing::Route

Match URLs exactly.

A trailing slash in +url+ is ignored so "https://example.com" and "https://example.com/" are equivalent.

This matcher doesn't collect params.

Examples:

Match URL exactly

route.url("https://www.iana.org/help/example-domains").to(:index)

Parameters:

  • url (String)
  • options (Hash)

Yields:

  • (route)

Returns:



50
51
52
 
# File 'lib/wayfarer/routing/dsl.rb', line 50

def url(url, **, &)
  child_route(Matchers::URL.new(url), **, &)
end