mustermann 4.0.0.alpha3 → 4.0.0.alpha4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c6a0beea1e6d365356c6444910ec10200dcaf98f1968e88ac2fe91e0a7b23b93
-  data.tar.gz: 1be43d10761af60bbd4cdd5d087214073984825b05f397de8d1475a7f35686d6
+  metadata.gz: c45d32932b0745c20363ab0fb0084eb861754482e3c47ed68684cf245f10100f
+  data.tar.gz: edb3fbe54217319a9a059b2a57c74b4e8f7d84cc4721fdb9a78bbf5ed6afa113
 SHA512:
-  metadata.gz: 710a7afa55bdbd0f6fb17845458572ea9adaf8149674c9b1e54ddba333382be9e05136d37d7680595bead97b21bee76334d129cbf96c320b0f975688b20ad29c
-  data.tar.gz: 64e15b87da6f731fce7d0e50eb4ee13511c175b979765d9a233a066c026026c0c82300e22b8492db8220d2f89995cadb471c78ac00da60ea8be360a22b8290be
+  metadata.gz: 39c217af2266a0dc8f647dafd1c5772cf10e6f921a9d8ccabdcd29357a1a3dc9991065221f12eacc473af1ca183ac8bbd14dc8eae2d83834b21c81ac55e8ffc4
+  data.tar.gz: f9a2c84244115819b62737f222b3c181ca5c5192e83243387473b3bf07666be8e019a78e591861e55a93579c28ab9e0f63725feddc0b6a61ff01f6f736c29735

data/README.md

@@ -455,27 +455,6 @@ set.expand(id: '5')          # => '/users/5'  (first applicable pattern)
 set.expand(:posts, id: '5')  # => '/posts/5'  (patterns for a specific value)
 ```
 
-<a name="-duck-typing"></a>
-## Duck Typing
-
-<a name="-duck-typing-to-pattern"></a>
-### `to_pattern`
-
-All methods converting string input to pattern objects will also accept any arbitrary object that implements `to_pattern`:
-
-``` ruby
-require 'mustermann'
-
-class MyObject
-  def to_pattern(**options)
-    Mustermann.new("/foo", **options)
-  end
-end
-
-object = MyObject.new
-Mustermann.new(object, type: :rails) # => #<Mustermann::Rails:"/foo">
-```
-
 ### Match order
 
 A set can match patterns and values in loose or strict insertion order.
@@ -536,6 +515,27 @@ set.match("/static").value             # => :first
 set.match_all("/static").map(&:value)  # => [:first, :second, :third]
 ```
 
+<a name="-duck-typing"></a>
+## Duck Typing
+
+<a name="-duck-typing-to-pattern"></a>
+### `to_pattern`
+
+All methods converting string input to pattern objects will also accept any arbitrary object that implements `to_pattern`:
+
+``` ruby
+require 'mustermann'
+
+class MyObject
+  def to_pattern(**options)
+    Mustermann.new("/foo", **options)
+  end
+end
+
+object = MyObject.new
+Mustermann.new(object, type: :rails) # => #<Mustermann::Rails:"/foo">
+```
+
 <a name="-duck-typing-respond-to"></a>
 ### `respond_to?`
 

data/lib/mustermann/ast/fast_pattern.rb

@@ -34,7 +34,7 @@ module Mustermann
         return unless match = @regexp.match(string)
         params = match.named_captures
         params.transform_values! { |v| unescape(v) } if string.include?('%')
-        Match.new(self, string, params)
+        Match.new(self, match, params:)
       end
 
       # Public override: fast path for simple patterns, falls through to super otherwise.

data/lib/mustermann/concat.rb

@@ -75,16 +75,21 @@ module Mustermann
 
     # @see Mustermann::Pattern#peek_match
     def peek_match(string)
-      substring = string
-      params = {}
+      post_match      = string
+      params         = {}
+      captures       = []
+      named_captures = {}
 
       patterns.each do |pattern|
-        return unless part = pattern.peek_match(substring)
+        return unless part = pattern.peek_match(post_match)
         params.merge!(part.params)
-        substring = substring[part.to_s.size..-1]
+        named_captures.merge!(part.named_captures)
+        captures.concat(part.captures)
+        post_match = post_match[part.to_s.size..-1]
       end
 
-      Match.new(self, string[0, string.size - substring.size], params, post_match: substring)
+      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/match.rb

@@ -1,39 +1,133 @@
 # 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
-    attr_reader :pattern, :string, :params, :post_match, :pre_match
-
-    def initialize(pattern, string, params = {}, post_match: '', pre_match: '')
-      @pattern    = pattern
-      @string     = string.freeze
-      @params     = params.freeze
-      @post_match = post_match.freeze
-      @pre_match  = pre_match.freeze
+    # @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
 
-    def [](key)
+    # @overload [](key)
+    #   Access params by key.
+    #   @param key [String, Symbol] the key to access
+    #   @return the value of the param, 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 params[key]
       when Symbol  then params[key.to_s]
-      else raise ArgumentError, "key must be a String or Symbol, not #{key.class}"
+      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_s string
     alias to_h params
-
   end
 end

data/lib/mustermann/pattern.rb

@@ -165,7 +165,7 @@ module Mustermann
     # @see #peek_params
     def peek_match(string)
       matched = peek(string)
-      Match.new(self, matched, {}, post_match: string[matched.size..-1]) 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).
@@ -182,7 +182,7 @@ 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)
-      match ? [match.params, match.string.size] : nil
+      match ? [match.params, match.to_s.size] : nil
     end
 
     # @param [String] string the string to match against

data/lib/mustermann/regexp_based.rb

@@ -35,10 +35,10 @@ module Mustermann
     # @see (see Mustermann::Pattern#peek_match)
     def peek_match(string) = build_match(@peek_regexp.match(string))
 
-    def match(string)
-      return unless match = @regexp.match(string)
-      Match.new(self, string, build_params(match))
-    end
+    # @param (see Mustermann::Pattern#match)
+    # @return (see Mustermann::Pattern#match)
+    # @see (see Mustermann::Pattern#match)
+    def match(string) = build_match(@regexp.match(string))
 
     extend Forwardable
     def_delegators :regexp, :===, :=~, :names
@@ -47,7 +47,7 @@ module Mustermann
 
     def build_match(match)
       return unless match
-      Match.new(self, match.to_s, build_params(match), post_match: match.post_match, pre_match: match.pre_match)
+      Match.new(self, match, params: build_params(match))
     end
 
     def build_params(match)

data/lib/mustermann/set/linear.rb

@@ -17,9 +17,9 @@ module Mustermann
         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
+          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:) }
+          values.each { |value| result << Match.new(match, value:) }
         end
         result
       end

data/lib/mustermann/set/match.rb

@@ -3,21 +3,21 @@ require 'mustermann/match'
 
 module Mustermann
   class Set
+
+    # Subclass of {Mustermann::Match} that also includes the value associated with the pattern that produced the match.
     class Match < Mustermann::Match
+      # @return the value associated with the pattern that produced the match, if any
       attr_reader :value
 
-      def initialize(pattern = nil, string = nil, params = {}, value: nil, match: nil, post_match: '', pre_match: '')
+      # (see Mustermann::Match#initialize)
+      # @option options [Object] :value the value associated with the pattern that produced the match, if any
+      def initialize(*, value: nil, **)
         @value = value
-        if match
-          @pattern    = match.pattern
-          @string     = match.string
-          @params     = match.params
-          @post_match = match.post_match
-          @pre_match  = match.pre_match
-        else
-          super(pattern, string, params, post_match:, pre_match:)
-        end
+        super(*, **)
       end
+
+      # @see Mustermann::Match#eql?
+      def eql?(other) = super && value == other.value
     end
   end
 end

data/lib/mustermann/set/trie.rb

@@ -148,7 +148,7 @@ module Mustermann
         end
 
         if peek
-          matches = build_matches(string[0, position], params, all:, post_match: string[position..], pre_match: '')
+          matches = build_matches(string, params, all:, matched_length: position, post_match: string[position..], pre_match: '')
           return matches unless all
           result.concat(matches)
         end
@@ -158,17 +158,18 @@ module Mustermann
 
       NIL_VALUES = [nil].freeze
 
-      def build_matches(string, params, all: false, post_match: '', pre_match: '')
+      def build_matches(string, params, all: false, matched_length: string.size, post_match: '', pre_match: '')
         result = [] if all
+        matched = string[0, matched_length]
 
         @patterns.each do |pattern|
-          next if pattern.except_regexp&.match?(string)
+          next if pattern.except_regexp&.match?(matched)
 
           pattern_params = build_pattern_params(pattern, params)
 
           values = @set.values_for_pattern(pattern) || NIL_VALUES
           values.each do |value|
-            match = Set::Match.new(pattern, string, pattern_params, value:, post_match:, pre_match:)
+            match = Set::Match.new(pattern, string, matched:, params: pattern_params, value:, post_match:, pre_match:)
             return match unless all
             result << match
           end

data/lib/mustermann/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mustermann
 version: !ruby/object:Gem::Version
-  version: 4.0.0.alpha3
+  version: 4.0.0.alpha4
 platform: ruby
 authors:
 - Konstantin Haase