mustermann 4.0.0.alpha4 → 4.0.0.beta1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c45d32932b0745c20363ab0fb0084eb861754482e3c47ed68684cf245f10100f
-  data.tar.gz: edb3fbe54217319a9a059b2a57c74b4e8f7d84cc4721fdb9a78bbf5ed6afa113
+  metadata.gz: a382e55dcc3919ca87dfa480d405b5fc126435c8081ce37e270a63e5907e7517
+  data.tar.gz: 4ec389e09c7a625fc83acf00fa9ff98a08e05cb58c1fb5c43772b14605a92e02
 SHA512:
-  metadata.gz: 39c217af2266a0dc8f647dafd1c5772cf10e6f921a9d8ccabdcd29357a1a3dc9991065221f12eacc473af1ca183ac8bbd14dc8eae2d83834b21c81ac55e8ffc4
-  data.tar.gz: f9a2c84244115819b62737f222b3c181ca5c5192e83243387473b3bf07666be8e019a78e591861e55a93579c28ab9e0f63725feddc0b6a61ff01f6f736c29735
+  metadata.gz: 7c8595c1df98b37d768691d0e1b591edd5a7b219aeff7569ee6e7e925b29ef2065125e7845d487e4b3aab68e2b7c06ffc7d696c74433a82b0d6012dd80a1d88e
+  data.tar.gz: 8f4bf30d82cd54534a5f4e31c1843868e1a0fe0112be8656167321b6554baac4d8455e947146c3ec5f9340f8af20ca8edd79499630a571b2a39851ddaef55f38

data/README.md

@@ -595,6 +595,99 @@ Mustermann.new('/:id.:ext', capture: { id: /\d+/, ext: ['png', 'jpg'] })
 
 Available POSIX character classes are: `:alnum`, `:alpha`, `:blank`, `:cntrl`, `:digit`, `:graph`, `:lower`, `:print`, `:punct`, `:space`, `:upper`, `:xdigit`, `:word` and `:ascii`.
 
+#### Typed Captures
+
+Certain Ruby classes and named symbols can be passed as a capture value. They constrain what the capture matches **and** automatically convert the captured string in `params` to the appropriate type.
+
+``` ruby
+require 'mustermann'
+require 'date'
+
+# Integer: only matches integers, converts to Integer in params
+pattern = Mustermann.new('/:id', capture: Integer)
+pattern.match('/42')    # matches
+pattern.match('/foo')   # does not match
+pattern.params('/42')   # => { "id" => 42 }
+
+# Float: matches integers and decimals, converts to Float in params
+pattern = Mustermann.new('/:price', capture: Float)
+pattern.params('/3.14') # => { "price" => 3.14 }
+pattern.params('/5')    # => { "price" => 5.0 }
+
+# Symbol: only matches word characters (\w+), converts to Symbol in params
+pattern = Mustermann.new('/:format', capture: Symbol)
+pattern.params('/json')       # => { "format" => :json }
+pattern.match('/with-hyphen') # does not match
+
+# Date: only matches YYYY-MM-DD dates, converts to Date in params
+pattern = Mustermann.new('/:date', capture: Date)
+pattern.params('/2026-04-23') # => { "date" => #<Date: 2026-04-23> }
+pattern.match('/04-23-2026')  # does not match
+
+# Gem::Version: matches version strings, converts to Gem::Version in params
+require 'rubygems/version'
+pattern = Mustermann.new('/:version', capture: Gem::Version)
+pattern.params('/1.2.3') # => { "version" => #<Gem::Version "1.2.3"> }
+```
+
+Lowercase symbol aliases are also available: `:integer`, `:float`, `:symbol`, `:date`, `:version`. They behave identically to their class counterparts:
+
+``` ruby
+pattern = Mustermann.new('/:id', capture: :integer)
+pattern.params('/42') # => { "id" => 42 }
+```
+
+These can be mixed with other capture types in a hash:
+
+``` ruby
+pattern = Mustermann.new('/:id(.:format)?', capture: { id: Integer, format: :slug })
+pattern.params('/42')      # => { "id" => 42, "format" => nil }
+pattern.params('/42.json') # => { "id" => 42, "format" => "json" }
+```
+
+Like all other capture types, these can also be used in an array:
+
+``` ruby
+pattern = Mustermann.new('/score/:score', capture: [Integer, Float])
+pattern.params('/42')   # => { "score" => 42 }
+pattern.params('/3.14') # => { "score" => 3.14 }
+```
+
+#### Other Symbols
+
+The following symbols constrain the capture with a regex but do **not** perform any type conversion — `params` still returns a string:
+
+| Symbol    | Matches |
+|-----------|---------|
+| `:locale` | BCP 47 language tags (`en`, `en-US`, `zh-Hans-CN`) |
+| `:slug`   | Lowercase URL slugs (`hello-world`, `foo-bar-baz`) |
+| `:uuid`   | UUIDs (`f47ac10b-58cc-4372-a567-0e02b2c3d479`, case-insensitive) |
+
+``` ruby
+Mustermann.new('/:lang', capture: :locale).match('/zh-Hans-CN') # matches
+Mustermann.new('/:slug', capture: :slug).match('/Hello')        # does not match
+Mustermann.new('/:id',   capture: :uuid).match('/not-a-uuid')   # does not match
+```
+
+Again, these can be mixed with other capture types in a hash or array:
+
+```ruby
+set = Mustermann::Set.new(capture: { id: [Integer, :uuid], locale: :locale })
+
+set.add("(/:locale)?/:id", :show)
+set.add("/(:locale)?", :index)
+
+# without capture constraints, this would match the :show pattern instead
+match = set.match('/en')
+match.value # => :index
+
+match = set.match('/f47ac10b-58cc-4372-a567-0e02b2c3d479')
+match.value # => :show
+
+match = set.match('/en/12')
+match.value # => :show
+```
+
 <a name="-available-options--except"></a>
 ### `except`
 

data/lib/mustermann/ast/compiler.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'mustermann/ast/translator'
+require 'mustermann/ast/converters'
 
 module Mustermann
   # @see Mustermann::AST::Pattern
@@ -99,46 +100,48 @@ 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}"}"
+        def qualified(string, greedy: true, **options)
+          "#{string}#{qualifier || "+#{'?' unless greedy}"}"
         end
 
-        def with_lookahead(string, lookahead: nil,
-                           **options) lookahead ? "(?:(?!#{lookahead})#{string})" : string
+        def with_lookahead(string, lookahead: nil, **options)
+          lookahead ? "(?:(?!#{lookahead})#{string})" : string
         end
 
-        def from_hash(hash,
-                      **options) pattern(capture: hash[name.to_sym],
-                                         **options)
+        def from_hash(hash, **options)
+          pattern(capture: hash[name.to_sym], **options)
         end
 
         def from_array(array, **options)
-          Regexp.union(*array.map do |e|
-            pattern(capture: e, **options)
-          end)
+          Regexp.union(*array.map { |e| pattern(capture: e, **options) })
         end
 
-        def from_symbol(symbol,
-                        **options) qualified(with_lookahead("[[:#{symbol}:]]", **options),
-                                             **options)
+        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 do |c|
-            t.encoded(c, **options)
-          end.join)
+          Regexp.new(string.chars.map { |c| t.encoded(c, **options) }.join)
         end
 
         def from_nil(**options)
-          qualified(
-            with_lookahead(default(**options), **options), **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 || '[^/\\?#]'

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

@@ -101,13 +101,13 @@ module Mustermann
       # Internal AST representation of pattern.
       # @!visibility private
       def to_ast
-        ast = self.class.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) if ast
+        @param_converters ||= scan_params(ast, options) if ast
         ast
       end
 
@@ -143,7 +143,7 @@ module Mustermann
 
       # @!visibility private
       def param_converters
-        @param_converters ||= scan_params(to_ast)
+        @param_converters ||= scan_params(to_ast, options)
       end
 
       # @api private

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

@@ -74,10 +74,13 @@ module Mustermann
       end
     end
 
+    # @return [Array<String>] the names of the named captures
+    def names = named_captures.keys
+
     # @overload [](key)
-    #   Access params by key.
+    #   Access named captures by key.
     #   @param key [String, Symbol] the key to access
-    #   @return the value of the param, or nil if not found
+    #   @return the value of the named capture, or nil if not found
     #
     # @overload [](index)
     #   Access captures by index.
@@ -96,8 +99,8 @@ module Mustermann
     #   @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]
+      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}"

data/lib/mustermann/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mustermann
 version: !ruby/object:Gem::Version
-  version: 4.0.0.alpha4
+  version: 4.0.0.beta1
 platform: ruby
 authors:
 - Konstantin Haase
@@ -29,6 +29,7 @@ files:
 - lib/mustermann.rb
 - lib/mustermann/ast/boundaries.rb
 - lib/mustermann/ast/compiler.rb
+- lib/mustermann/ast/converters.rb
 - lib/mustermann/ast/expander.rb
 - lib/mustermann/ast/fast_pattern.rb
 - lib/mustermann/ast/node.rb