mustermann 3.0.4 → 4.0.1

data/lib/mustermann/set.rb

@@ -0,0 +1,447 @@
+# frozen_string_literal: true
+require 'mustermann'
+require 'mustermann/expander'
+require 'mustermann/set/cache'
+require 'mustermann/set/linear'
+require 'mustermann/set/strict_order'
+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 use_trie [Boolean, Integer]
+    #   whether to use a trie for matching
+    #   If an Integer is given, it is the number of patterns at which to switch from linear to trie matching.
+    #   Defaults to 50
+    #
+    # @param use_cache [Boolean]
+    #   whether to cache matches not yet garbage collected. Defaults to +true+
+    #
+    # @param strict_order [Boolean]
+    #   whether to match patterns in strict insertion order rather than trie order. Defaults to +false+.
+    #   See {#use_strict_order?} for details
+    #
+    # @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, strict_order: false, **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
+      @strict_order      = strict_order
+
+      options.each do |key, value|
+        if key.is_a? Symbol
+          @options[key] = value
+        else
+          mapping << { key => value }
+        end
+      end
+
+      @options = Mustermann.dedup(@options)
+
+      update(mapping)
+
+      block.arity == 0 ? update(yield) : yield(self) if block
+
+      optimize!
+    end
+
+    # A set can match patterns and values in loose or strict insertion order.
+    #
+    # You have the following guarantees without strict ordering:
+    # - Patterns with dynamic segments in the same position and equal static parts will always match in the order they were added.
+    # - Multiple values for the same pattern will retain their insertion order in regards to that pattern.
+    #
+    # Trade-offs without strict ordering:
+    # - Static segments may be favored over dynamic segments. If you want to guarantee this behavior, enable trie-mode proactively.
+    # - When a pattern has multiple values, these will follow each other directly when using {#match_all} or {#peek_match_all}.
+    # 
+    # Strict ordering comes with both a performance overhead and marginally increased memory usage.
+    # How big the performance overhead is depends on the number of patterns that overlap in the strings they successfully match against.
+    # It does use Ruby's built-in sorting, which on MRI is based on quicksort. The memory overhead grows linear with the number
+    # of pattern and value combinations, but is generally small compared to the memory used by the patterns and values themselves.
+    # 
+    # With strict ordering enabled, patterns and values are guaranteed to occur in insertion order.
+    #
+    # @example Without strict ordering, not using a trie
+    #   set = Mustermann::Set.new(use_trie: false)
+    # 
+    #   set.add("/:path",  :first)
+    #   set.add("/static", :second)
+    #   set.add("/:path",  :third)
+    #
+    #   set.match("/static").value             # => :first
+    #   set.match_all("/static").map(&:value)  # => [:first, :third, :second]
+    #
+    # @example Without strict ordering, using a trie
+    #   set = Mustermann::Set.new(use_trie: true)
+    #
+    #   set.add("/:path",  :first)
+    #   set.add("/static", :second)
+    #   set.add("/:path",  :third)
+    #   
+    #   set.match("/static").value             # => :second
+    #   set.match_all("/static").map(&:value)  # => [:second, :first, :third]
+    #
+    # @example With strict ordering
+    #   set = Mustermann::Set.new(strict_order: true)
+    #   
+    #   set.add("/:path",  :first)
+    #   set.add("/static", :second)
+    #   set.add("/:path",  :third)
+    #   
+    #   set.match("/static").value             # => :first
+    #   set.match_all("/static").map(&:value)  # => [:first, :second, :third]
+    #
+    # @return [Boolean] whether matching happens in strict pattern/value insertion order
+    def strict_order? = @strict_order
+    
+    # @return [Boolean] whether caching is enabled
+    def use_cache? = @use_cache
+    
+    # @return [Boolean] whether trie optimization is enabled
+    def use_trie? = @use_trie == true
+
+    # 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)
+      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
+
+      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)
+        @matcher.track(pattern, value) if strict_order?
+      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
+    #   pattern = Mustermann.new('/users/:id')
+    #   set[pattern] # => :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] || EMPTY_ARRAY
+        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 || EMPTY_HASH)
+    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:
+
+    # 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
+
+    private
+
+    def add_pattern(pattern)
+      if @use_trie.is_a? Integer and @mapping.size >= @use_trie
+        @use_trie = true
+        @matcher = build_matcher
+      end
+
+      @matcher ||= build_matcher
+      @matcher.add(pattern)
+      @expanders[self]&.add(pattern)
+    end
+
+    def build_matcher
+      factory = use_trie? ? Trie : Linear
+      matcher = factory.new(self, @mapping.keys)
+      matcher = StrictOrder.new(matcher) if strict_order?
+      matcher = Cache.new(matcher) if use_cache?
+      matcher
+    end
+  end
+end

data/lib/mustermann/sinatra/safe_renderer.rb

@@ -2,7 +2,7 @@
 module Mustermann
   class Sinatra < AST::Pattern
     # Generates a string that can safely be concatenated with other strings
-    # without chaning its semantics
+    # without changing its semantics
     # @see #safe_string
     # @!visibility private
     SafeRenderer = AST::Translator.create do

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: EMPTY_ARRAY, **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

@@ -2,6 +2,7 @@
 require 'mustermann'
 require 'mustermann/identity'
 require 'mustermann/ast/pattern'
+require 'mustermann/ast/fast_pattern'
 require 'mustermann/sinatra/parser'
 require 'mustermann/sinatra/safe_renderer'
 require 'mustermann/sinatra/try_convert'
@@ -15,6 +16,7 @@ module Mustermann
   # @see Mustermann::Pattern
   # @see file:README.md#sinatra Syntax description in the README
   class Sinatra < AST::Pattern
+    include AST::FastPattern
     include Concat::Native
     register :sinatra
 
@@ -35,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
@@ -57,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
@@ -70,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 EMPTY_HASH
+      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 ||= '3.0.4'
+  VERSION ||= '4.0.1'
 end