mustermann 3.1.1 → 4.0.0.alpha

data/lib/mustermann/set/linear.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+require 'mustermann/set/match'
+
+module Mustermann
+  class Set
+    class Linear
+      def initialize(set, patterns = [])
+        @set      = set
+        @patterns = patterns
+      end
+
+      def add(pattern)
+        @patterns << pattern
+      end
+
+      def match(string, all: false, peek: false)
+        result = [] if all
+        @patterns.each do |pattern|
+          next unless match = peek ? pattern.peek_match(string) : pattern.match(string)
+          return Match.new(match:, value: @set.values_for_pattern(pattern)&.first) unless all
+          values = @set.values_for_pattern(pattern) || [nil]
+          values.each { |value| result << Match.new(match:, value:) }
+        end
+        result
+      end
+    end
+
+    private_constant :Linear
+  end
+end

data/lib/mustermann/set/match.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+require 'mustermann/match'
+require 'delegate'
+
+module Mustermann
+  class Set
+    class Match < DelegateClass(Mustermann::Match)
+      attr_reader :value
+
+      def initialize(*args, value: nil, match: nil, **options)
+        @value = value
+        super(match || Mustermann::Match.new(*args, **options))
+      end
+    end
+  end
+end

data/lib/mustermann/set/trie.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+require 'mustermann/ast/translator'
+require 'mustermann/set/match'
+
+module Mustermann
+  class Set
+    class Trie
+      class Translator < AST::Translator
+        translate(:node) { |trie, **o| trie[t.compile(node)] }
+        translate(:separator) { |trie, **options| trie[payload] }
+
+        translate(:root) do |trie, **options|
+          leaves = t(payload, trie, **options)
+          if leaves.is_a? Array
+            leaves.each { |leaf| leaf.patterns << t.pattern }
+          else
+            leaves.patterns << t.pattern
+          end
+          leaves
+        end
+
+        translate(:char) do |trie, **options|
+          strings = t.possible_strings(payload)
+          return trie if strings.empty?
+          primary_node = trie[strings.first]
+          strings[1..-1].each { |s| trie.wire(s, primary_node) }
+          primary_node
+        end
+
+        translate(:optional) do |trie, **options|
+          [*t(payload, trie, **options), trie]
+        end
+
+        translate(Array) do |trie, **options|
+          i = 0
+          while i < size
+            element = self[i]
+            if element.is_a? :char or element.is_a? :separator
+              trie = t(element, trie, **options)
+              i += 1
+            elsif element.is_a? :splat and self[i + 1]&.is_a? :separator
+              # Compile splat+separator together so the splat is bounded by the separator,
+              # then continue building the trie for the remaining elements.
+              trie = trie[t.compile(self[i..i + 1])]
+              i += 2
+            elsif element.is_a? :splat or !self[i + 1]&.is_a? :separator
+              return trie[t.compile(self[i..-1])]
+            else
+              trie = t(element, trie, **options)
+              return trie.flat_map { |node| t(self[i + 1..-1], node, **options) } if trie.is_a? Array
+              i += 1
+            end
+          end
+          trie
+        end
+
+        attr_reader :pattern
+
+        def initialize(pattern)
+          @pattern  = pattern
+          @compiler = pattern.compiler.new
+          @options  = pattern.options
+          super()
+        end
+
+        def compile(node, **options) = /\A#{@compiler.translate(node, **@options, **options)}/
+
+        def possible_strings(char)
+          return [] if char.empty?
+          @compiler.class.char_representations(char, **@options.slice(:uri_decode, :space_matches_plus))
+        end
+      end
+
+      attr_reader :patterns, :set, :static, :dynamic
+
+      def initialize(set, patterns = [])
+        @set      = set
+        @patterns = []
+        @dynamic  = {}
+        @static   = {}
+        patterns.each { |pattern| add(pattern) }
+      end
+
+      def [](key)
+        case key
+        when String then @static[key] ||= Trie.new(@set)
+        when Regexp then @dynamic[key] ||= Trie.new(@set)
+        end
+      end
+
+      def wire(string, target)
+        return if string.empty?
+        if string.size == 1
+          @static[string] ||= target
+        else
+          (@static[string[0]] ||= Trie.new(@set)).wire(string[1..-1], target)
+        end
+      end
+
+      def match(string, all: false, peek: false, position: 0, params: {})
+        return build_matches(string, params, all:) if position >= string.size
+        result = [] if all
+
+        if node = @static[string[position]]
+          if nested_result = node.match(string, all:, peek:, position: position + 1, params:)
+            return nested_result unless all
+            result.concat(nested_result)
+          end
+        end
+
+        anchored = {}
+        @dynamic.each do |matcher, node|
+          remaining = string[position..-1]
+          regexp_match = matcher.match(remaining)
+          # Non-greedy patterns (e.g. splat .*?) can match 0 chars on non-empty input, making
+          # no progress. Retry with an end-of-string anchor so they consume the full remainder.
+          if regexp_match&.to_s&.empty? && !remaining.empty?
+            anchored_matcher = anchored[matcher] ||= Regexp.new(matcher.source + '\z')
+            regexp_match = anchored_matcher.match(remaining)
+          end
+          next unless regexp_match
+
+          regexp_match.named_captures.each do |name, value|
+            params = params.dup
+            params[name] = params[name]&.dup || []
+            params[name] << value
+          end
+
+          nested_result = node.match(string, all:, params:, peek:, position: position + regexp_match.to_s.size)
+          return nested_result unless all
+          result.concat(nested_result)
+        end
+
+        if peek
+          matches = build_matches(string[0, position], params, all:, post_match: string[position..])
+          return matches unless all
+          result.concat(matches)
+        end
+
+        result
+      end
+
+      def build_matches(string, params, all: false, **options)
+        result = [] if all
+
+        @patterns.each do |pattern|
+          next if pattern.except_regexp&.match?(string)
+
+          pattern_params = params.to_h do |key, value|
+            value = value.flat_map { |v| pattern.map_param(key, v) }
+            value = value.first if value.size < 2 and not pattern.always_array?(key)
+            [key, value]
+          end
+
+          values = @set.values_for_pattern(pattern) || [nil]
+          values.each do |value|
+            match = Set::Match.new(pattern, string, pattern_params, value:, **options)
+            return match unless all
+            result << match
+          end
+        end
+
+        result
+      end
+
+      def add(pattern)
+        Translator.new(pattern).translate(pattern.to_ast, self)
+      end
+    end
+
+    private_constant :Trie
+  end
+end

data/lib/mustermann/set.rb

@@ -0,0 +1,327 @@
+# frozen_string_literal: true
+require 'mustermann'
+require 'mustermann/expander'
+require 'mustermann/set/cache'
+require 'mustermann/set/linear'
+require 'mustermann/set/trie'
+
+module Mustermann
+  # A collection of patterns that can be matched against strings efficiently.
+  #
+  # Each pattern in the set may be associated with one or more arbitrary values,
+  # such as handler objects or route actions. A single {#match} call returns a
+  # {Set::Match} that provides both the captured parameters and the associated
+  # value for the matched pattern. When the set contains many patterns, an
+  # internal trie (prefix tree) is used to dispatch requests in sub-linear time.
+  #
+  # @example Building a routing table
+  #   require 'mustermann/set'
+  #
+  #   set = Mustermann::Set.new
+  #   set.add('/users/:id',  :users_show)
+  #   set.add('/posts/:id',  :posts_show)
+  #
+  #   m = set.match('/users/42')
+  #   m.value          # => :users_show
+  #   m.params['id']   # => '42'
+  #
+  # @example Constructor shorthand with a hash
+  #   set = Mustermann::Set.new('/users/:id' => :users_show, '/posts/:id' => :posts_show)
+  #
+  # @example Block syntax
+  #   set = Mustermann::Set.new do |s|
+  #     s.add('/users/:id', :users_show)
+  #     s.add('/posts/:id', :posts_show)
+  #   end
+  #
+  # @note Adding patterns via {#add}, {#update}, or {#[]=} is not thread-safe, but matching and expanding is.
+  class Set
+    # Pattern options forwarded to {Mustermann.new} when patterns are created from strings.
+    # @return [Hash]
+    attr_reader :options
+
+    # Creates a new set, optionally pre-populated with patterns.
+    #
+    # Patterns can be supplied as a Hash (pattern → value), a plain String or
+    # Pattern, an Array of any of these, or an existing {Set}. The same forms
+    # are accepted by {#update} and {#add}.
+    #
+    # @example Empty set
+    #   Mustermann::Set.new
+    #
+    # @example Pre-populated from a hash
+    #   Mustermann::Set.new('/users/:id' => :users, '/posts/:id' => :posts)
+    #
+    # @example Imperative block
+    #   Mustermann::Set.new do |s|
+    #     s.add('/users/:id', :users)
+    #   end
+    #
+    # @example Zero-argument block returning a mapping hash
+    #   Mustermann::Set.new { { '/users/:id' => :users } }
+    #
+    # @param mapping [Array] initial patterns or mappings to add
+    # @param additional_values [:raise, :ignore, :append] behavior when extra keys are passed to {#expand};
+    #   defaults to +:raise+
+    # @param options [Hash] pattern options forwarded to {Mustermann.new} (e.g. +type: :rails+)
+    # @raise [ArgumentError] if +additional_values+ is not a recognized behavior symbol
+    def initialize(*mapping, additional_values: :raise, use_trie: 50, use_cache: true, **options, &block)
+      raise ArgumentError, "Illegal value %p for additional_values" % additional_values unless Expander::ADDITIONAL_VALUES.include? additional_values
+      raise ArgumentError, "Illegal value %p for use_trie" % use_trie unless [true, false].include?(use_trie) or use_trie.is_a? Integer
+
+      @use_trie          = use_trie
+      @use_cache         = use_cache
+      @matcher           = nil
+      @mapping           = {}
+      @reverse_mapping   = {}
+      @options           = {}
+      @expanders         = {}
+      @additional_values = additional_values
+
+      options.each do |key, value|
+        if key.is_a? Symbol
+          @options[key] = value
+        else
+          mapping << { key => value }
+        end
+      end
+
+      update(mapping)
+
+      block.arity == 0 ? update(yield) : yield(self) if block
+    end
+
+    # Adds a pattern to the set, optionally associated with one or more values.
+    #
+    # If the pattern is given as a String it will be compiled via {Mustermann.new}
+    # using the set's own options. The pattern must be AST-based (Sinatra, Rails,
+    # and similar types). Plain regexp patterns are not supported.
+    #
+    # Calling +add+ more than once for the same pattern appends additional values
+    # without creating duplicates.
+    #
+    # @example
+    #   set.add('/users/:id', :users)
+    #   set.add('/users/:id', :admin)   # same pattern, second value
+    #
+    # @param pattern [String, Pattern] the pattern to add
+    # @param values [Array] zero or more values to associate with the pattern
+    # @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)
+      pattern = Mustermann.new(pattern, **options)
+      raise ArgumentError, "Non-AST patterns are not supported" unless pattern.respond_to? :to_ast
+
+      if @mapping.key? pattern
+        current = @mapping[pattern]
+      else
+        add_pattern(pattern)
+        current = @mapping[pattern] = []
+      end
+
+      values = [nil] if values.empty?
+
+      values.each do |value|
+        raise ArgumentError, "%p may not be used as a value" % value if Expander::ADDITIONAL_VALUES.include? value
+        raise ArgumentError, "the set itself may not be used as value" if value == self
+        next if current.include? value
+        current << value
+        @reverse_mapping[value] ||= []
+        @reverse_mapping[value] << pattern unless @reverse_mapping[value].include? pattern
+        @expanders[value]&.add(pattern)
+      end
+
+      self
+    end
+
+    # Adds a pattern associated with a value using hash-assignment syntax.
+    # @see #add
+    alias []= add
+
+    # Looks up a value by string or retrieves the first value for a known pattern object.
+    #
+    # When given a String, it is matched against the set and the associated value of the
+    # first matching pattern is returned. When given a {Pattern}, the first value
+    # registered for that exact pattern is returned without matching.
+    #
+    # @example String lookup
+    #   set['/users/42']  # => :users_show (or nil)
+    #
+    # @example Pattern lookup
+    #   pat = Mustermann.new('/users/:id')
+    #   set[pat]          # => :users_show (or nil)
+    #
+    # @param pattern_or_string [String, Pattern]
+    # @return [Object, nil] the associated value, or +nil+ if not found
+    # @raise [ArgumentError] for unsupported argument types
+    def [](pattern_or_string)
+      case pattern_or_string
+      when String  then match(pattern_or_string)&.value
+      when Pattern then values_for_pattern(pattern_or_string)&.first
+      else raise ArgumentError, "unsupported pattern type #{pattern_or_string.class}"
+      end
+    end
+
+    # Matches the string against all patterns in the set and returns the first match.
+    #
+    # @param string [String] the string to match
+    # @return [Set::Match, nil] the first match, or +nil+ if none of the patterns match
+    def match(string) = @matcher&.match(string)
+
+    # Matches the beginning of the string against all patterns and returns the
+    # first prefix match. The unmatched remainder of the string is available via
+    # {Set::Match#post_match}.
+    #
+    # @param string [String]
+    # @return [Set::Match, nil] the first prefix match, or +nil+
+    def peek_match(string) = @matcher&.match(string, peek: true)
+
+    # Matches the string against all patterns and returns every match, one per
+    # (pattern, value) pair, in insertion order.
+    #
+    # @param string [String]
+    # @return [Array<Set::Match>] all matches, or an empty array if none
+    def match_all(string) = @matcher&.match(string, all: true)
+
+    # Matches the beginning of the string against all patterns and returns every
+    # prefix match, one per (pattern, value) pair. The unmatched remainder is
+    # available as {Set::Match#post_match} on each result.
+    #
+    # @param string [String]
+    # @return [Array<Set::Match>] all prefix matches, or an empty array if none
+    def peek_match_all(string) = @matcher&.match(string, all: true, peek: true)
+
+    # Returns a new set that includes all patterns from the receiver plus those
+    # from +mapping+. The receiver is not modified.
+    #
+    # @param mapping [Hash, String, Pattern, Array, Set] patterns to merge in
+    # @return [Set] a new set
+    def merge(mapping) = dup.update(mapping)
+
+    # @!visibility private
+    def initialize_copy(other)
+      @mapping         = other.mapping.transform_values(&:dup)
+      @reverse_mapping = @mapping.each_with_object({}) do |(pattern, values), h|
+        values.each { |value| (h[value] ||= []) << pattern }
+      end
+      @expanders = {}
+      @matcher   = nil
+      @mapping.each_key { |pattern| add_pattern(pattern) }
+    end
+
+    # Adds all patterns from +mapping+ to the set in place and returns +self+.
+    # Aliased as +merge!+.
+    #
+    # Accepts the same argument forms as {#initialize}: a Hash, a String, a
+    # {Pattern}, an Array, or another {Set}.
+    #
+    # @param mapping [Hash, String, Pattern, Array, Set]
+    # @return [self]
+    # @raise [ArgumentError] for unsupported mapping types
+    def update(mapping)
+      case mapping
+      when Set             then mapping.mapping.each { |pattern, values| add(pattern, *values) }
+      when Hash            then mapping.each { |k, v| add(k, v) }
+      when String, Pattern then add(mapping)
+      when Array           then mapping.each { |item| update(item) }
+      else raise ArgumentError, "unsupported mapping type #{mapping.class}"
+      end
+      self
+    end
+
+    alias merge! update
+
+    # Returns all patterns that have been added to the set, in insertion order.
+    # @return [Array<Pattern>]
+    def patterns = @mapping.keys
+
+    # Returns an {Expander} that can generate strings from parameter hashes.
+    #
+    # When called without arguments (or with the set itself as the value) the
+    # expander covers all patterns in the set. Pass a specific value to get an
+    # expander limited to the patterns associated with that value.
+    #
+    # @param value [Object] restricts the expander to patterns associated with
+    #   this value; defaults to the set itself (all patterns)
+    # @return [Mustermann::Expander]
+    def expander(value = self)
+      @expanders[value] ||= begin
+        patterns = value == self ? @mapping.keys : @reverse_mapping[value] || []
+        Mustermann::Expander.new(patterns, additional_values: @additional_values, **options)
+      end
+    end
+
+    # Generates a string from a parameter hash using the patterns in the set.
+    #
+    # When called with just a parameter hash, the first pattern that can be fully
+    # expanded with those keys is used. Pass a value as the first argument to
+    # restrict expansion to the patterns associated with that value. You may also
+    # pass an +additional_values+ behavior symbol (+:raise+, +:ignore+, or
+    # +:append+) as the first argument to override the set's default behavior for
+    # that call.
+    #
+    # @example Expand using any pattern
+    #   set.expand(id: '5')
+    #
+    # @example Expand patterns for a specific value
+    #   set.expand(:users, id: '5')
+    #
+    # @example Override additional_values behavior for one call
+    #   set.expand(:ignore, id: '5', extra: 'ignored')
+    #
+    # @param value [Object, :raise, :ignore, :append] the value whose patterns
+    #   should be used, or an additional_values behavior symbol; defaults to all
+    #   patterns
+    # @param behavior [:raise, :ignore, :append, nil] how to handle extra keys;
+    #   defaults to the set's +additional_values+ setting
+    # @param values [Hash, nil] the parameters to expand
+    # @return [String]
+    # @raise [Mustermann::ExpandError] if no pattern can be expanded with the given keys
+    def expand(value = self, behavior = nil, values = nil)
+      if Expander::ADDITIONAL_VALUES.include? value
+        if behavior.is_a? Hash
+          values   = values ? values.merge(behavior) : behavior
+          behavior = nil
+        elsif behavior and behavior != value
+          raise ArgumentError, "behavior specified multiple times" if behavior
+        end
+        behavior = value
+        value    = self
+      elsif value.is_a? Hash and behavior.nil? and values.nil?
+        values = value
+        value  = self unless @reverse_mapping.key? values
+      end
+      expander(value).expand(behavior || @additional_values, values || {})
+    end
+
+    # @return [Boolean] whether the set contains any pattern associated with the given value
+    def has_value?(value) = @reverse_mapping[value]&.any?
+
+    # @!visibility private
+    def values_for_pattern(pattern) = @mapping[pattern] # :nodoc:
+
+    protected
+
+    attr_reader :mapping
+
+    private
+
+    def add_pattern(pattern)
+      case @use_trie
+      when true
+        @matcher ||= Trie.new(self, @mapping.keys)
+      when Integer
+        if @mapping.size >= @use_trie
+          @matcher = Trie.new(self, @mapping.keys)
+          @use_trie = true
+        end
+      end
+
+      @matcher ||= Linear.new(self, @mapping.keys)
+      @matcher = Cache.new(@matcher) if @use_cache and not @matcher.is_a? Cache
+      @matcher.add(pattern)
+
+      @expanders[self]&.add(pattern)
+    end
+  end
+end

data/lib/mustermann/version.rb

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

data/lib/mustermann.rb

@@ -115,10 +115,4 @@ module Mustermann
   def self.normalized_type(type)
     type.to_s.gsub('-', '_').downcase
   end
-
-  # @!visibility private
-  def self.extend_object(object)
-    return super unless defined? ::Sinatra::Base and object.is_a? Class and object < ::Sinatra::Base
-    require 'mustermann/extension'
-  end
 end

metadata

@@ -1,16 +1,24 @@
 --- !ruby/object:Gem::Specification
 name: mustermann
 version: !ruby/object:Gem::Version
-  version: 3.1.1
+  version: 4.0.0.alpha
 platform: ruby
 authors:
 - Konstantin Haase
+- Kunpei Sakai
+- Patrik Ragnarsson
+- Jordan Owens
 - Zachary Scott
 bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
-description: A library implementing patterns that behave like regular expressions.
+description: |
+  Mustermann is your personal string matching expert. As an expert in the field of strings and patterns,
+  Mustermann keeps its runtime dependencies to a minimum and is fully covered with specs and documentation.
+
+  Given a string pattern, Mustermann will turn it into an object that behaves like a regular expression
+  and has comparable performance characteristics.
 email: sinatrarb@googlegroups.com
 executables: []
 extensions: []
@@ -36,27 +44,34 @@ files:
 - lib/mustermann/equality_map.rb
 - lib/mustermann/error.rb
 - lib/mustermann/expander.rb
-- lib/mustermann/extension.rb
+- lib/mustermann/hybrid.rb
 - lib/mustermann/identity.rb
-- lib/mustermann/mapper.rb
+- lib/mustermann/match.rb
 - lib/mustermann/pattern.rb
-- lib/mustermann/pattern_cache.rb
 - lib/mustermann/rails.rb
 - lib/mustermann/regexp.rb
 - lib/mustermann/regexp_based.rb
 - lib/mustermann/regular.rb
-- lib/mustermann/simple_match.rb
+- lib/mustermann/router.rb
+- lib/mustermann/set.rb
+- lib/mustermann/set/cache.rb
+- lib/mustermann/set/linear.rb
+- lib/mustermann/set/match.rb
+- lib/mustermann/set/trie.rb
 - lib/mustermann/sinatra.rb
 - lib/mustermann/sinatra/parser.rb
 - lib/mustermann/sinatra/safe_renderer.rb
 - lib/mustermann/sinatra/try_convert.rb
-- lib/mustermann/to_pattern.rb
 - lib/mustermann/version.rb
 - lib/mustermann/versions.rb
 homepage: https://github.com/sinatra/mustermann
 licenses:
 - MIT
-metadata: {}
+metadata:
+  bug_tracker_uri: https://github.com/sinatra/mustermann/issues
+  changelog_uri: https://github.com/sinatra/mustermann/blob/main/CHANGELOG.md
+  documentation_uri: https://github.com/sinatra/mustermann/tree/main/mustermann#readme
+  source_code_uri: https://github.com/sinatra/mustermann/tree/main/mustermann
 rdoc_options: []
 require_paths:
 - lib
@@ -64,7 +79,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.7.0
+      version: 3.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="

data/lib/mustermann/extension.rb

@@ -1,3 +0,0 @@
-# frozen_string_literal: true
-
-fail "Mustermann extension for Sinatra has been extracted into its own gem. More information at https://github.com/sinatra/mustermann-sinatra-extension"