mustermann 3.1.0 → 4.0.0.alpha

data/lib/mustermann/ast/compiler.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 require 'mustermann/ast/translator'
 
 module Mustermann
@@ -9,28 +10,59 @@ module Mustermann
     class Compiler < Translator
       raises CompileError
 
-      # Trivial compilations
-      translate(Array)      { |**o| map { |e| t(e, **o) }.join  }
+      # Compile an array of AST nodes, detecting which captures can safely use
+      # atomic groups.  A capture is safe to atomicize when its very next sibling
+      # is a *path separator* (payload '/'), because every Mustermann capture
+      # character class (Sinatra's [^\/\?#]+, Template's [\w\-\.~%]+, etc.)
+      # excludes '/', so the greedy match naturally stops before '/' and
+      # committing to it atomically never affects correctness.
+      #
+      # More permissive conditions (e.g. end-of-array) are intentionally avoided:
+      # template expressions nest captures inside inner arrays where end-of-array
+      # does NOT mean end-of-pattern, and non-'/' separators (e.g. '.' in
+      # {.a,b,c}) may appear inside the capture character class.
+      #
+      # Splats (.*?) and non-greedy captures are excluded — atomicizing them
+      # would commit to zero or one character and break match resolution.
+      # Strip `atomic:` from incoming options so a parent's value cannot bleed
+      # into siblings; each element's atomicity comes solely from its own context.
+      translate(Array) do |atomic: false, **options|
+        greedy = options.fetch(:greedy, true)
+        each_with_index.map do |element, index|
+          next_sibling = self[index + 1]
+          atomic = greedy &&
+            element.is_a?(:capture) &&
+            !element.is_a?(:splat) &&
+            next_sibling&.is_a?(:separator) &&
+            next_sibling.payload == '/'
+          t(element, **options, atomic: atomic)
+        end.join
+      end
+
       translate(:node)      { |**o| t(payload, **o)             }
       translate(:separator) { |**o| Regexp.escape(payload)      }
-      translate(:optional)  { |**o| "(?:%s)?" % t(payload, **o) }
+      translate(:optional)  { |**o| '(?:%s)?' % t(payload, **o) }
       translate(:char)      { |**o| t.encoded(payload, **o)     }
 
       translate :union do |**options|
-        "(?:%s)" % payload.map { |e| "(?:%s)" % t(e, **options) }.join(?|)
+        '(?:%s)' % payload.map { |e| '(?:%s)' % t(e, **options) }.join('|')
       end
 
       translate :expression do |greedy: true, **options|
         t(payload, allow_reserved: operator.allow_reserved, greedy: greedy && !operator.allow_reserved,
-          parametric: operator.parametric, separator: operator.separator, **options)
+                   parametric: operator.parametric, separator: operator.separator, **options)
       end
 
-      translate :with_look_ahead do |**options|
-        lookahead = each_leaf.inject("") do |ahead, element|
+      translate :with_look_ahead do |atomic: false, **options|
+        greedy = options.fetch(:greedy, true)
+        lookahead = each_leaf.inject('') do |ahead, element|
           ahead + t(element, skip_optional: true, lookahead: ahead, greedy: false, no_captures: true, **options).to_s
         end
         lookahead << (at_end ? '$' : '/')
-        t(head, lookahead: lookahead, **options) + t(payload, **options)
+        # The look-ahead already constrains what the head capture can match, so
+        # it is safe to make it atomic when greedy.  Non-greedy captures rely on
+        # backtracking to extend their match and must not be committed atomically.
+        t(head, **options, lookahead: lookahead, atomic: greedy) + t(payload, **options)
       end
 
       # Capture compilation is complex. :(
@@ -39,9 +71,23 @@ module Mustermann
         register :capture
 
         # @!visibility private
-        def translate(**options)
+        # When +atomic: true+ is passed (set by the Array translator for captures
+        # that are followed only by a separator or end-of-pattern), the compiled
+        # content is wrapped in an atomic group <tt>(?>…)</tt>.  This prevents
+        # Oniguruma from backtracking into characters the capture has already
+        # consumed, giving a measurable speedup on failing matches without
+        # changing the result for any valid input.
+        def translate(atomic: false, **options)
           return pattern(**options) if options[:no_captures]
-          "(?<#{name}>#{translate(no_captures: true, **options)})"
+
+          inner = translate(no_captures: true, **options)
+          # Atomic groups are only safe for pure character-class repetitions.
+          # Captures with an explicit array/hash/string option or a custom
+          # constraint produce alternations that need backtracking to resolve
+          # the correct alternative, so they must not be wrapped atomically.
+          apply_atomic = atomic && options[:capture].nil? && constraint.nil?
+          content = apply_atomic ? "(?>#{inner})" : inner
+          "(?<#{name}>#{content})"
         end
 
         # @return [String] regexp without the named capture
@@ -58,14 +104,44 @@ module Mustermann
         end
 
         private
-          def qualified(string, greedy: true, **options)        "#{string}#{qualifier || "+#{?? unless greedy}"}"                    end
-          def with_lookahead(string, lookahead: nil, **options)  lookahead ? "(?:(?!#{lookahead})#{string})" : string                end
-          def from_hash(hash,     **options)                     pattern(capture: hash[name.to_sym], **options)                      end
-          def from_array(array,   **options)                     Regexp.union(*array.map { |e| pattern(capture: e, **options) })     end
-          def from_symbol(symbol, **options)                     qualified(with_lookahead("[[:#{symbol}:]]", **options), **options)  end
-          def from_string(string, **options)                     Regexp.new(string.chars.map { |c| t.encoded(c, **options) }.join)   end
-          def from_nil(**options)                                qualified(with_lookahead(default(**options), **options), **options) end
-          def default(**options)                                 constraint || "[^/\\?#]"                                            end
+
+        def qualified(string, greedy: true,
+                      **options) "#{string}#{qualifier || "+#{'?' unless greedy}"}"
+        end
+
+        def with_lookahead(string, lookahead: nil,
+                           **options) lookahead ? "(?:(?!#{lookahead})#{string})" : string
+        end
+
+        def from_hash(hash,
+                      **options) pattern(capture: hash[name.to_sym],
+                                         **options)
+        end
+
+        def from_array(array, **options)
+          Regexp.union(*array.map do |e|
+            pattern(capture: e, **options)
+          end)
+        end
+
+        def from_symbol(symbol,
+                        **options) qualified(with_lookahead("[[:#{symbol}:]]", **options),
+                                             **options)
+        end
+
+        def from_string(string, **options)
+          Regexp.new(string.chars.map do |c|
+            t.encoded(c, **options)
+          end.join)
+        end
+
+        def from_nil(**options)
+          qualified(
+            with_lookahead(default(**options), **options), **options
+          )
+        end
+
+        def default(**options) = constraint || '[^/\\?#]'
       end
 
       # @!visibility private
@@ -74,7 +150,7 @@ module Mustermann
         # splats are always non-greedy
         # @!visibility private
         def pattern(**options)
-          constraint || ".*?"
+          constraint || '.*?'
         end
       end
 
@@ -83,11 +159,17 @@ module Mustermann
         register :variable
 
         # @!visibility private
-        def translate(**options)
-          return super(**options) if explode or not options[:parametric]
+        def translate(atomic: false, **options)
+          # Exploded variables expand to `pattern(?:sep pattern)*`.  The engine
+          # must be able to backtrack through that repetition when a following
+          # capture (e.g. the 'b' in {/a*,b}) needs to claim the last segment.
+          # Strip `atomic:` so Capture#translate never wraps the repetition.
+          effective_atomic = atomic && !explode
+          return super(atomic: effective_atomic, **options) if explode or !options[:parametric]
+
           # Remove this line after fixing broken compatibility between 2.1 and 2.2
           options.delete(:parametric) if options.has_key?(:parametric)
-          parametric super(parametric: false, **options)
+          parametric super(atomic: effective_atomic, parametric: false, **options)
         end
 
         # @!visibility private
@@ -117,21 +199,34 @@ module Mustermann
         # @!visibility private
         def register_param(parametric: false, split_params: nil, separator: nil, **options)
           return unless explode and split_params
+
           split_params[name] = { separator: separator, parametric: parametric }
         end
       end
 
+      # @return [Array<String>] all raw string representations of the character (literal + URI-encoded variants)
+      # @!visibility private
+      def self.char_representations(char, uri_decode: true, space_matches_plus: true)
+        if char == ' ' and space_matches_plus
+          @space_and_plus ||= char_representations(' ', space_matches_plus: false) +
+                              char_representations('+', space_matches_plus: false)
+        else
+          @char_representations ||= {}
+          @char_representations[char] ||= begin
+            escaped = URI_PARSER.escape(char, /./)
+            [char, escaped.upcase, escaped.downcase].uniq
+          end
+        end
+      end
+
       # @return [String] Regular expression for matching the given character in all representations
       # @!visibility private
       def encoded(char, uri_decode: true, space_matches_plus: true, **options)
         return Regexp.escape(char) unless uri_decode
-        encoded = escape(char, escape: /./)
-        list    = [escape(char), encoded.downcase, encoded.upcase].uniq.map { |c| Regexp.escape(c) }
-        if char == " "
-          list << encoded('+') if space_matches_plus
-          list << " "
-        end
-        "(?:%s)" % list.join("|")
+
+        '(?:%s)' % self.class.char_representations(char, uri_decode:, space_matches_plus:).map { |c|
+          Regexp.escape(c)
+        }.join('|')
       end
 
       # Compiles an AST to a regular expression.

data/lib/mustermann/ast/pattern.rb

@@ -83,6 +83,16 @@ module Mustermann
         raise error.class, "#{error.message}: #{@string.inspect}", error.backtrace
       end
 
+      # Returns a regexp that matches strings excluded by the +except+ option,
+      # or +nil+ if no +except+ constraint was given. Used by the trie matcher
+      # to filter out excluded strings at leaf nodes.
+      # @return [Regexp, nil]
+      # @!visibility private
+      def except_regexp
+        return unless except_str = options[:except]
+        @except_regexp ||= Regexp.new("\\A#{compiler.new.translate(parse(except_str), no_captures: true, **options.except(:except))}\\z")
+      end
+
       # Internal AST representation of pattern.
       # @!visibility private
       def to_ast

data/lib/mustermann/ast/translator.rb

@@ -104,9 +104,14 @@ module Mustermann
       # @return decorator encapsulating translation
       #
       # @!visibility private
+      def self.factory_for(node_class)
+        @factory_for ||= {}
+        @factory_for[node_class] ||= node_class.ancestors.lazy.filter_map { dispatch_table[_1.name] }.first
+      end
+
       def decorator_for(node)
-        factory = node.class.ancestors.inject(nil) { |d,a| d || self.class.dispatch_table[a.name] }
-        raise error_class, "#{self.class}: Cannot translate #{node.class}" unless factory
+        factory = self.class.factory_for(node.class) or
+          raise error_class, "#{self.class}: Cannot translate #{node.class}"
         factory.new(node, self)
       end
 

data/lib/mustermann/concat.rb

@@ -75,10 +75,16 @@ module Mustermann
 
     # @see Mustermann::Pattern#peek_match
     def peek_match(string)
-      pump(string, initial: SimpleMatch.new) do |pattern, substring|
-        return unless match = pattern.peek_match(substring)
-        [match, match.to_s.size]
+      substring = string
+      params = {}
+
+      patterns.each do |pattern|
+        return unless part = pattern.peek_match(substring)
+        params.merge!(part.params)
+        substring = substring[part.to_s.size..-1]
       end
+
+      Match.new(self, string[0, string.size - substring.size], params, post_match: substring)
     end
 
     # @see Mustermann::Pattern#peek_params

data/lib/mustermann/error.rb

@@ -5,5 +5,6 @@ module Mustermann
     CompileError = Class.new(Error)         # Raised if anything goes wrong while compiling a {Pattern}.
     ParseError   = Class.new(Error)         # Raised if anything goes wrong while parsing a {Pattern}.
     ExpandError  = Class.new(Error)         # Raised if anything goes wrong while expanding a {Pattern}.
+    TrieError    = Class.new(CompileError)  # Raised if anything goes wrong while compiling a {Trie}.
   end
 end

data/lib/mustermann/expander.rb

@@ -13,15 +13,16 @@ module Mustermann
   #
   #   expander.expand(page_id: 58, format: :html5) # => "/pages/58?format=html5"
   class Expander
+    # @!visibility private
+    ADDITIONAL_VALUES = %i[raise ignore append].freeze
+
     attr_reader :patterns, :additional_values, :caster
 
     # @param [Array<#to_str, Mustermann::Pattern>] patterns list of patterns to expand, see {#add}.
     # @param [Symbol] additional_values behavior when encountering additional values, see {#expand}.
     # @param [Hash] options used when creating/expanding patterns, see {Mustermann.new}.
     def initialize(*patterns, additional_values: :raise, **options, &block)
-      unless additional_values == :raise or additional_values == :ignore or additional_values == :append
-        raise ArgumentError, "Illegal value %p for additional_values" % additional_values
-      end
+      raise ArgumentError, "Illegal value %p for additional_values" % additional_values unless ADDITIONAL_VALUES.include? additional_values
 
       @patterns          = []
       @api_expander      = AST::Expander.new
@@ -42,6 +43,10 @@ module Mustermann
     # @return [Mustermann::Expander] the expander
     def add(*patterns)
       patterns.each do |pattern|
+        if pattern.is_a? Expander
+          add(*pattern.patterns)
+          next
+        end
         pattern = Mustermann.new(pattern, **@options)
         if block_given?
           @api_expander.add(yield(pattern))

data/lib/mustermann/hybrid.rb

@@ -0,0 +1,50 @@
+require 'mustermann/sinatra'
+
+module Mustermann
+  # Hybrid pattern type that bridges {Mustermann::Sinatra} and Rails pattern syntax.
+  #
+  # It supports all syntax elements of {Mustermann::Sinatra}, plus URI template-style
+  # placeholders, and changes the semantics of parenthesized groups to match Rails:
+  #
+  # - A group *without* a pipe operator is **implicitly optional**, even without a
+  #   trailing `?`. So `/foo(/bar)` matches both `/foo/bar` and `/foo`.
+  #
+  # - A group *with* a pipe operator is **not** implicitly optional, to avoid the
+  #   ambiguity of `/scope/(a|b)` also matching `/scope/`. Add a trailing `?` to make
+  #   such a group optional explicitly: `/scope/(a|b)?`.
+  #
+  # @example Implicit optional group (no pipe)
+  #   require 'mustermann'
+  #   pattern = Mustermann.new('/foo(/bar)', type: :hybrid)
+  #   pattern === '/foo'     # => true
+  #   pattern === '/foo/bar' # => true
+  #
+  # @example Non-optional group with pipe
+  #   pattern = Mustermann.new('/scope/(a|b)', type: :hybrid)
+  #   pattern === '/scope/a' # => true
+  #   pattern === '/scope/'  # => false
+  #
+  # @example Explicitly optional group with pipe
+  #   pattern = Mustermann.new('/scope/(a|b)?', type: :hybrid)
+  #   pattern === '/scope/'  # => true
+  #
+  # @example Nested implicit optional groups (Rails-style resource routing)
+  #   pattern = Mustermann.new('/:controller(/:action(/:id))', type: :hybrid)
+  #   pattern.params('/posts')        # => { "controller" => "posts" }
+  #   pattern.params('/posts/show')   # => { "controller" => "posts", "action" => "show" }
+  #   pattern.params('/posts/show/1') # => { "controller" => "posts", "action" => "show", "id" => "1" }
+  #
+  # @see Mustermann::Sinatra
+  class Hybrid < Sinatra
+    register :hybrid
+
+    # Parses a parenthesized group. Groups without a pipe operator are wrapped in an
+    # optional node (implicitly optional, Rails style). Groups that do contain a pipe
+    # operator are left as plain groups; append `?` to make them optional explicitly.
+    on("(") do |c|
+      n = node(:group) { read unless scan(?)) }
+      has_or = n.payload.any? { |e| e.is_a?(:or) }
+      has_or && !scan("?") ? n : node(:optional, n)
+    end
+  end
+end

data/lib/mustermann/match.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Mustermann
+  class Match
+    attr_reader :pattern, :string, :params, :post_match, :pre_match
+
+    def initialize(pattern, string, params = {}, post_match: '', pre_match: '')
+      @pattern    = pattern
+      @string     = string.freeze
+      @params     = params.freeze
+      @post_match = post_match.freeze
+      @pre_match  = pre_match.freeze
+    end
+
+    def [](key)
+      case key
+      when String  then params[key]
+      when Symbol  then params[key.to_s]
+      else raise ArgumentError, "key must be a String or Symbol, not #{key.class}"
+      end
+    end
+    
+    def deconstruct_keys(keys) = keys.to_h { |key| [key, self[key]] }
+
+    def hash = pattern.hash ^ string.hash ^ params.hash
+
+    def eql?(other)
+      return false unless other.is_a? self.class
+      pattern == other.pattern && string == other.string && params == other.params
+    end
+
+    def values_at(*keys) = keys.map { |key| self[key] }
+
+    alias == eql?
+    alias to_s string
+    alias to_h params
+
+  end
+end

data/lib/mustermann/pattern.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 require 'mustermann/error'
-require 'mustermann/simple_match'
+require 'mustermann/match'
 require 'mustermann/equality_map'
 require 'uri'
 
@@ -84,12 +84,10 @@ module Mustermann
     end
 
     # @param [String] string The string to match against
-    # @return [MatchData, Mustermann::SimpleMatch, nil] MatchData or similar object if the pattern matches.
-    # @see http://ruby-doc.org/core-2.0/Regexp.html#method-i-match Regexp#match
-    # @see http://ruby-doc.org/core-2.0/MatchData.html MatchData
-    # @see Mustermann::SimpleMatch
+    # @return [Mustermann::Match, nil] the match object if the pattern matches.
+    # @see Mustermann::Match
     def match(string)
-      SimpleMatch.new(string) if self === string
+      Match.new(self, string) if self === string
     end
 
     # @param [String] string The string to match against
@@ -110,7 +108,7 @@ module Mustermann
     # Used by Ruby internally for hashing.
     # @return [Integer] same has value for patterns that are equal
     def hash
-      self.class.hash | @string.hash | options.hash
+      self.class.hash ^ @string.hash ^ options.hash
     end
 
     # Two patterns are considered equal if they are of the same type, have the same pattern string
@@ -163,11 +161,11 @@ module Mustermann
     #   pattern.peek("/Frank/Sinatra") # => #<MatchData "/Frank" name:"Frank">
     #
     # @param [String] string The string to match against
-    # @return [MatchData, Mustermann::SimpleMatch, nil] MatchData or similar object if the pattern matches.
+    # @return [Mustermann::Match, nil] MatchData or similar object if the pattern matches.
     # @see #peek_params
     def peek_match(string)
       matched = peek(string)
-      match(matched) if matched
+      Match.new(self, matched, {}, post_match: string[matched.size..-1]) if matched
     end
 
     # Tries to match the pattern against the beginning of the string (as opposed to the full string).
@@ -184,33 +182,12 @@ module Mustermann
     # @return [Array<Hash, Integer>, nil] Array with params hash and length of substing if matched, nil otherwise
     def peek_params(string)
       match = peek_match(string)
-      [params(captures: match), match.to_s.size] if match
-    end
-
-    # @return [Hash{String: Array<Integer>}] capture names mapped to capture index.
-    # @see http://ruby-doc.org/core-2.0/Regexp.html#method-i-named_captures Regexp#named_captures
-    def named_captures
-      {}
-    end
-
-    # @return [Array<String>] capture names.
-    # @see http://ruby-doc.org/core-2.0/Regexp.html#method-i-names Regexp#names
-    def names
-      []
+      match ? [match.params, match.string.size] : nil
     end
 
     # @param [String] string the string to match against
     # @return [Hash{String: String, Array<String>}, nil] Sinatra style params if pattern matches.
-    def params(string = nil, captures: nil, offset: 0)
-      return unless captures ||= match(string)
-      params   = named_captures.map do |name, positions|
-        values = positions.map { |pos| map_param(name, captures[pos + offset]) }.flatten
-        values = values.first if values.size < 2 and not always_array? name
-        [name, values]
-      end
-
-      Hash[params]
-    end
+    def params(string = nil) = match(string)&.params
 
     # @note This method is only implemented by certain subclasses.
     #

data/lib/mustermann/rails.rb

@@ -42,6 +42,6 @@ module Mustermann
     version('4.2') { on(?\\) { |c| node(:char, expect(/./)) } }
 
     # Rails 5.0 fixes |
-    version('5.0') { on(?|) { |c| node(:or) }}
+    version('5', '6', '7', '8') { on(?|) { |c| node(:or) }}
   end
 end

data/lib/mustermann/regexp_based.rb

@@ -32,17 +32,32 @@ module Mustermann
     # @param (see Mustermann::Pattern#peek_match)
     # @return (see Mustermann::Pattern#peek_match)
     # @see (see Mustermann::Pattern#peek_match)
-    def peek_match(string)
-      @peek_regexp.match(string)
-    end
+    def peek_match(string) = build_match(@peek_regexp.match(string))
+
+    def match(string) = build_match(@regexp.match(string))
+
+    # private
+
+    # def build_match(match)
+    #   return unless match
+    #   Match.new(self, match.string, match.named_captures, post_match: match.post_match, pre_match: match.pre_match)
+    # end
 
     extend Forwardable
-    def_delegators :regexp, :===, :=~, :match, :names, :named_captures
+    def_delegators :regexp, :===, :=~, :names
+
+    private
 
-    def compile(**options)
-      raise NotImplementedError, 'subclass responsibility'
+    def build_match(match)
+      return unless match
+      params = match.regexp.named_captures.to_h do |name, positions|
+        value = positions.size < 2 && !always_array?(name) ? map_param(name, match[name]) :
+          positions.flat_map { |pos| map_param(name, match[pos]) }
+        [name, value]
+      end
+      Match.new(self, match.to_s, params, post_match: match.post_match, pre_match: match.pre_match)
     end
 
-    private :compile
+    def compile(**options) = raise NotImplementedError, 'subclass responsibility'
   end
 end

data/lib/mustermann/router.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+require 'mustermann'
+require 'mustermann/set'
+
+module Mustermann
+  # An extremely simple, Rack-compatible router implementation using {Mustermann::Set} for pattern matching.
+  #
+  # @example Basic usage
+  #   require 'mustermann/router'
+  #
+  #   router = Mustermann::Router.new do
+  #     get "/hello/:name" do |env|
+  #       name = env["mustermann.match"][:name]
+  #       [200, { "Content-Type" => "text/plain" }, ["Hello, #{name}!"]]
+  #     end
+  #   end
+  #
+  #   # in config.ru
+  #   run router
+  #
+  # @example Routing to other applications
+  #   router = Mustermann::Router.new do
+  #     get  "/users",     MyApp::Users::Index
+  #     get  "/users/:id", MyApp::Users::Show
+  #     post "/users",     MyApp::Users::Create
+  #     fallback           MyApp::NotFound
+  #   end
+  #
+  #   router.path_for(MyApp::Users::Show, id: 42) # => "/users/42"
+  #
+  # @example As middleware
+  #   use Mustermann::Router do
+  #     get("/up") { [200, { "Content-Type" => "text/plain" }, ["Up!"]] }
+  #   end
+  #
+  #   run MyApp
+  #
+  # @see Mustermann::Set
+  # @see https://rack.github.io/rack/
+  class Router
+    NOT_FOUND = [404, { "Content-Type" => "text/plain", "X-Cascade" => "pass" }, ["Not found"]].freeze
+    VERBS     = %w[GET HEAD POST PUT PATCH DELETE OPTIONS LINK UNLINK].freeze
+    private_constant :VERBS, :NOT_FOUND
+
+    # Initializes a new router.
+    # @param key [String] The key under which the route match will be stored in the Rack environment hash (default: "mustermann.match").
+    # @param options [Hash] Options to be passed to the Mustermann patterns.
+    def initialize(fallback = nil, key: "mustermann.match", **options, &block)
+      @key      = key
+      @sets     = VERBS.to_h { |verb| [verb, Set.new] }
+      @options  = options
+      @fallback = fallback || ->(env) { NOT_FOUND }
+      instance_exec(&block) if block_given?
+    end
+
+    # @param env [Hash] The Rack environment hash for the request.
+    # @return [Array] The Rack response array (status, headers, body).
+    def call(env)
+      if routes = @sets[env["REQUEST_METHOD"]] and match = routes.match(env["PATH_INFO"] || "/")
+        env = env.merge(@key => match)
+        return match.value.call(env)
+      end
+      @fallback.call(env)
+    end
+
+    def fallback(fallback = nil, &block) = @fallback = fallback || block || @fallback
+
+    # Adds a route for the given verb and pattern, with the given target.
+    #
+    # @note Shorthand methods, like `get`, `post`, etc. dynamically are defined for all supported verbs.
+    #
+    # @param verb [String] HTTP verb (e.g. "GET", "POST")
+    # @param pattern [String, Mustermann::Pattern] Pattern string or Mustermann pattern (e.g. "/users/:id")
+    # @param target [#call, nil] The Rack application or middleware to call when the route matches. Can be passed a block as well.
+    # @yield [env] Block to be used as the target if no explicit target is given.
+    # @yieldparam env [Hash] The Rack environment hash for the request.
+    # @return [void]
+    def route(verb, pattern, target = nil, **options, &block)
+      raise ArgumentError, "need to provide target, :to or a block" unless target || block
+      raise ArgumentError, "unknown verb: #{verb}" unless VERBS.include?(verb)
+      pattern = Mustermann.new(pattern, **@options, **options)
+      @sets[verb].add(pattern, target || block)
+    end
+
+    # Helps generate links
+    #
+    # @param app [#call] The Rack application or middleware for which to generate the path.
+    # @param (see Mustermann::Expander#expand)
+    # @return [String] The generated path.
+    def path_for(app, behavior = nil, params = {})
+      set = @sets.values.find { |s| s.has_value?(app) } || @sets[VERBS.first]
+      set.expand(app, behavior, params)
+    end
+
+    VERBS.each do |verb|
+      define_method(verb.downcase) { |*args, **opts, &block| route(verb, *args, **opts, &block) }
+    end
+  end
+end