mustermann 4.0.0.alpha4 → 4.0.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c45d32932b0745c20363ab0fb0084eb861754482e3c47ed68684cf245f10100f
-  data.tar.gz: edb3fbe54217319a9a059b2a57c74b4e8f7d84cc4721fdb9a78bbf5ed6afa113
+  metadata.gz: cc7122898bc258ae00b79d44d7f81fb78e95da49f2c80000c1d04c69dc68ed7f
+  data.tar.gz: bc039a0b69440d1fc07253be7575f752938476386f08237c8984d9f21145b5ee
 SHA512:
-  metadata.gz: 39c217af2266a0dc8f647dafd1c5772cf10e6f921a9d8ccabdcd29357a1a3dc9991065221f12eacc473af1ca183ac8bbd14dc8eae2d83834b21c81ac55e8ffc4
-  data.tar.gz: f9a2c84244115819b62737f222b3c181ca5c5192e83243387473b3bf07666be8e019a78e591861e55a93579c28ab9e0f63725feddc0b6a61ff01f6f736c29735
+  metadata.gz: 955b763efdad19885a42b27e706509f024329b9ff96707d17198407428fe75b531295cd01dc0e5f2a38aae2458fcd6c2180af98dbe71038e4d24f74a6a1fa67e
+  data.tar.gz: cbc49d4686b678c0f11898c4f5bd91d31d975551bbc6de1ba418de3be1ee3c6a093a4e5caa12edbd3e7bfdb1cfb9239d98b0ecc0fb5d68fa287f8e8f403242e7

data/README.md

@@ -42,7 +42,7 @@ pattern.params('/a/b.c') # => { "prefix" => "a", splat => ["b", "c"] }
 These features are included in the library, but not loaded by default
 
 * **[Pattern Set](#-pattern-set):** A collection of patterns with associated values, designed for building routing tables that dispatch efficiently as the number of routes grows.
-* **Mustermann::Router:** A very basic rack router built on top of `Mustermann::Set` for demonstration purposes. Simple and fast.
+* **Mustermann::Router:** A very basic rack router built on top of `Mustermann::Set` for demonstration purposes or small-footprint routing in Rack middleware. Simple and fast.
 
 <a name="-pattern-types"></a>
 ## Pattern Types
@@ -120,7 +120,7 @@ require 'mustermann'
 
 pattern = Mustermann.new('/:page')
 pattern.match('/')     # => nil
-pattern.match('/home') # => #<MatchData "/home" page:"home">
+pattern.match('/home') # => #<Mustermann::Match>
 pattern =~ '/home'     # => 0
 pattern === '/home'    # => true (this allows using it in case statements)
 
@@ -595,6 +595,99 @@ Mustermann.new('/:id.:ext', capture: { id: /\d+/, ext: ['png', 'jpg'] })
 
 Available POSIX character classes are: `:alnum`, `:alpha`, `:blank`, `:cntrl`, `:digit`, `:graph`, `:lower`, `:print`, `:punct`, `:space`, `:upper`, `:xdigit`, `:word` and `:ascii`.
 
+#### Typed Captures
+
+Certain Ruby classes and named symbols can be passed as a capture value. They constrain what the capture matches **and** automatically convert the captured string in `params` to the appropriate type.
+
+``` ruby
+require 'mustermann'
+require 'date'
+
+# Integer: only matches integers, converts to Integer in params
+pattern = Mustermann.new('/:id', capture: Integer)
+pattern.match('/42')    # matches
+pattern.match('/foo')   # does not match
+pattern.params('/42')   # => { "id" => 42 }
+
+# Float: matches integers and decimals, converts to Float in params
+pattern = Mustermann.new('/:price', capture: Float)
+pattern.params('/3.14') # => { "price" => 3.14 }
+pattern.params('/5')    # => { "price" => 5.0 }
+
+# Symbol: only matches word characters (\w+), converts to Symbol in params
+pattern = Mustermann.new('/:format', capture: Symbol)
+pattern.params('/json')       # => { "format" => :json }
+pattern.match('/with-hyphen') # does not match
+
+# Date: only matches YYYY-MM-DD dates, converts to Date in params
+pattern = Mustermann.new('/:date', capture: Date)
+pattern.params('/2026-04-23') # => { "date" => #<Date: 2026-04-23> }
+pattern.match('/04-23-2026')  # does not match
+
+# Gem::Version: matches version strings, converts to Gem::Version in params
+require 'rubygems/version'
+pattern = Mustermann.new('/:version', capture: Gem::Version)
+pattern.params('/1.2.3') # => { "version" => #<Gem::Version "1.2.3"> }
+```
+
+Lowercase symbol aliases are also available: `:integer`, `:float`, `:symbol`, `:date`, `:version`. They behave identically to their class counterparts:
+
+``` ruby
+pattern = Mustermann.new('/:id', capture: :integer)
+pattern.params('/42') # => { "id" => 42 }
+```
+
+These can be mixed with other capture types in a hash:
+
+``` ruby
+pattern = Mustermann.new('/:id(.:format)?', capture: { id: Integer, format: :slug })
+pattern.params('/42')      # => { "id" => 42, "format" => nil }
+pattern.params('/42.json') # => { "id" => 42, "format" => "json" }
+```
+
+Like all other capture types, these can also be used in an array:
+
+``` ruby
+pattern = Mustermann.new('/score/:score', capture: [Integer, Float])
+pattern.params('/42')   # => { "score" => 42 }
+pattern.params('/3.14') # => { "score" => 3.14 }
+```
+
+#### Other Symbols
+
+The following symbols constrain the capture with a regex but do **not** perform any type conversion — `params` still returns a string:
+
+| Symbol    | Matches |
+|-----------|---------|
+| `:locale` | BCP 47 language tags (`en`, `en-US`, `zh-Hans-CN`) |
+| `:slug`   | Lowercase URL slugs (`hello-world`, `foo-bar-baz`) |
+| `:uuid`   | UUIDs (`f47ac10b-58cc-4372-a567-0e02b2c3d479`, case-insensitive) |
+
+``` ruby
+Mustermann.new('/:lang', capture: :locale).match('/zh-Hans-CN') # matches
+Mustermann.new('/:slug', capture: :slug).match('/Hello')        # does not match
+Mustermann.new('/:id',   capture: :uuid).match('/not-a-uuid')   # does not match
+```
+
+Again, these can be mixed with other capture types in a hash or array:
+
+```ruby
+set = Mustermann::Set.new(capture: { id: [Integer, :uuid], locale: :locale })
+
+set.add("(/:locale)?/:id", :show)
+set.add("/(:locale)?", :index)
+
+# without capture constraints, this would match the :show pattern instead
+match = set.match('/en')
+match.value # => :index
+
+match = set.match('/f47ac10b-58cc-4372-a567-0e02b2c3d479')
+match.value # => :show
+
+match = set.match('/en/12')
+match.value # => :show
+```
+
 <a name="-available-options--except"></a>
 ### `except`
 
@@ -630,10 +723,10 @@ Semi-greedy behavior is not specific to dots, it works with all characters or st
 
 ``` ruby
 pattern = Mustermann.new(':a.:b', greedy: true)
-pattern.match('a.b.c.d') # => #<MatchData a:"a.b.c" b:"d">
+pattern.match('a.b.c.d') # => #<Mustermann::Match>
 
 pattern = Mustermann.new(':a.:b', greedy: false)
-pattern.match('a.b.c.d') # => #<MatchData a:"a" b:"b.c.d">
+pattern.match('a.b.c.d') # => #<Mustermann::Match>
 ```
 
 <a name="-available-options--space_matches_plus"></a>

data/lib/mustermann/ast/compiler.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'mustermann/ast/translator'
+require 'mustermann/ast/converters'
 
 module Mustermann
   # @see Mustermann::AST::Pattern
@@ -99,46 +100,48 @@ module Mustermann
           when Hash   then from_hash(capture, **options)
           when String then from_string(capture, **options)
           when nil    then from_nil(**options)
-          else capture
+          when Regexp then capture
+          when Class  then from_class(capture, **options)
+          else raise CompileError, "invalid capture constraint %p for %p" % [capture, name]
           end
         end
 
         private
 
-        def qualified(string, greedy: true,
-                      **options) "#{string}#{qualifier || "+#{'?' unless greedy}"}"
+        def qualified(string, greedy: true, **options)
+          "#{string}#{qualifier || "+#{'?' unless greedy}"}"
         end
 
-        def with_lookahead(string, lookahead: nil,
-                           **options) lookahead ? "(?:(?!#{lookahead})#{string})" : string
+        def with_lookahead(string, lookahead: nil, **options)
+          lookahead ? "(?:(?!#{lookahead})#{string})" : string
         end
 
-        def from_hash(hash,
-                      **options) pattern(capture: hash[name.to_sym],
-                                         **options)
+        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)
+          Regexp.union(*array.map { |e| pattern(capture: e, **options) })
         end
 
-        def from_symbol(symbol,
-                        **options) qualified(with_lookahead("[[:#{symbol}:]]", **options),
-                                             **options)
+        def from_symbol(symbol, **options)
+          capture, _ = CONVERTERS[symbol]
+          return pattern(capture:, **options) if capture
+          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)
+          Regexp.new(string.chars.map { |c| t.encoded(c, **options) }.join)
         end
 
         def from_nil(**options)
-          qualified(
-            with_lookahead(default(**options), **options), **options
-          )
+          qualified(with_lookahead(default(**options), **options), **options)
+        end
+
+        def from_class(klass, **options)
+          capture, _ = CONVERTERS[klass.name]
+          raise CompileError, "no converter for class %p" % klass unless capture
+          pattern(capture:, **options)
         end
 
         def default(**options) = constraint || '[^/\\?#]'

data/lib/mustermann/ast/converters.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+require "rubygems/version"
+require "date"
+
+module Mustermann
+  module AST
+    CONVERTERS = {
+      "Integer" => [ /-?\d+/,           :to_i   ],
+      "Symbol"  => [ /\w+/,             :to_sym ],
+      "String"  => [ nil,               :to_s   ],
+      "Float"   => [ /-?\d+(?:\.\d+)?/, :to_f   ],
+
+      "Date"    => [
+        /\d{4}-\d{2}-\d{2}/,
+        ->(string) { Date.parse(string) }
+      ],
+
+      "Gem::Version" => [
+        Regexp.new(Gem::Version::VERSION_PATTERN),
+        ->(string) { Gem::Version.new(string) }
+      ],
+
+      locale: [ /(?:[A-Za-z]{2,3}|i)(-[A-Za-z0-9]{1,8})*/ ],
+      slug:   [ /[a-z0-9]+(?:-[a-z0-9]+)*/ ],
+      uuid:   [ /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/i ],
+    }
+
+    CONVERTERS.merge!({
+      integer: CONVERTERS["Integer"],
+      symbol:  CONVERTERS["Symbol"],
+      string:  CONVERTERS["String"],
+      float:   CONVERTERS["Float"],
+      date:    CONVERTERS["Date"],
+      version: CONVERTERS["Gem::Version"],
+    })
+
+    CONVERTERS.freeze
+
+    private_constant :CONVERTERS
+  end
+end

data/lib/mustermann/ast/fast_pattern.rb

@@ -26,17 +26,6 @@ module Mustermann
 
       private_constant :SIMPLE, :ENCODED, :SEGMENT_SCAN
 
-      # Bypasses the generic build_match overhead for simple patterns: uses
-      # MatchData#named_captures directly and avoids match.to_s / post_match /
-      # pre_match calls (all no-ops for \A…\Z anchored regexps).
-      def match(string)
-        return super unless @fast_match
-        return unless match = @regexp.match(string)
-        params = match.named_captures
-        params.transform_values! { |v| unescape(v) } if string.include?('%')
-        Match.new(self, match, params:)
-      end
-
       # Public override: fast path for simple patterns, falls through to super otherwise.
       # Must remain public to match AST::Pattern#to_ast visibility.
       def to_ast
@@ -46,8 +35,24 @@ module Mustermann
         ast
       end
 
+      def params(string = nil)
+        return super unless @fast_match
+        return unless md = @regexp.match(string)
+        result = md.named_captures
+        result.transform_values! { |v| v.include?('%') ? unescape(v) : v } if string.include?('%')
+        result
+      end
+
       private
 
+      def build_match(regexp, string)
+        return super unless @fast_match
+        return unless match = regexp.match(string)
+        params = match.named_captures
+        params.transform_values! { |v| v.include?('%') ? unescape(v) : v } if string.include?('%')
+        Match.new(self, match, params: params)
+      end
+
       def simple_pattern?
         options[:capture].nil?  &&
           options[:except].nil? &&

data/lib/mustermann/ast/param_scanner.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+require 'mustermann/ast/converters'
 require 'mustermann/ast/translator'
 
 module Mustermann
@@ -8,14 +9,45 @@ module Mustermann
     # @see Mustermann::AST::Pattern#to_templates
     class ParamScanner < Translator
       # @!visibility private
-      def self.scan_params(ast)
-        new.translate(ast)
+      def self.scan_params(ast, options)
+        new.translate(ast, options)
       end
 
-      translate(:node)    { t(payload) }
-      translate(Array)    { map { |e| t(e) }.inject(:merge) }
-      translate(Object)   { {} }
-      translate(:capture) { convert ? { name => convert } : {} }
+      translate(:node)             { |o| t(payload, o) }
+      translate(:with_look_ahead)  { |o| t(head, o).merge(t(payload, o)) }
+      translate(Array)             { |o| map { |e| t(e, o) }.inject(:merge) }
+      translate(Object)            { |o| {} }
+
+      class Capture < NodeTranslator
+        register :capture
+
+        def translate(options)
+          return { name => convert } if convert
+          _, converter = converter(options[:capture])
+          converter ? { name => converter } : {}
+        end
+
+        def converter(capture)
+          case capture
+          when Hash   then return converter(capture[name.to_sym])
+          when Class  then regexp, converter = CONVERTERS[capture.name]
+          when Symbol then regexp, converter = CONVERTERS[capture]
+          when Array
+            entries = capture.map { |item| converter(item) }.compact
+            regexp  = Regexp.union(entries.map(&:first))
+
+            entries.map! { |r, c| [/\A#{r}\Z/, c] }
+
+            converter = ->(string) do
+              _, c = entries.find { |r, _| r.match?(string) }
+              c&.call(string) || string
+            end
+          end
+
+          return unless converter
+          [regexp, converter.to_proc]
+        end
+      end
     end
   end
 end

data/lib/mustermann/ast/pattern.rb

@@ -101,13 +101,13 @@ module Mustermann
       # Internal AST representation of pattern.
       # @!visibility private
       def to_ast
-        ast = self.class.ast_cache.fetch(@string) do
+        ast = self.class.ast_cache.fetch([@string, options]) do
           ast   = parse(@string, pattern: self)
           ast &&= transform(ast)
           ast &&= set_boundaries(ast, string: @string)
           validate(ast)
         end
-        @param_converters ||= scan_params(ast) if ast
+        @param_converters ||= scan_params(ast, options) if ast
         ast
       end
 
@@ -138,12 +138,13 @@ module Mustermann
       # @see Mustermann::Pattern#map_param
       def map_param(key, value)
         return super unless param_converters.include? key
-        param_converters[key][super]
+        converted = super
+        converted.nil? ? converted : param_converters[key][converted]
       end
 
       # @!visibility private
       def param_converters
-        @param_converters ||= scan_params(to_ast)
+        @param_converters ||= scan_params(to_ast, options)
       end
 
       # @api private

data/lib/mustermann/ast/transformer.rb

@@ -22,6 +22,13 @@ module Mustermann
         node
       end
 
+      # eliminate redundant optional nodes - this helps avoid regexp warnings
+      translate(:optional) do
+        return t(payload) if payload.is_a? Node[:optional]
+        node.payload = t(payload)
+        node
+      end
+
       # ignore unknown objects on the tree
       translate(Object) { node }
 

data/lib/mustermann/composite.rb

@@ -29,6 +29,11 @@ module Mustermann
       @patterns = patterns.flat_map { |p| patterns_from(p, **options) }
     end
 
+    # @see Mustermann::Pattern#names
+    def names
+      @names ||= patterns.flat_map { |p| p.respond_to?(:names) ? p.names : [] }.uniq
+    end
+
     # @see Mustermann::Pattern#==
     def ==(pattern)
       patterns == patterns_from(pattern)
@@ -79,19 +84,33 @@ module Mustermann
     end
 
     # @return [String] the string representation of the pattern
-    def to_s
-      simple_inspect
-    end
+    def to_s = inspect
 
     # @!visibility private
     def inspect
-      "#<%p:%s>" % [self.class, simple_inspect]
+      "(#{simple_inspect})"
     end
 
     # @!visibility private
     def simple_inspect
-      pattern_strings = patterns.map { |p| p.simple_inspect }
-      "(#{pattern_strings.join(" #{operator} ")})"
+      patterns.map { |p| p.is_a?(Composite) ? p.inspect : p.simple_inspect }.join(" #{operator} ")
+    end
+
+    # @!visibility private
+    def pretty_print(q)
+      q.group(1, "(", ")") do
+        patterns.each_with_index do |pattern, index|
+          unless index == 0
+            q.text " #{operator}"
+            q.breakable " "
+          end
+          if pattern.is_a?(Composite)
+            q.pp pattern
+          else
+            q.text pattern.simple_inspect
+          end
+        end
+      end
     end
 
     # @!visibility private

data/lib/mustermann/concat.rb

@@ -14,8 +14,8 @@ module Mustermann
           concat = (self + patterns.inject(:+))
           concat + other.patterns.slice(patterns.length..-1).inject(:+)
         else
-          return super unless native = native_concat(other)
-          self.class.new(native, **options)
+          native, opts = native_concat(other)
+          native ? self.class.new(native, **options, **opts.to_h) : super
         end
       end
 

data/lib/mustermann/expander.rb

@@ -159,6 +159,23 @@ module Mustermann
       end
     end
 
+    # @!visibility private
+    def inspect
+      return "#<#{self.class.name}>" if @patterns.empty?
+      "#<#{self.class.name}: #{@patterns.map { |p| p.to_s.inspect }.join(", ")}>"
+    end
+
+    # @!visibility private
+    def pretty_print(q)
+      q.text "#<#{self.class.name}"
+      q.group(1, "", ">") do
+        @patterns.each_with_index do |pattern, index|
+          q.breakable(index == 0 ? " " : ", ")
+          q.pp pattern.to_s
+        end
+      end
+    end
+
     # @see Object#==
     def ==(other)
       return false unless other.class == self.class

data/lib/mustermann/match.rb

@@ -74,10 +74,13 @@ module Mustermann
       end
     end
 
+    # @return [Array<String>] the names of the named captures
+    def names = named_captures.keys
+
     # @overload [](key)
-    #   Access params by key.
+    #   Access named captures by key.
     #   @param key [String, Symbol] the key to access
-    #   @return the value of the param, or nil if not found
+    #   @return the value of the named capture, or nil if not found
     #
     # @overload [](index)
     #   Access captures by index.
@@ -96,8 +99,8 @@ module Mustermann
     #   @return [Array] the values of the captures
     def [](key, length = nil)
       case key
-      when String  then params[key]
-      when Symbol  then params[key.to_s]
+      when String  then named_captures[key]
+      when Symbol  then named_captures[key.to_s]
       when Integer then length ? captures[key, length] : captures[key]
       when Range   then captures[key]
       else raise ArgumentError, "key must be a String, Symbol, Integer, or Range, not #{key.class}"
@@ -129,5 +132,24 @@ module Mustermann
 
     alias == eql?
     alias to_h params
+
+    # @!visibility private
+    def inspect
+      params_str = params.map { |k, v| " #{k}:#{v.inspect}" }.join
+      "#<#{self.class.name}: #{@matched.inspect}#{params_str}>"
+    end
+
+    # @!visibility private
+    def pretty_print(q)
+      q.group(1, "#<#{self.class.name}:", ">") do
+        q.breakable
+        q.pp @matched
+        params.each do |key, value|
+          q.breakable
+          q.text("#{key}:")
+          q.pp value
+        end
+      end
+    end
   end
 end

data/lib/mustermann/pattern.rb

@@ -90,6 +90,9 @@ module Mustermann
       Match.new(self, string) if self === string
     end
 
+    # @return [Array<String>] list of named captures in the pattern
+    def names = []
+
     # @param [String] string The string to match against
     # @return [Integer, nil] nil if pattern does not match the string, zero if it does.
     # @see http://ruby-doc.org/core-2.0/Regexp.html#method-i-3D-7E Regexp#=~
@@ -339,6 +342,13 @@ module Mustermann
       method(method).owner != Mustermann::Pattern
     end
 
+    # @!visibility private
+    def pretty_print(q)
+      q.text "#<%p:" % self.class
+      q.pp(@string)
+      q.text ">"
+    end
+
     # @!visibility private
     def inspect
       "#<%p:%p>" % [self.class, @string]

data/lib/mustermann/rails.rb

@@ -45,5 +45,19 @@ module Mustermann
 
     # Rails 5.0 fixes |
     version('5', '6', '7', '8') { on(?|) { |c| node(:or) }}
+
+    # (see Mustermann::Pattern#|)
+    def |(other) = combine(other, :|) { super }
+
+    # (see Mustermann::Pattern#+)
+    def +(other) = combine(other, :+) { super }
+
+    private
+
+    def combine(other, operator)
+      return yield unless hybrid = Mustermann[:hybrid].try_convert(self, **options)
+      native = hybrid.public_send(operator, other)
+      native.is_a?(Composite) ? yield : native
+    end
   end
 end

data/lib/mustermann/regexp_based.rb

@@ -11,15 +11,37 @@ module Mustermann
     attr_reader :regexp
     alias_method :to_regexp, :regexp
 
+    # @api private
+    supported_options :cache
+
     # @param (see Mustermann::Pattern#initialize)
     # @return (see Mustermann::Pattern#initialize)
     # @see (see Mustermann::Pattern#initialize)
     def initialize(string, **options)
+      cache = options.delete(:cache) { true }
+
       super
-      regexp       = compile(**options)
-      @peek_regexp = /\A#{regexp}/
-      @regexp      = /\A#{regexp}\Z/
+      regexp           = compile(**options)
+      @peek_regexp     = /\A#{regexp}/
+      @regexp          = /\A#{regexp}\Z/
       @simple_captures = @regexp.named_captures.none? { |name, positions| positions.size > 1 || always_array?(name) }
+
+      cache_class = ObjectSpace::WeakKeyMap if defined?(ObjectSpace::WeakKeyMap)
+
+      case cache
+      when true
+        @match_cache = cache_class&.new || false
+        @peek_cache  = cache_class&.new || false
+      when false
+        @match_cache = false
+        @peek_cache  = false
+      when Hash
+        @match_cache = cache[:match] || cache_class&.new || false
+        @peek_cache  = cache[:peek]  || cache_class&.new || false
+      else
+        @match_cache = cache.new
+        @peek_cache  = cache.new
+      end
     end
 
     # @param (see Mustermann::Pattern#peek_size)
@@ -33,20 +55,38 @@ module Mustermann
     # @param (see Mustermann::Pattern#peek_match)
     # @return (see Mustermann::Pattern#peek_match)
     # @see (see Mustermann::Pattern#peek_match)
-    def peek_match(string) = build_match(@peek_regexp.match(string))
+    def peek_match(string) = cache_match(@peek_cache, @peek_regexp, string)
 
     # @param (see Mustermann::Pattern#match)
     # @return (see Mustermann::Pattern#match)
     # @see (see Mustermann::Pattern#match)
-    def match(string) = build_match(@regexp.match(string))
+    def match(string) = cache_match(@match_cache, @regexp, string)
+
+    # Extracts params directly from the regexp without allocating a Match object or
+    # populating the match cache — significant GC savings when called in hot loops.
+    # @param (see Mustermann::Pattern#params)
+    # @return (see Mustermann::Pattern#params)
+    def params(string = nil)
+      return unless md = @regexp.match(string)
+      build_params(md)
+    end
 
     extend Forwardable
     def_delegators :regexp, :===, :=~, :names
 
     private
 
-    def build_match(match)
-      return unless match
+    def cache_match(cache, regexp, string)
+      if cache
+        return cache[string] if cache.key?(string)
+        cache[string] = build_match(regexp, string)
+      else
+        build_match(regexp, string)
+      end
+    end
+
+    def build_match(regexp, string)
+      return unless match = regexp.match(string)
       Match.new(self, match, params: build_params(match))
     end
 

data/lib/mustermann/set.rb

@@ -185,6 +185,11 @@ module Mustermann
     # @return [self]
     # @raise [ArgumentError] if the pattern is not AST-based, or if a reserved symbol is used as a value
     def add(pattern, *values)
+      if pattern.is_a? Composite and pattern.operator == :|
+        pattern.patterns.each { |p| add(p, *values) }
+        return self
+      end
+
       pattern = Mustermann.new(pattern, **options)
       raise ArgumentError, "Non-AST patterns are not supported" unless pattern.respond_to? :to_ast
 
@@ -380,6 +385,38 @@ module Mustermann
     # Runs trie optimizations pro-actively and explicitly rather than at match time.
     def optimize! = @matcher&.optimize!
 
+    # @!visibility private
+    def inspect # :nodoc:
+      mapping = @mapping.map do |pattern, values|
+        if values.size > 1 or values.first.is_a? Array
+          "%p => %p" % [pattern.to_s, values]
+        elsif values.first != nil
+          "%p => %p" % [pattern.to_s, values.first]
+        else
+          "%p" % pattern.to_s
+        end
+      end
+      "#<#{self.class.name}: #{mapping.join(", ")}>"
+    end
+
+    # @!visibility private
+    def pretty_print(q) # :nodoc:
+      q.text "#<#{self.class.name}"
+      q.group(1, "", ">") do
+        @mapping.each_with_index do |(pattern, values), index|
+          q.breakable(index == 0 ? " " : ", ")
+          q.pp(pattern.to_s)
+          if values.size > 1 or values.first.is_a? Array
+            q.text " => "
+            q.pp(values)
+          elsif values.first != nil
+            q.text " => "
+            q.pp(values.first)
+          end
+        end
+      end
+    end
+
     protected
 
     attr_reader :mapping

data/lib/mustermann/sinatra/try_convert.rb

@@ -6,24 +6,34 @@ module Mustermann
     class TryConvert < AST::Translator
       # @return [Mustermann::Sinatra, nil]
       # @!visibility private
-      def self.convert(input, **options)
-        new(options).translate(input)
+      def self.convert(type, input, **options)
+        new(type, **options).translate(input)
       end
 
+      # Reserved variable names.
+      # @!visibility private
+      attr_reader :names
+
       # Expected options for the resulting pattern.
       # @!visibility private
       attr_reader :options
 
+      # Expected pattern type for the resulting pattern.
+      # @!visibility private
+      attr_reader :type
+
       # @!visibility private
-      def initialize(options)
+      def initialize(type, names: [], **options)
+        @names   = names
         @options = options
+        @type    = type
       end
 
       # @return [Mustermann::Sinatra]
       # @!visibility private
-      def new(input, escape = false)
+      def new(input, escape: false, **opts)
         input = Mustermann::Sinatra.escape(input) if escape
-        Mustermann::Sinatra.new(input, **options)
+        type.new(input, **opts, **options, ignore_unknown_options: true)
       end
 
       # @return [true, false] whether or not expected pattern should have uri_decode option set
@@ -32,15 +42,43 @@ module Mustermann
         options.fetch(:uri_decode, true)
       end
 
-      translate(Object) { nil               }
-      translate(String) { t.new(self, true) }
+      # @return [true, false] whether or not the given options are compatible with the expected options
+      # @!visibility private
+      def compatible_options?(other_options)
+        other_options.all? do |key, value|
+          case key
+          when :capture then compatible_capture_option?(value)
+          else value == options[key]
+          end
+        end
+      end
 
-      translate(Identity) { t.new(self, true) if uri_decode == t.uri_decode }
-      translate(Sinatra)  { node              if options    == t.options    }
+      # @return [true, false] whether or not the given capture option is compatible with the expected capture option
+      # @!visibility private
+      def compatible_capture_option?(capture)
+        return true if names.empty?
+        case capture
+        when Hash  then capture.all? { |n, o| !names.include?(n.to_s) and compatible_capture_option?(o) }
+        when Array then capture.all? { |o| compatible_capture_option?(o) }
+        else true
+        end
+      end
+
+      translate(Object) { nil }
+      translate(String) { t.new(self, escape: true) }
+      translate(Identity) { t.new(self, escape: true) if uri_decode == t.uri_decode }
+
+      translate(Sinatra) do
+        if node.class == t.type and t.options == options
+          node
+        elsif t.compatible_options? options
+          t.new(to_s, **options)
+        end
+      end
 
       translate AST::Pattern do
-        next unless options == t.options
-        t.new(SafeRenderer.translate(to_ast)) rescue nil
+        next unless t.compatible_options? options
+        t.new(SafeRenderer.translate(to_ast), **options) rescue nil
       end
     end
 

data/lib/mustermann/sinatra.rb

@@ -37,13 +37,13 @@ module Mustermann
     # @return [Mustermann::Sinatra, nil] the converted pattern, if possible
     # @!visibility private
     def self.try_convert(input, **options)
-      TryConvert.convert(input, **options)
+      TryConvert.convert(self, input, **options)
     end
 
     # Creates a pattern that matches any string matching either one of the patterns.
     # If a string is supplied, it is treated as a fully escaped Sinatra pattern.
     #
-    # If the other pattern is also a Sintara pattern, it might join the two to a third
+    # If the other pattern is also a Sinatra pattern, it might join the two to a third
     # sinatra pattern instead of generating a composite for efficiency reasons.
     #
     # This only happens if the sinatra pattern behaves exactly the same as a composite
@@ -59,12 +59,12 @@ module Mustermann
     # @return [Mustermann::Pattern] a composite pattern
     # @see Mustermann::Pattern#|
     def |(other)
-      return super unless converted = self.class.try_convert(other, **options)
-      return super unless converted.names.empty? or names.empty?
-      self.class.new(safe_string + "|" + converted.safe_string, **options)
+      return super unless converted = try_convert(other)
+      return super if converted.names.any? { |name| names.include?(name) }
+      self.class.new(safe_string + "|" + converted.safe_string, **converted.options)
     end
 
-    # Generates a string represenation of the pattern that can safely be used for def interpolation
+    # Generates a string representation of the pattern that can safely be used for def interpolation
     # without changing its semantics.
     #
     # @example
@@ -72,19 +72,41 @@ module Mustermann
     #   unsafe = Mustermann.new("/:name")
     #
     #   Mustermann.new("#{unsafe}bar").params("/foobar") # => { "namebar" => "foobar" }
-    #   Mustermann.new("#{unsafe.safe_string}bar").params("/foobar") # => { "name" => "bar" }
+    #   Mustermann.new("#{unsafe.safe_string}bar").params("/foobar") # => { "name" => "foo" }
     #
-    # @return [String] string representatin of the pattern
+    # @return [String] string representations of the pattern
     def safe_string
       @safe_string ||= SafeRenderer.translate(to_ast)
     end
 
     # @!visibility private
     def native_concat(other)
-      return unless converted = self.class.try_convert(other, **options)
-      safe_string + converted.safe_string
+      return unless converted = try_convert(other)
+      [safe_string + converted.safe_string, converted.options]
     end
 
-    private :native_concat
+    # @!visibility private
+    def normalize_capture(pattern)
+      case capture = pattern.options[:capture]
+      when Hash then capture.slice(*pattern.names.map(&:to_sym))
+      when nil  then {}
+      else pattern.names.to_h { |name| [name.to_sym, capture] }
+      end
+    end
+
+    # @!visibility private
+    def try_convert(other)
+      options = self.options
+
+      if other.is_a? Pattern and other.names.any?
+        capture = normalize_capture(other).merge(normalize_capture(self))
+        capture = nil if capture.empty?
+        options = options.merge(capture:)
+      end
+
+      self.class.try_convert(other, names:, **options)
+    end
+
+    private :native_concat, :normalize_capture, :try_convert
   end
 end

data/lib/mustermann/version.rb

@@ -1,4 +1,4 @@
 # frozen_string_literal: true
 module Mustermann
-  VERSION ||= '4.0.0.alpha4'
+  VERSION ||= '4.0.0.rc1'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mustermann
 version: !ruby/object:Gem::Version
-  version: 4.0.0.alpha4
+  version: 4.0.0.rc1
 platform: ruby
 authors:
 - Konstantin Haase
@@ -29,6 +29,7 @@ files:
 - lib/mustermann.rb
 - lib/mustermann/ast/boundaries.rb
 - lib/mustermann/ast/compiler.rb
+- lib/mustermann/ast/converters.rb
 - lib/mustermann/ast/expander.rb
 - lib/mustermann/ast/fast_pattern.rb
 - lib/mustermann/ast/node.rb