mustermann 3.0.4 → 4.0.0

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
 
@@ -75,10 +75,21 @@ 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]
+      post_match      = string
+      params         = {}
+      captures       = []
+      named_captures = {}
+
+      patterns.each do |pattern|
+        return unless part = pattern.peek_match(post_match)
+        params.merge!(part.params)
+        named_captures.merge!(part.named_captures)
+        captures.concat(part.captures)
+        post_match = post_match[part.to_s.size..-1]
       end
+
+      matched = string[0, string.size - post_match.size]
+      Match.new(self, string, matched:, params:, captures:, named_captures:, post_match:)
     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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
+require 'mustermann'
 require 'mustermann/ast/expander'
 require 'mustermann/caster'
-require 'mustermann'
 
 module Mustermann
   # Allows fine-grained control over pattern expansion.
@@ -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))
@@ -154,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/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,155 @@
+# frozen_string_literal: true
+
+module Mustermann
+  # The return value of {Mustermann::Pattern#match}, {Mustermann::Pattern#peek_match}, {Mustermann::Set#match}, and similar methods.
+  # Mimics large parts of the MatchData API, but also provides access to the pattern and params hash.
+  class Match
+    # @return [Mustermann::Pattern] the pattern that produced the match
+    attr_reader :pattern
+
+    # @return [String] the string that was matched
+    attr_reader :string
+
+    # @return [Hash] the params hash
+    attr_reader :params
+
+    # @return [Array] the captures array
+    attr_reader :captures
+
+    # @return [Hash] the named captures hash, usually identical to {#params}
+    attr_reader :named_captures
+
+    # @return [String] the post match string
+    attr_reader :post_match
+
+    # @return [String] the pre match string
+    attr_reader :pre_match
+
+    # @return [Regexp, nil] the regular expression that produced the match, if available
+    attr_reader :regexp
+
+    # @overload initialize(pattern, string, **options)
+    #   @param pattern [Mustermann::Pattern] the pattern that produced the match
+    #   @param string [String] the string that was matched
+    #
+    # @overload initialize(match, **options)
+    #   @param match [Mustermann::Match] the match to copy pattern and string from
+    #
+    # @overload initialize(pattern, match, **options)
+    #   @param match [Mustermann::Match, MatchData] the match to copy string from
+    #
+    # @option options [Array]  :captures the captures array
+    # @option options [Hash]   :named_captures the named captures hash
+    # @option options [String] :matched the matched substring (defaults to string for full matches)
+    # @option options [Hash]   :params the params hash
+    # @option options [Regexp] :regexp the regular expression that produced the match
+    # @option options [String] :post_match the post match string
+    # @option options [String] :pre_match the pre match string
+    def initialize(pattern_or_match, string_or_match = nil, matched: nil, params: nil, post_match: nil, pre_match: nil, captures: nil, named_captures: nil, regexp: nil)
+      case pattern_or_match
+      when Mustermann::Match, MatchData then match = pattern_or_match
+      when Mustermann::Pattern          then pattern = pattern_or_match
+      else raise ArgumentError, "first argument must be a Mustermann::Pattern or a MatchData, not #{pattern_or_match.class}"
+      end
+
+      case string_or_match
+      when Mustermann::Match, MatchData then match ||= string_or_match
+      when String                       then string = string_or_match
+      when nil # ignore
+      else raise ArgumentError, "second argument must be a String or a MatchData, not #{string_or_match.class}"
+      end
+
+      @pattern        = pattern        || match&.pattern
+      @string         = string         || match&.string         || ''
+      @params         = params         || match&.params         || {}
+      @post_match     = post_match     || match&.post_match     || ''
+      @pre_match      = pre_match      || match&.pre_match      || ''
+      @captures       = captures       || match&.captures       || @params.values
+      @named_captures = named_captures || match&.named_captures || @params
+      @matched        = matched        || match&.to_s           || @string
+
+      unless @regexp = regexp
+        @regexp = match.regexp if match.respond_to?(:regexp)
+        @regexp ||= pattern.respond_to?(:regexp) ? pattern.regexp : nil
+      end
+    end
+
+    # @return [Array<String>] the names of the named captures
+    def names = named_captures.keys
+
+    # @overload [](key)
+    #   Access named captures by key.
+    #   @param key [String, Symbol] the key to access
+    #   @return the value of the named capture, or nil if not found
+    #
+    # @overload [](index)
+    #   Access captures by index.
+    #   @param index [Integer] the index to access
+    #   @return the value of the capture, or nil if not found
+    #
+    # @overload [](start, length)
+    #   Access multiple captures by index and length.
+    #   @param start [Integer] the starting index to access
+    #   @param length [Integer] the number of captures to access
+    #   @return [Array] the values of the captures
+    #
+    # @overload [](range)
+    #   Access multiple captures by range.
+    #   @param range [Range] the range of indices to access
+    #   @return [Array] the values of the captures
+    def [](key, length = nil)
+      case key
+      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}"
+      end
+    end
+
+    # Deconstructs the match into a hash of the given keys. Useful for pattern matching.
+    # @param keys [Array] the keys to deconstruct
+    # @return [Hash] a hash of the given keys and their corresponding values
+    # @see https://docs.ruby-lang.org/en/4.0/syntax/pattern_matching_rdoc.html
+    def deconstruct_keys(keys) = keys.to_h { |key| [key, self[key]] }
+
+    # @see Object#hash
+    def hash = pattern.hash ^ string.hash ^ params.hash
+
+    # @see Object#eql?
+    def eql?(other)
+      return false unless other.is_a? self.class
+      pattern == other.pattern && string == other.string && params == other.params
+    end
+
+    # Returns the values of the given keys as an array.
+    # @params keys [Array<Symbol, String>] the keys to access
+    # @return [Array] the values of the given keys
+    def values_at(*keys) = keys.map { |key| self[key] }
+
+    # @return [String] the matched substring (like MatchData#to_s)
+    def to_s = @matched
+
+    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

@@ -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,14 +84,15 @@ 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
 
+    # @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#=~
@@ -110,7 +111,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 +164,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, string, matched:, params: {}, 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 +185,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.to_s.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.
     #
@@ -362,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]
@@ -381,6 +368,7 @@ module Mustermann
     # @!visibility private
     def unescape(string, decode = uri_decode)
       return string unless decode and string
+      return string unless string.include?('%')
       @@uri.unescape(string)
     end
 
@@ -392,6 +380,13 @@ module Mustermann
       ALWAYS_ARRAY.include? key
     end
 
+    # @api private
+    # Returns true if params can be used as-is without calling map_param.
+    # Used by Set::Trie to skip building a redundant copy of the params hash.
+    def identity_params?(params)
+      !params.any? { |k, v| v.is_a?(Array) || always_array?(k) || (v.respond_to?(:include?) && v.include?('%')) }
+    end
+
     private :unescape, :map_param, :respond_to_special?
     private_constant :ALWAYS_ARRAY
   end

data/lib/mustermann/rails.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+require 'mustermann'
+require 'mustermann/ast/pattern'
+require 'mustermann/ast/fast_pattern'
+require 'mustermann/versions'
+
+module Mustermann
+  # Rails style pattern implementation.
+  #
+  # @example
+  #   Mustermann.new('/:foo', type: :rails) === '/bar' # => true
+  #
+  # @see Mustermann::Pattern
+  # @see file:README.md#rails Syntax description in the README
+  class Rails < AST::Pattern
+    include AST::FastPattern
+    extend Versions
+    register :rails
+
+    # first parser, no optional parts
+    version('2.3') do
+      on(nil) { |c| unexpected(c) }
+      on(?*)  { |c| node(:named_splat) { scan(/\w+/) } }
+      on(?:)  { |c| node(:capture) { scan(/\w+/) } }
+    end
+
+    # rack-mount
+    version('3.0', '3.1') do
+      on(?))  { |c| unexpected(c) }
+      on(?()  { |c| node(:optional, node(:group) { read unless scan(?)) }) }
+      on(?\\) { |c| node(:char, expect(/./)) }
+    end
+
+    # stand-alone journey
+    version('3.2') do
+      on(?|)  { |c| raise ParseError, "the implementation of | is broken in ActionDispatch, cannot compile compatible pattern" }
+      on(?\\) { |c| node(:char, c) }
+    end
+
+    # embedded journey, broken (ignored) escapes
+    version('4.0', '4.1') { on(?\\) { |c| read } }
+
+    # escapes got fixed in 4.2
+    version('4.2') { on(?\\) { |c| node(:char, expect(/./)) } }
+
+    # 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,14 +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)
@@ -32,17 +55,55 @@ 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)
+    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) = 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, :===, :=~, :match, :names, :named_captures
+    def_delegators :regexp, :===, :=~, :names
+
+    private
+
+    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
 
-    def compile(**options)
-      raise NotImplementedError, 'subclass responsibility'
+    def build_params(match)
+      if @simple_captures
+        params = match.named_captures
+        return params if params.empty? || identity_params?(params)
+        params.each_with_object({}) { |(k, v), h| h[k] = map_param(k, v) }
+      else
+        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
+      end
     end
 
-    private :compile
+    def compile(**options) = raise NotImplementedError, 'subclass responsibility'
   end
 end