mustermann 3.0.4 → 4.0.0

data/lib/mustermann/ast/compiler.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
+
 require 'mustermann/ast/translator'
+require 'mustermann/ast/converters'
 
 module Mustermann
   # @see Mustermann::AST::Pattern
@@ -9,28 +11,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 +72,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
@@ -53,19 +100,51 @@ 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}"}"                    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 { |e| pattern(capture: e, **options) })
+        end
+
+        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 { |c| t.encoded(c, **options) }.join)
+        end
+
+        def from_nil(**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 || '[^/\\?#]'
       end
 
       # @!visibility private
@@ -74,7 +153,7 @@ module Mustermann
         # splats are always non-greedy
         # @!visibility private
         def pattern(**options)
-          constraint || ".*?"
+          constraint || '.*?'
         end
       end
 
@@ -83,11 +162,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 +202,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/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/expander.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 require 'mustermann/ast/translator'
 require 'mustermann/ast/compiler'
-require 'ruby2_keywords'
 
 module Mustermann
   module AST
@@ -12,11 +11,11 @@ module Mustermann
     class Expander < Translator
       raises ExpandError
 
-      translate(Array, &-> (*args) do
+      translate Array do |*args, **options|
         inject(t.pattern) do |pattern, element|
-          t.add_to(pattern, t(element, *args))
+          t.add_to(pattern, t(element, *args, **options))
         end
-      end.ruby2_keywords)
+      end
 
       translate :capture do |**options|
         t.for_capture(node, **options)
@@ -123,7 +122,7 @@ module Mustermann
 
       # @see Mustermann::AST::Translator#expand
       # @!visibility private
-      ruby2_keywords def escape(string, *args)
+      def escape(string, *args, **options)
         return super unless string.respond_to?(:=~)
 
         # URI::Parser is pretty slow, let's not send every string to it, even if it's unnecessary

data/lib/mustermann/ast/fast_pattern.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Mustermann
+  module AST
+    # Mixin for AST::Pattern subclasses that accelerates compilation and AST
+    # construction for "simple" patterns: only static path segments and
+    # unconstrained full-segment captures (e.g. /foo/:bar/baz/:id).
+    # Patterns with optional groups, constraints, or non-default options fall
+    # through to the full AST pipeline.
+    module FastPattern
+      # Matches patterns that consist only of slashes, static segments, and
+      # simple :name captures — no optional groups, no constraints.
+      SIMPLE = /\A(?:\/(?:[a-zA-Z0-9\-_.~]+|:[a-zA-Z_]\w*))+\z/
+
+      # Regexp fragment for each printable ASCII char, matching the same output
+      # as Compiler#encoded with uri_decode: true.
+      ENCODED = (0..127).each_with_object({}) do |byte, h|
+        c   = byte.chr
+        pct = '%%%02X' % byte
+        reps = [c, pct, pct.downcase].uniq
+        h[c] = reps.size == 1 ? Regexp.escape(reps.first) :
+          '(?:%s)' % reps.map { |r| Regexp.escape(r) }.join('|')
+      end.freeze
+
+      SEGMENT_SCAN = %r{(/)|(:[a-zA-Z_]\w*)|([^/:]+)}
+
+      private_constant :SIMPLE, :ENCODED, :SEGMENT_SCAN
+
+      # 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
+        return super unless simple_pattern?
+        ast = self.class.ast_cache.fetch(@string) { build_fast_ast }
+        @param_converters ||= {}
+        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? &&
+          options.fetch(:greedy, true) != false &&
+          uri_decode &&
+          @string.match?(SIMPLE)
+      end
+
+      def compile(**options)
+        return super unless simple_pattern?
+        result = fast_compile
+        @fast_match = true
+        result
+      end
+
+      def fast_compile
+        tokens = @string.scan(SEGMENT_SCAN)
+        src = String.new
+        tokens.each_with_index do |(sep, cap, chars), i|
+          if sep
+            src << '\\/'
+          elsif cap
+            # Mirror the compiler: wrap in atomic group when the next token is a separator.
+            if tokens[i + 1]&.first
+              src << "(?<#{cap[1..]}>(?>[^/\\?#]+))"
+            else
+              src << "(?<#{cap[1..]}>[^/\\?#]+)"
+            end
+          else
+            chars.each_char { |c| src << ENCODED[c] }
+          end
+        end
+        Regexp.new(src)
+      end
+
+      def build_fast_ast
+        nodes = []
+        pos   = 0
+        @string.scan(SEGMENT_SCAN) do |sep, cap, chars|
+          if sep
+            node = Node::Separator.new('/')
+            node.start, node.stop = pos, pos + 1
+            nodes << node
+            pos += 1
+          elsif cap
+            node = Node::Capture.new(cap[1..])
+            node.start, node.stop = pos, pos + cap.length
+            nodes << node
+            pos += cap.length
+          else
+            chars.each_char do |c|
+              node = Node::Char.new(c)
+              node.start, node.stop = pos, pos + 1
+              nodes << node
+              pos += 1
+            end
+          end
+        end
+        root = Node::Root.new
+        root.payload = nodes
+        root.pattern = @string
+        root.start, root.stop = 0, @string.length
+        root
+      end
+    end
+  end
+end

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/parser.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 require 'mustermann/ast/node'
 require 'forwardable'
-require 'ruby2_keywords'
 require 'strscan'
 
 module Mustermann
@@ -65,10 +64,10 @@ module Mustermann
       # @param [Symbol] type node type
       # @return [Mustermann::AST::Node]
       # @!visibility private
-      ruby2_keywords def node(type, *args, &block)
+      def node(type, *args, **options, &block)
         type  = Node[type] unless type.respond_to? :new
         start = pos
-        node  = block ? type.parse(*args, &block) : type.new(*args)
+        node  = block ? type.parse(*args, **options, &block) : type.new(*args, **options)
         min_size(start, pos, node)
       end
 

data/lib/mustermann/ast/pattern.rb

@@ -23,6 +23,11 @@ module Mustermann
       instance_delegate %i[parser compiler transformer validation template_generator param_scanner boundaries] => 'self.class'
       instance_delegate parse: :parser, transform: :transformer, validate: :validation,
         generate_templates: :template_generator, scan_params: :param_scanner, set_boundaries: :boundaries
+      
+      # @api private
+      def self.ast_cache
+        @ast_cache ||= EqualityMap.new
+      end
 
       # @api private
       # @return [#parse] parser object for pattern
@@ -83,16 +88,27 @@ 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
-        @ast_cache ||= EqualityMap.new
-        @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, options) if ast
+        ast
       end
 
       # All AST-based pattern implementations support expanding.
@@ -122,12 +138,18 @@ 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
+      def identity_params?(params)
+        param_converters.empty? && super
       end
 
       private :compile, :parse, :transform, :validate, :generate_templates, :param_converters, :scan_params, :set_boundaries

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/ast/translator.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 require 'mustermann/ast/node'
 require 'mustermann/error'
-require 'ruby2_keywords'
 require 'delegate'
 
 module Mustermann
@@ -40,9 +39,9 @@ module Mustermann
 
         # shorthand for translating a nested object
         # @!visibility private
-        ruby2_keywords def t(*args, &block)
+        def t(*args, **options, &block)
           return translator unless args.any?
-          translator.translate(*args, &block)
+          translator.translate(*args, **options, &block)
         end
 
         # @!visibility private
@@ -105,16 +104,21 @@ 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
 
       # Start the translation dance for a (sub)tree.
       # @!visibility private
-      ruby2_keywords def translate(node, *args, &block)
-        result = decorator_for(node).translate(*args, &block)
+      def translate(node, *args, **options, &block)
+        result = decorator_for(node).translate(*args, **options, &block)
         result = result.node while result.is_a? NodeTranslator
         result
       end