Add pattern matching support via deconstruct_keys

Closes #642.

Author: sferik

CHANGELOG.md

@@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Pattern matching support (`deconstruct_keys`) for Response, Response::Status,
+  Headers, ContentType, and URI (#642)
+
 ### Changed
 
 - Bumped min llhttp dependency version

README.md

@@ -104,6 +104,24 @@ and call `#readpartial` on it repeatedly until it returns `nil`:
 => nil
 ```
 
+### Pattern Matching
+
+Response objects support Ruby's pattern matching:
+
+```ruby
+case HTTP.get("https://api.example.com/users")
+in { status: 200..299, body: body }
+  JSON.parse(body.to_s)
+in { status: 404 }
+  nil
+in { status: 400.. }
+  raise "request failed"
+end
+```
+
+Pattern matching is also supported on `HTTP::Response::Status`, `HTTP::Headers`,
+`HTTP::ContentType`, and `HTTP::URI`.
+
 ## Supported Ruby Versions
 
 This library aims to support and is [tested against][build-link]

lib/http/content_type.rb

@@ -69,5 +69,21 @@ def initialize(mime_type = nil, charset = nil)
       @mime_type = mime_type
       @charset   = charset
     end
+
+    # Pattern matching interface for matching against content type attributes
+    #
+    # @example
+    #   case response.content_type
+    #   in { mime_type: /json/ }
+    #     "JSON content"
+    #   end
+    #
+    # @param keys [Array<Symbol>, nil] keys to extract, or nil for all
+    # @return [Hash{Symbol => Object}]
+    # @api public
+    def deconstruct_keys(keys)
+      h = { mime_type: @mime_type, charset: @charset }
+      keys ? h.slice(*keys) : h
+    end
   end
 end

lib/http/headers.rb

@@ -186,16 +186,20 @@ def to_h
       keys.to_h { |k| [k, self[k]] }
     end
     # @!method to_hash
-    #   Returns Rack-compatible headers Hash
-    #
-    #   @example
-    #     headers.to_hash
-    #
     #   @see #to_h
     #   @return [Hash]
-    #   @api public
     alias to_hash to_h
 
+    # Pattern matching interface
+    #
+    # @example
+    #   headers.deconstruct_keys(%i[content_type])
+    #
+    # @param keys [Array<Symbol>, nil] keys to extract, or nil for all
+    # @return [Hash{Symbol => Object}]
+    # @api public
+    def deconstruct_keys(keys) = @pile.map { |_, k, _| k }.to_h { |k| [k.tr("A-Z-", "a-z_").to_sym, self[k]] }.then { |h| keys ? h.slice(*keys) : h } # rubocop:disable Layout/LineLength
+
     # Returns human-readable representation of self instance
     #
     # @example

lib/http/response.rb

@@ -148,6 +148,42 @@ def to_a
       [status.to_i, headers.to_h, body.to_s]
     end
 
+    # @!method deconstruct
+    #   Array pattern matching interface
+    #
+    #   @example
+    #     response.deconstruct
+    #
+    #   @see #to_a
+    #   @return [Array(Integer, Hash, String)]
+    #   @api public
+    alias deconstruct to_a
+
+    # Pattern matching interface for matching against response attributes
+    #
+    # @example
+    #   case response
+    #   in { status: 200..299, body: /success/ }
+    #     "ok"
+    #   in { status: 400.. }
+    #     "error"
+    #   end
+    #
+    # @param keys [Array<Symbol>, nil] keys to extract, or nil for all
+    # @return [Hash{Symbol => Object}]
+    # @api public
+    def deconstruct_keys(keys)
+      h = {
+        status:        @status,
+        version:       @version,
+        headers:       @headers,
+        body:          @body,
+        request:       @request,
+        proxy_headers: @proxy_headers
+      }
+      keys ? h.slice(*keys) : h
+    end
+
     # Flushes body and returns self-reference
     #
     # @example

lib/http/response/status.rb

@@ -176,6 +176,24 @@ def inspect
         "#<#{self.class} #{self}>"
       end
 
+      # Pattern matching interface for matching against status code and reason
+      #
+      # @example
+      #   case response.status
+      #   in { code: 200..299 }
+      #     "success"
+      #   in { code: 400.. }
+      #     "error"
+      #   end
+      #
+      # @param keys [Array<Symbol>, nil] keys to extract, or nil for all
+      # @return [Hash{Symbol => Object}]
+      # @api public
+      def deconstruct_keys(keys)
+        h = { code: code, reason: reason }
+        keys ? h.slice(*keys) : h
+      end
+
       SYMBOLS.each do |code, symbol|
         class_eval <<-RUBY, __FILE__, __LINE__ + 1
           def #{symbol}?      # def bad_request?

lib/http/uri.rb

@@ -260,6 +260,20 @@ def inspect
       format("#<%s:0x%014x URI:%s>", self.class, object_id << 1, self)
     end
 
+    # Pattern matching interface
+    #
+    # @example
+    #   uri.deconstruct_keys(%i[scheme host])
+    #
+    # @param keys [Array<Symbol>, nil] keys to extract, or nil for all
+    # @return [Hash{Symbol => Object}]
+    # @api public
+    def deconstruct_keys(keys)
+      h = { scheme: scheme, host: host, port: port, path: path,
+            query: query, fragment: fragment, user: user, password: password }
+      keys ? h.slice(*keys) : h
+    end
+
     private
 
     # Adds or removes IPv6 brackets from a host

sig/http.rbs

@@ -140,6 +140,7 @@ module HTTP
     def include?: (untyped name) -> bool
     def to_h: () -> Hash[String, untyped]
     alias to_hash to_h
+    def deconstruct_keys: (Array[Symbol]? keys) -> Hash[Symbol, untyped]
     def to_a: () -> Array[Array[String]]
     def inspect: () -> String
     def keys: () -> Array[String]
@@ -213,6 +214,7 @@ module HTTP
     public
 
     def initialize: (?String? mime_type, ?String? charset) -> void
+    def deconstruct_keys: (Array[Symbol]? keys) -> Hash[Symbol, untyped]
   end
 
   class Feature
@@ -480,6 +482,7 @@ module HTTP
     def to_s: () -> String
     alias to_str to_s
     def inspect: () -> String
+    def deconstruct_keys: (Array[Symbol]? keys) -> Hash[Symbol, untyped]
 
     # Delegated methods from Addressable::URI
     def scheme: () -> String?
@@ -659,6 +662,8 @@ module HTTP
     def connection: () -> untyped
     def uri: () -> URI
     def to_a: () -> Array[untyped]
+    alias deconstruct to_a
+    def deconstruct_keys: (Array[Symbol]? keys) -> Hash[Symbol, untyped]
     def flush: () -> Response
     def content_length: () -> Integer?
     def content_type: () -> ContentType
@@ -702,6 +707,7 @@ module HTTP
       def server_error?: () -> bool
       def to_sym: () -> Symbol?
       def inspect: () -> String
+      def deconstruct_keys: (Array[Symbol]? keys) -> Hash[Symbol, untyped]
       def __setobj__: (untyped obj) -> void
       def __getobj__: () -> Integer
     end

test/http/content_type_test.rb

@@ -126,6 +126,43 @@
     end
   end
 
+  describe "#deconstruct_keys" do
+    let(:content_type) { HTTP::ContentType.new("text/html", "utf-8") }
+
+    it "returns all keys when given nil" do
+      assert_equal({ mime_type: "text/html", charset: "utf-8" }, content_type.deconstruct_keys(nil))
+    end
+
+    it "returns only requested keys" do
+      assert_equal({ mime_type: "text/html" }, content_type.deconstruct_keys([:mime_type]))
+    end
+
+    it "excludes unrequested keys" do
+      refute_includes content_type.deconstruct_keys([:mime_type]).keys, :charset
+    end
+
+    it "returns empty hash for empty keys" do
+      assert_equal({}, content_type.deconstruct_keys([]))
+    end
+
+    it "returns nil values when attributes are nil" do
+      ct = HTTP::ContentType.new
+
+      assert_equal({ mime_type: nil, charset: nil }, ct.deconstruct_keys(nil))
+    end
+
+    it "supports pattern matching with case/in" do
+      matched = case content_type
+                in { mime_type: /html/ }
+                  true
+                else
+                  false
+                end
+
+      assert matched
+    end
+  end
+
   describe "#initialize" do
     it "stores mime_type and charset" do
       ct = HTTP::ContentType.new("text/html", "utf-8")

test/http/headers_test.rb

@@ -376,6 +376,51 @@ def obj.inspect = "INSPECTED"
     end
   end
 
+  describe "#deconstruct_keys" do
+    before do
+      headers.add :content_type, "application/json"
+      headers.add :set_cookie,   "hoo=ray"
+      headers.add :set_cookie,   "woo=hoo"
+    end
+
+    it "returns all keys as snake_case symbols when given nil" do
+      result = headers.deconstruct_keys(nil)
+
+      assert_equal "application/json", result[:content_type]
+      assert_equal %w[hoo=ray woo=hoo], result[:set_cookie]
+    end
+
+    it "converts header names to snake_case symbols" do
+      assert_includes headers.deconstruct_keys(nil).keys, :content_type
+      assert_includes headers.deconstruct_keys(nil).keys, :set_cookie
+    end
+
+    it "returns only requested keys" do
+      result = headers.deconstruct_keys([:content_type])
+
+      assert_equal({ content_type: "application/json" }, result)
+    end
+
+    it "excludes unrequested keys" do
+      refute_includes headers.deconstruct_keys([:content_type]).keys, :set_cookie
+    end
+
+    it "returns empty hash for empty keys" do
+      assert_equal({}, headers.deconstruct_keys([]))
+    end
+
+    it "supports pattern matching with case/in" do
+      matched = case headers
+                in { content_type: /json/ }
+                  true
+                else
+                  false
+                end
+
+      assert matched
+    end
+  end
+
   describe "#inspect" do
     it "returns a human-readable representation" do
       headers.set :set_cookie, %w[hoo=ray woo=hoo]