Add map_matcher plugin, for matching next segment in request path to a hash key, yielding hash value

This is designed to be a more efficient approach of a typical pattern
for route metaprogramming. When dealing with many similar routes, it
is common to use a hash keyed by route segment, and then match against
an array of the keys:

```ruby
map = {
  'album' => Album,
  'artist' => Artist,
  ...
}.freeze

keys = map.keys.freeze

route do |r|
  r.on "type", keys do |key|
    value = map[key]
    # ...
  end
end
```

For large maps, this is less efficient, since the array matcher
checks whether each element is the next route segment. The
map_matcher plugin allows for:

```ruby
route do |r|
  r.on "type", map: map do |value|
    # ...
  end
end
```

This gets the next route segment and checks whether it is a hash
key, instead of iterating over the hash elements, so it is more
efficient. It also results in simpler code.

Author: jeremyevans

CHANGELOG

@@ -1,3 +1,7 @@
+=== master
+
+* Add map_matcher plugin, for matching next segment in request path to a hash key, yielding hash value (jeremyevans)
+
 === 3.96.0 (2025-09-12)
 
 * Add redirect_path plugin, for automatically calling path with the redirect argument if not given a string (jeremyevans)

lib/roda/plugins/map_matcher.rb

@@ -0,0 +1,48 @@
+# frozen-string-literal: true
+
+#
+class Roda
+  module RodaPlugins
+    # The map_matcher plugin allows you to provide a string-keyed
+    # hash during route matching, and match any of the keys in the hash
+    # as the next segment in the request path, yielding the corresponding
+    # value in the hash:
+    #
+    #   class App < Roda
+    #     plugin :map_matcher
+    #
+    #     map = { "foo" => "bar", "baz" => "quux" }.freeze
+    #
+    #     route do
+    #       r.get map: map do |v|
+    #         v
+    #         # GET /foo => bar
+    #         # GET /baz => quux
+    #       end
+    #     end
+    #   end
+    module MapMatcher
+      module RequestMethods
+        private
+
+        # Match only if the next segment in the path is one of the keys
+        # in the hash, and yield the value of the hash.
+        def match_map(hash)
+          rp = @remaining_path
+          if key = _match_class_String
+            if value = hash[@captures[-1]]
+              @captures[-1] = value
+              true
+            else
+              @remaining_path = rp
+              @captures.pop
+              false
+            end
+          end
+        end
+      end
+    end
+
+    register_plugin(:map_matcher, MapMatcher)
+  end
+end

spec/plugin/map_matcher_spec.rb

@@ -0,0 +1,26 @@
+require_relative "../spec_helper"
+
+describe "map_matcher plugin" do 
+  it "allows for matching next segment to a hash key, yielding hash value" do
+    app(:bare) do 
+      plugin :map_matcher
+      route do |r|
+        r.is :map=>{'a'=>'x', 'b'=>'y'} do |f|
+          f
+        end
+        r.is({:map=>{'a'=>'x', 'b'=>'y'}}, :map=>{'c'=>'z'}) do |*a|
+          a.join('-')
+        end
+        r.remaining_path
+      end
+    end
+
+    body("/").must_equal '/'
+    body("/a").must_equal 'x'
+    body("/b").must_equal 'y'
+    body("/c").must_equal '/c'
+    body("/a/c").must_equal 'x-z'
+    body("/b/c").must_equal 'y-z'
+    body("/a/d").must_equal '/a/d'
+  end
+end

www/pages/documentation.erb

@@ -137,6 +137,7 @@
       <li><a href="rdoc/classes/Roda/RodaPlugins/HashMatcher.html">hash_matcher</a>: Adds hash_matcher class method for easily defining hash matchers.</li>
       <li><a href="rdoc/classes/Roda/RodaPlugins/HeaderMatchers.html">header_matchers</a>: Adds matchers using information from the request headers.</li>
       <li><a href="rdoc/classes/Roda/RodaPlugins/IntegerMatcherMax.html">Integer_matcher_max</a>: Sets a maximum integer value that will be matched by the default Integer matcher.</li>
+      <li><a href="rdoc/classes/Roda/RodaPlugins/MapMatcher.html">map_matcher</a>: Adds support for :map hash matcher for matching next route segment by hash key, yielding hash value.</li>
       <li><a href="rdoc/classes/Roda/RodaPlugins/MatchAffix.html">match_affix</a>: Adds support for overriding default prefix/suffix used in match patterns.</li>
       <li><a href="rdoc/classes/Roda/RodaPlugins/MultibyteStringMatcher.html">multibyte_string_matcher</a>: Makes string matcher handle multibyte characters.</li>
       <li><a href="rdoc/classes/Roda/RodaPlugins/ParamMatchers.html">param_matchers</a>: Adds matchers using information from the request params.</li>