link-header-parser 6.1.1 → 7.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bec652a3b5e7759eef7d39f146793f1cd4c294f7feb9224743d3de0096306e99
-  data.tar.gz: 0d277b9ea131896cdb57d28246202b06071e2ba48c64bc7b4d6080d9e6d4240d
+  metadata.gz: 3d7f18899021fd6fb79e5915e8d1945fc67a1de6093f8b8043e05b3de01cbffc
+  data.tar.gz: 30652a856807b2ab19dc1a2b0d7a419e7ff399f182a31eff3734d403eba1b8bb
 SHA512:
-  metadata.gz: 003a7d910fae4dfcb416a262afbfcdd846406cf0bfedbe7425b8d302a9922243e57892dbb03dd8b6d7efef3d3bfd43f957759bce8a6912830ffd1773093f811b
-  data.tar.gz: 7f74b994d6806e58d3393824fb68d2fda896d75b1de01941269d3110fada1eb36631b6e030f20bf17573a35358f43446630ed003e9d023ded98378df2788b984
+  metadata.gz: a509d74c25c362a61eba888acf9ea4b5e733e66db19003e2c82ac9b9d72de70d491993ed9b1c5db4265905332fffbf2cdc4cb1f331bb8f7f19a5914d4b8cfbf5
+  data.tar.gz: 73a5ebd6172a225bf6ffff23250c241dcfe78855cb2aa97b65811deece22ae3a10b292fc444f973ec141396edc33736a2210183c2a3b85bac2f1b8160a0e5e21

data/README.md

@@ -6,6 +6,12 @@
 [![Downloads](https://img.shields.io/gem/dt/link-header-parser.svg?logo=rubygems&style=for-the-badge)](https://rubygems.org/gems/link-header-parser)
 [![Source](https://img.shields.io/badge/get_it_on_codeberg-2185d0?labelColor=555&logo=codeberg&logoColor=fff&style=for-the-badge)](https://codeberg.org/jgarber/link-header-parser-ruby)
 
+## Key Features
+
+- Implements [RFC-8288](https://tools.ietf.org/html/rfc8288) HTTP Link Header parsing algorithm (see [Appendix B](https://tools.ietf.org/html/rfc8288#appendix-B)).
+- Supports [IRI](https://en.wikipedia.org/wiki/Internationalized_Resource_Identifier)s by using the [Addressable](https://rubygems.org/gems/addressable) gem.
+- Supports Ruby 2.6 and newer.
+
 ## Getting Started
 
 Before installing and using link-header-parser-ruby, you'll want to have [Ruby](https://www.ruby-lang.org) 2.6 (or newer) installed. Using a Ruby version managment tool like [rbenv](https://github.com/rbenv/rbenv), [chruby](https://github.com/postmodern/chruby), or [rvm](https://github.com/rvm/rvm) is recommended.
@@ -24,114 +30,7 @@ gem "link-header-parser"
 
 ## Usage
 
-With link-header-parser-ruby added to your project's `Gemfile` and installed, you may parse a URL's HTTP Link headers by doing:
-
-```ruby
-require "net/http"
-require "link-header-parser"
-
-url = "https://sixtwothree.org"
-link_headers = Net::HTTP.get_response(URI.parse(url)).get_fields("Link")
-
-collection = LinkHeaderParser.parse(link_headers, base: url)
-```
-
-The `parse` method accepts two arguments:
-
-1. an `Array` of strings representing HTTP Link headers (e.g. `['</>; rel="home"', '</chapters/1>; anchor="#copyright"; rel="license"']`)
-1. a `String` (or any `String`-like object) representing the absolute URL of the resource providing the HTTP Link headers
-
-In the example above, `collection` is an instance of `LinkHeadersCollection` which includes Ruby's [`Enumerable`](https://ruby-doc.org/core/Enumerable.html) mixin. This mixin allows for use of common methods like `each`, `first`/`last`, and `map`.
-
-For example, you could retrieve an array of `target_uri`s:
-
-```ruby
-puts collection.map(&:target_uri)
-#=> ["https://assets.sixtwothree.org/", "https://fonts.googleapis.com/", "https://fonts.gstatic.com/", "https://sixtwothree.org/webmentions"]
-```
-
-### Working with a `LinkHeadersCollection`
-
-In addition to the included `Enumerable` methods, the following methods may be used to interact with a `LinkHeadersCollection`:
-
-#### The `relation_types` Method
-
-```ruby
-puts collection.relation_types
-#=> ["preconnect", "webmention"]
-```
-
-#### The `group_by_relation_type` Method
-
-Using the `collection` from above, the `group_by_relation_type` method returns a `Hash`:
-
-```ruby
-{
-  preconnect: [
-    #<LinkHeaderParser::LinkHeader target_uri: "https://assets.sixtwothree.org/", relation_types: ["preconnect"]>,
-    #<LinkHeaderParser::LinkHeader target_uri: "https://fonts.googleapis.com/", relation_types: ["preconnect"]>,
-    #<LinkHeaderParser::LinkHeader target_uri: "https://fonts.gstatic.com/", relation_types: ["preconnect"]>
-  ],
-  webmention: [
-    #<LinkHeaderParser::LinkHeader target_uri: "https://sixtwothree.org/webmentions", relation_types: ["webmention"]>
-  ]
-}
-```
-
-### Working with a `LinkHeader`
-
-You may interact with one or more `LinkHeader`s in a `LinkHeadersCollection` using the methods outlined below. The naming conventions for these methods draws heavily on the terminology established in [RFC-5988](https://tools.ietf.org/html/rfc5988) and [RFC-8288](https://tools.ietf.org/html/rfc8288).
-
-#### Link Target ([§ 3.1](https://tools.ietf.org/html/rfc8288#section-3.1))
-
-```ruby
-link_header = LinkHeaderParser.parse(%(</index.html>; rel="home"), base: "https://example.com/").first
-
-link_header.target_string
-#=> "/index.html"
-
-link_header.target_uri
-#=> "https://example.com/index.html"
-```
-
-The `target_string` method returns a string of the value between the opening and closing angle brackets at the beginning of the Link header. The `target_uri` method returns a string representing the resolved URL.
-
-#### Link Context ([§ 3.2](https://tools.ietf.org/html/rfc8288#section-3.2))
-
-```ruby
-link_header = LinkHeaderParser.parse(%(</chapters/1>; anchor="#copyright"; rel="license"), base: "https://example.com/").first
-
-link_header.context_string
-#=> "#copyright"
-
-link_header.context_uri
-#=> "https://example.com/chapters/1#copyright"
-```
-
-The `anchor` parameter's value may be a fragment identifier (e.g. `#foo`), a relative URL (e.g. `/foo`), or an absolute URL (e.g. `https://context.example.com`). The `context_string` method returns the `anchor` parameter's value (when present) and defaults to the `target_string` value. The `context_uri` method returns a string representing the resolved URL.
-
-#### Relation Type ([§ 3.3](https://tools.ietf.org/html/rfc8288#section-3.3))
-
-```ruby
-link_header = LinkHeaderParser.parse(%(</chapters/1>; rel="prev start"), base: "https://example.com/").first
-
-link_header.relations_string
-#=> "prev start"
-
-link_header.relation_types
-#=> ["prev", "start"]
-```
-
-#### Link Parameters ([Appendix B.3](https://tools.ietf.org/html/rfc8288#appendix-B.3))
-
-```ruby
-link_header = LinkHeaderParser.parse(%(</posts.rss>; rel="alternate"; hreflang="en-US"; title="sixtwothree.org: Posts"; type="application/rss+xml"), base: "https://sixtwothree.org").first
-
-link_header.link_parameters
-#=> [#<LinkHeaderParser::LinkHeaderParameter name: "rel", value: "alternate">, #<LinkHeaderParser::LinkHeaderParameter name: "hreflang", value: "en-US">, #<LinkHeaderParser::LinkHeaderParameter name: "title", value: "sixtwothree.org: Posts">, #<LinkHeaderParser::LinkHeaderParameter name: "type", value: "application/rss+xml">]
-```
-
-Note that the `Array` returned by the `link_parameters` method may include multiple `LinkHeaderParameter`s with the same name depending on the provided Link header. Certain methods on `LinkHeader` will return values from the first occurrence of a parameter name (e.g. `link_header.relations_string`) in accordance with [RFC-8288](https://tools.ietf.org/html/rfc8288).
+See [USAGE.md](USAGE.md) for documentation of link-header-parser-ruby's features.
 
 ## Acknowledgments
 

data/USAGE.md

@@ -0,0 +1,143 @@
+# Using link-header-parser-ruby
+
+Before using link-header-parser-ruby, please read the [Getting Started](README.md#getting-started) and [Installation](README.md#installation) sections of the project's [README.md](README.md).
+
+## Parsing HTTP Link headers
+
+With link-header-parser-ruby added to your project's `Gemfile` and installed, you may parse a HTTP Link headers from an HTTP response by doing something like:
+
+```ruby
+require "net/http"
+require "link-header-parser"
+
+url = "https://sixtwothree.org"
+link_headers = Net::HTTP.get_response(URI.parse(url)).get_fields("Link")
+
+collection = LinkHeaderParser.parse(link_headers, base_uri: url)
+```
+
+The `LinkHeaderParser.parse` method accepts two arguments:
+
+1. an `Array` of strings representing HTTP Link headers (e.g. `['</>; rel="home"', '</chapters/1>; anchor="#copyright"; rel="license"']`), and
+2. a `String` (or any object that responds to `#to_s`) representing the absolute URL of the resource providing the HTTP Link headers.
+
+## Working with a `LinkHeaderSet`
+
+In the example above, `collection` is a `LinkHeaderSet`, an [`Array`](https://docs.ruby-lang.org/en/master/Array.html)-like object whose elements are one or more `LinkHeader` objects. The `LinkHeaderSet` is enhanced with a few custom methods noted below.
+
+Building on the example `collection` from above:
+
+```ruby
+collection.relation_types
+#=> ["preconnect", "webmention"]
+
+collection.group_by_relation_type
+#=>
+{
+  "preconnect" => [
+    #<LinkHeaderParser::LinkHeader @base_uri=#<Addressable::URI URI:https://sixtwothree.org> @target_string="https://assets.sixtwothree.org/">,
+    #<LinkHeaderParser::LinkHeader @base_uri=#<Addressable::URI URI:https://sixtwothree.org> @target_string="https://fonts.googleapis.com/">,
+    #<LinkHeaderParser::LinkHeader @base_uri=#<Addressable::URI URI:https://sixtwothree.org> @target_string="https://fonts.gstatic.com/">
+  ],
+  "webmention" => [
+    #<LinkHeaderParser::LinkHeader @base_uri=#<Addressable::URI URI:https://sixtwothree.org> @target_string="https://sixtwothree.org/webmentions">
+  ]
+}
+```
+
+## Working with a `LinkHeader`
+
+You may also directly parse a `LinkHeader` using `LinkHeaderParser::LinkHeader.parse` as shown in the examples below. The naming conventions for `LinkHeader`'s instance methods draws heavily on the terminology established in [RFC-5988](https://tools.ietf.org/html/rfc5988) and [RFC-8288](https://tools.ietf.org/html/rfc8288).
+
+### Link Target ([§ 3.1](https://tools.ietf.org/html/rfc8288#section-3.1))
+
+```ruby
+link_header = LinkHeaderParser::LinkHeader.parse(%(</index.html>; rel="home"), base_uri: "https://website.example")
+
+link_header.target_string
+#=> "/index.html"
+
+link_header.target_uri
+#=> "https://website.example/index.html"
+```
+
+The `target_string` method returns a string of the value between the opening and closing angle brackets at the beginning of the Link header. The `target_uri` method returns a string representing the resolved URL.
+
+### Link Context ([§ 3.2](https://tools.ietf.org/html/rfc8288#section-3.2))
+
+```ruby
+link_header = LinkHeaderParser::LinkHeader.parse(%(</chapters/1>; anchor="#copyright"; rel="license"), base_uri: "https://website.example")
+
+link_header.context_string
+#=> "#copyright"
+
+link_header.context_uri
+#=> "https://website.example/chapters/1#copyright"
+```
+
+The `anchor` parameter's value may be a fragment identifier (e.g. `#copyright`), a relative URL (e.g. `/copyright`), or an absolute URL (e.g. `https://website.example/copyright`). The `context_string` method returns the `anchor` parameter's value (when present) and defaults to the `target_string` value. The `context_uri` method returns a string representing the resolved URL.
+
+### Relation Type ([§ 3.3](https://tools.ietf.org/html/rfc8288#section-3.3))
+
+```ruby
+link_header = LinkHeaderParser::LinkHeader.parse(%(</chapters/1>; rel="prev start"), base_uri: "https://website.example")
+
+link_header.relations_string
+#=> "prev start"
+
+link_header.relation_types
+#=> ["prev", "start"]
+```
+
+### Target Attributes ([Appendix B.3](https://tools.ietf.org/html/rfc8288#appendix-B.2))
+
+```ruby
+link_header = LinkHeaderParser::LinkHeader.parse(%(</posts.rss>; rel="alternate"; hreflang="en-US"; title="Posts"; type="application/rss+xml"), base_uri: "https://website.example")
+
+link_header.target_attributes
+#=>
+[
+  #<LinkHeaderParser::TargetAttribute @name="rel" @value="alternate">,
+  #<LinkHeaderParser::TargetAttribute @name="hreflang" @value="en-US">,
+  #<LinkHeaderParser::TargetAttribute @name="title" @value="Posts">,
+  #<LinkHeaderParser::TargetAttribute @name="type" @value="application/rss+xml">
+]
+```
+
+> [!NOTE]
+> The `target_attributes` method returns a `TargetAttributeSet`, an `Array`-like object. Its elements, instances of `TargetAttribute`, may include multiple `TargetAttribute`s with the same `name` depending on the provided HTTP Link header. Some methods on `LinkHeader` return values from _only the first occurrence_ of a target attribute's name (e.g. `link_header.relations_string`) in accordance with [RFC-8288](https://tools.ietf.org/html/rfc8288).
+
+## Working with a `TargetAttributeSet`
+
+Beyond standard `Array` methods, the `TargetAttributeSet` adds a `find_by_name` method that may be used to locate the first occurrence of a particular target attribute. Building on the example above:
+
+```ruby
+link_header.target_attributes.find_by_name("type")
+#=> #<LinkHeaderParser::TargetAttribute @name="type" @value="application/rss+xml">
+```
+
+## Creating HTTP Link headers
+
+From v7.0.0, link-header-parser-ruby may be used to created HTTP Link headers. It's maybe not the most efficient way to do this, but it's possible:
+
+```ruby
+# Create a new `LinkHeader` for the `/feed.rss` target string.
+link_header = LinkHeaderParser::LinkHeader.new("/feed.rss", base_uri: "https://website.example")
+
+# Append a target attribute using `Array#<<`.
+link_header.target_attributes << "rel=alternate"
+
+# Append multiple target attributes using `Array#append`.
+link_header.target_attributes.append(%(hreflang="en-US"), LinkHeaderParser::TargetAttribute.new(name: "type", value: "application/rss+xml"))
+
+# Coerce the `LinkHeader` and its target attributes to a string.
+link_header.to_s
+#=> "</feed.rss>; rel=\"alternate\"; hreflang=\"en-US\"; type=\"application/rss+xml\""
+```
+
+> [!TIP]
+> When adding elements to either a `LinkHeaderSet` or `TargetAttributeSet`, you may pass a string or an instance of the related object (`LinkHeader` and `TargetAttribute` respectively). As necessary, link-header-parser will automatically create a new instance of the related object using the provided input before adding the new element.
+
+## Exception Handling
+
+link-header-parser-ruby may raise an `Addressable::URI::InvalidURIError` exception if the value passed to the `base_uri` option is an invalid URI (e.g. `https:`).

data/lib/link-header-parser.rb

@@ -1,28 +1,31 @@
 # frozen_string_literal: true
 
-require "forwardable"
-require "uri"
+require "delegate"
+
+require "addressable/uri"
 
 require_relative "link_header_parser/link_header"
-require_relative "link_header_parser/link_header_parameter"
-require_relative "link_header_parser/link_headers_collection"
+require_relative "link_header_parser/link_header_set"
+require_relative "link_header_parser/target_attribute"
+require_relative "link_header_parser/target_attribute_set"
 
 module LinkHeaderParser
   # Parse an array of HTTP Link headers.
   #
-  # Convenience method for {LinkHeaderParser::LinkHeadersCollection#initialize}.
+  # Convenience method for {LinkHeaderSet#initialize}.
   #
   # @example
   #   require "net/http"
   #
-  #   url = "https://sixtwothree.org"
+  #   url = "https://website.example"
   #   link_headers = Net::HTTP.get_response(URI.parse(url)).get_fields("Link")
   #
-  #   LinkHeaderParser.parse(link_headers, base: url)
+  #   LinkHeaderParser.parse(link_headers, base_uri: url)
+  #
+  # @param (see LinkHeaderSet#initialize)
   #
-  # @param (see LinkHeaderParser::LinkHeadersCollection#initialize)
-  # @return (see LinkHeaderParser::LinkHeadersCollection#initialize)
-  def self.parse(*headers, base:)
-    LinkHeadersCollection.new(*headers, base: base)
+  # @return [LinkHeaderSet]
+  def self.parse(*field_values, base_uri:)
+    LinkHeaderSet.new(*field_values, base_uri: base_uri)
   end
 end

data/lib/link_header_parser/link_header.rb

@@ -8,21 +8,58 @@ module LinkHeaderParser
     PARAMETERS_REGEXP_PATTERN = /(?<!;)\s*[^;]+/.freeze
     private_constant :PARAMETERS_REGEXP_PATTERN
 
-    # The +String+ value used to create this {LinkHeader}.
+    # Parse a +field_value+ string into a {LinkHeader}.
     #
-    # @return [String]
-    attr_reader :field_value
+    # @example
+    #   url = "https://website.example"
+    #   link_header = %(</webmentions>; rel="webmention")
+    #
+    #   LinkHeaderParser::LinkHeader.parse(link_header, base_uri: url)
+    #
+    # @param field_value [String, #to_s]
+    # @param base_uri (see #initialize)
+    #
+    # @return [self]
+    def self.parse(field_value, base_uri:)
+      return field_value if field_value.is_a?(self)
+
+      match_data = field_value.to_s.match(FIELD_VALUE_REGEXP_PATTERN)
+
+      new(match_data[:target_string], *match_data[:parameters].scan(PARAMETERS_REGEXP_PATTERN), base_uri: base_uri)
+    end
+
+    # @return [Addressable::URI]
+    attr_reader :base_uri
+
+    # The parsed parameters for this Link header extracted from +field_value+.
+    #
+    # @see https://tools.ietf.org/html/rfc8288#appendix-B.2
+    #   IETF RFC 8288 Web Linking Appendix B.2.2.4 Parsing a Link Field Value
+    #
+    # @return [TargetAttributeSet]
+    attr_reader :target_attributes
 
-    # Create a new parsed Link header.
+    # The target URL for this Link header extracted from +field_value+.
     #
     # @see https://tools.ietf.org/html/rfc8288#appendix-B.2
-    #   IETF RFC 8288 Web Linking Appendix B.2 Parsing a Link Field Value
+    #   IETF RFC 8288 Web Linking Appendix B.2.2.4 Parsing a Link Field Value
+    #
+    # @return [String]
+    attr_reader :target_string
+
+    # Create a new {LinkHeader}.
     #
-    # @param field_value [String, #to_str]
-    # @param base [String, #to_str]
-    def initialize(field_value, base:)
-      @field_value = field_value.to_str
-      @base = base.to_str
+    # @see LinkParameter.parse
+    #
+    # @param target_string [String, #to_s]
+    # @param link_parameters [Array<String, #to_s>]
+    # @param base_uri [String, #to_s]
+    #
+    # @raise [Addressable::URI::InvalidURIError]
+    def initialize(target_string, *link_parameters, base_uri:)
+      @target_string = target_string.to_s.strip
+      @target_attributes = TargetAttributeSet.new(*link_parameters)
+      @base_uri = Addressable::URI.parse(base_uri)
     end
 
     # The context URL for this Link header extracted from +field_value+ (or
@@ -33,7 +70,7 @@ module LinkHeaderParser
     #
     # @return [String]
     def context_string
-      @context_string ||= grouped_link_parameters[:anchor]&.first || target_string
+      target_attributes.find_by_name("anchor")&.value || target_string
     end
 
     # The resolved context URL for this Link header.
@@ -43,38 +80,16 @@ module LinkHeaderParser
     #
     # @return [String]
     def context_uri
-      @context_uri ||= URI.join(target_uri, context_string).normalize.to_s
+      Addressable::URI.join(target_uri, context_string).to_s
     end
 
     # @return [String]
     def inspect
-      "#<#{self.class.name}:#{format("%#0x", object_id)} " \
-        "target_uri: #{target_uri.inspect}, " \
-        "relation_types: #{relation_types.inspect}>"
-    end
-
-    # The parsed parameters for this Link header extracted from +field_value+.
-    #
-    # @see https://tools.ietf.org/html/rfc8288#appendix-B.3
-    #   IETF RFC 8288 Web Linking Appendix B.3 Parsing Parameters
-    #
-    # @return [Array<LinkHeaderParser::LinkHeaderParameter>]
-    def link_parameters
-      @link_parameters ||= field_value_match_data[:parameters]
-                             .scan(PARAMETERS_REGEXP_PATTERN)
-                             .map { |parameter| LinkHeaderParameter.new(parameter.strip) }
-    end
-
-    # The +relations_string+ value returned as an +Array+.
-    #
-    # @see LinkHeader#relations_string
-    #
-    # @see https://tools.ietf.org/html/rfc8288#appendix-B.2
-    #   IETF RFC 8288 Web Linking Appendix B.2.2.10 and Appendix B.2.2.17.1 Parsing a Link Field Value
-    #
-    # @return [Array<String>]
-    def relation_types
-      @relation_types ||= relations_string.split.map(&:downcase)
+      format "#<%<class>s:%<id>#0x @base_uri=%<base_uri>s @target_string=%<target_string>s>",
+             class: self.class,
+             id: object_id << 1,
+             base_uri: base_uri.inspect,
+             target_string: target_string.inspect
     end
 
     # The relation types for this Link header extracted from +field_value+.
@@ -84,17 +99,19 @@ module LinkHeaderParser
     #
     # @return [String]
     def relations_string
-      @relations_string ||= grouped_link_parameters[:rel]&.first.to_s
+      target_attributes.find_by_name("rel")&.value.to_s
     end
 
-    # The target URL for this Link header extracted from +field_value+
+    # The +relations_string+ value returned as an array.
+    #
+    # @see #relations_string
     #
     # @see https://tools.ietf.org/html/rfc8288#appendix-B.2
-    #   IETF RFC 8288 Web Linking Appendix B.2.2.4 Parsing a Link Field Value
+    #   IETF RFC 8288 Web Linking Appendix B.2.2.10 and Appendix B.2.2.17.1 Parsing a Link Field Value
     #
-    # @return [String]
-    def target_string
-      @target_string ||= field_value_match_data[:target_string]
+    # @return [Array<String>]
+    def relation_types
+      relations_string.split.map(&:downcase)
     end
 
     # The resolved target URL for this Link header.
@@ -104,40 +121,14 @@ module LinkHeaderParser
     #
     # @return [String]
     def target_uri
-      @target_uri ||= URI.join(base, target_string).normalize.to_s
-    end
-
-    # Return a +Hash+ representation of this {LinkHeader}.
-    #
-    # @return [Hash{Symbol => String, Array, Hash{Symbol => Array}}]
-    def to_hash
-      {
-        target_string: target_string,
-        target_uri: target_uri,
-        context_string: context_string,
-        context_uri: context_uri,
-        relations_string: relations_string,
-        relation_types: relation_types,
-        link_parameters: grouped_link_parameters,
-      }
+      @target_uri ||= base_uri.join(target_string).to_s
     end
 
-    alias to_h to_hash
-
-    private
-
-    attr_reader :base
-
-    def field_value_match_data
-      @field_value_match_data ||= field_value.match(FIELD_VALUE_REGEXP_PATTERN)
+    # @return [String]
+    def to_str
+      "<#{target_string}>; #{target_attributes}"
     end
 
-    def grouped_link_parameters
-      @grouped_link_parameters ||= link_parameters
-                                     .map(&:to_a)
-                                     .group_by(&:shift)
-                                     .transform_keys(&:to_sym)
-                                     .transform_values(&:flatten)
-    end
+    alias to_s to_str
   end
 end

data/lib/link_header_parser/link_header_set.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module LinkHeaderParser
+  class LinkHeaderSet < SimpleDelegator
+    # Create a new {LinkHeaderSet} from an array of HTTP Link header
+    # +field_values+.
+    #
+    # @example
+    #   require "net/http"
+    #
+    #   url = "https://website.example"
+    #   link_headers = Net::HTTP.get_response(URI.parse(url)).get_fields("Link")
+    #
+    #   LinkHeaderParser::LinkHeaderSet.new(link_headers, base_uri: url)
+    #
+    # @param field_values [Array<String>]
+    # @param base_uri (see LinkHeader.parse)
+    def initialize(*field_values, base_uri:)
+      @base_uri = base_uri
+
+      super(parsed_link_headers_from(field_values))
+    end
+
+    # Append an HTTP Link header to this {LinkHeaderSet}.
+    #
+    # @param field_value [String]
+    #
+    # @return [self]
+    def <<(field_value)
+      super(*parsed_link_headers_from(field_value))
+    end
+
+    # Append one or more HTTP Link headers to this {LinkHeaderSet}.
+    #
+    # @param field_values [Array<String>]
+    #
+    # @return [self]
+    def append(*field_values)
+      super(*parsed_link_headers_from(field_values))
+    end
+
+    # Obtain a hash of this {LinkHeaderSet}'s {LinkHeader}s grouped by their
+    # relation types.
+    #
+    # @return [Hash{String => LinkHeaderSet<LinkHeader>}]
+    def group_by_relation_type
+      obj = relation_types.to_h { |relation_type| [relation_type, LinkHeaderSet.new(base_uri: base_uri)] }
+
+      each_with_object(obj) do |link_header, hash|
+        link_header.relation_types.each { |relation_type| hash[relation_type] << link_header }
+      end
+    end
+
+    # @return [String]
+    def inspect
+      format "#<%<class>s:%<id>#0x @base_uri=%<base_uri>s>",
+             class: self.class,
+             id: object_id << 1,
+             base_uri: base_uri.inspect
+    end
+
+    # Retrieve a unique sorted array of this collection's {LinkHeader}
+    # relation types.
+    #
+    # @return [Array<String>]
+    def relation_types
+      Set.new(flat_map(&:relation_types)).to_a.sort
+    end
+
+    # @return [String]
+    def to_str
+      join(", ")
+    end
+
+    alias to_s to_str
+
+    # Prepend one or more HTTP Link headers to this {LinkHeaderSet}.
+    #
+    # @param field_values [Array<String>]
+    #
+    # @return [self]
+    def unshift(*field_values)
+      super(*parsed_link_headers_from(field_values))
+    end
+
+    private
+
+    attr_reader :base_uri
+
+    # @return [self]
+    def parsed_link_headers_from(*field_values)
+      field_values.flatten!
+      field_values.map { |field_value| LinkHeader.parse(field_value, base_uri: base_uri) }
+    end
+  end
+end

data/lib/link_header_parser/target_attribute.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module LinkHeaderParser
+  class TargetAttribute
+    # @see https://tools.ietf.org/html/rfc8288#appendix-B.3
+    #    IETF RFC 8288 Web Linking Appendix B.3 Parsing Parameters
+    # @see https://tools.ietf.org/html/rfc8288#appendix-B.4
+    #    IETF RFC 8288 Web Linking Appendix B.4 Parsing a Quoted String
+    PARAMETER_REGEXP_PATTERN = /^(?<name>.+?)(?:=\s*"?(?<value>.*?)"?)?$/.freeze
+    private_constant :PARAMETER_REGEXP_PATTERN
+
+    # Parse a +link_parameter+ string into a {TargetAttribute}.
+    #
+    # @example
+    #   LinkHeaderParser::TargetAttribute.parse(%(rel="webmention"))
+    #
+    # @param link_parameter [String, #to_s]
+    #
+    # @return [self]
+    def self.parse(link_parameter)
+      return link_parameter if link_parameter.is_a?(self)
+
+      new(**link_parameter.to_s.match(PARAMETER_REGEXP_PATTERN).named_captures.transform_keys(&:to_sym))
+    end
+
+    # @return [String]
+    attr_reader :name
+
+    # @return [String]
+    attr_reader :value
+
+    # Create a new {TargetAttribute}.
+    #
+    # @see https://tools.ietf.org/html/rfc8288#appendix-B.2
+    #   IETF RFC 8288 Web Linking Appendix B.2.2.4 Parsing a Link Field Value
+    #
+    # @param name [String, #to_s]
+    # @param value [String, #to_s]
+    def initialize(name:, value:)
+      @name = name.to_s.strip.downcase
+      @value = value.to_s.strip
+    end
+
+    # @return [String]
+    def inspect
+      format "#<%<class>s:%<id>#0x @name=%<name>s @value=%<value>s>",
+             class: self.class,
+             id: object_id << 1,
+             name: name.inspect,
+             value: value.inspect
+    end
+
+    # @return [String]
+    def to_str
+      %(#{name}="#{value}")
+    end
+
+    alias to_s to_str
+  end
+end

data/lib/link_header_parser/target_attribute_set.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module LinkHeaderParser
+  class TargetAttributeSet < SimpleDelegator
+    # Create a new {TargetAttributeSet} from an array of HTTP Link header
+    # +link_parameters+.
+    #
+    # @param link_parameters [Array<String>]
+    def initialize(*link_parameters)
+      super(parsed_target_attributes_from(link_parameters))
+    end
+
+    # Append an HTTP Link header parameter to this {TargetAttributeSet}.
+    #
+    # @param parameter_value [String]
+    #
+    # @return [self]
+    def <<(parameter_value)
+      super(*parsed_target_attributes_from(parameter_value))
+    end
+
+    # Append one or more HTTP Link header parameters to this
+    # {TargetAttributeSet}.
+    #
+    # @param link_parameters [Array<String>]
+    #
+    # @return [self]
+    def append(*link_parameters)
+      super(*parsed_target_attributes_from(link_parameters))
+    end
+
+    # Find and retrieve a {TargetAttribute} from this {TargetAttributeSet} by
+    # its +#name+.
+    #
+    # @return [TargetAttribute, nil]
+    def find_by_name(name)
+      find { |target_attribute| target_attribute.name == name }
+    end
+
+    # @return [String]
+    def inspect
+      format "#<%<class>s:%<id>#0x>",
+             class: self.class,
+             id: object_id << 1
+    end
+
+    # @return [String]
+    def to_str
+      join("; ")
+    end
+
+    alias to_s to_str
+
+    # Prepend one or more HTTP Link header parameter to this
+    # {TargetAttributeSet}.
+    #
+    # @param link_parameters [Array<String>]
+    #
+    # @return [self]
+    def unshift(*link_parameters)
+      super(*parsed_target_attributes_from(link_parameters))
+    end
+
+    private
+
+    # @return [self]
+    def parsed_target_attributes_from(*link_parameters)
+      link_parameters.flatten!
+      link_parameters.map { |parameter_value| TargetAttribute.parse(parameter_value) }
+    end
+  end
+end

data/link-header-parser.gemspec

@@ -4,7 +4,7 @@ Gem::Specification.new do |spec|
   spec.required_ruby_version = ">= 2.6"
 
   spec.name          = "link-header-parser"
-  spec.version       = "6.1.1"
+  spec.version       = "7.0.0"
   spec.authors       = ["Jason Garber"]
   spec.email         = ["jason@sixtwothree.org"]
 
@@ -14,7 +14,7 @@ Gem::Specification.new do |spec|
   spec.license       = "MIT"
 
   spec.files         = Dir["lib/**/*"].reject { |f| File.directory?(f) }
-  spec.files        += ["LICENSE", "CHANGELOG.md", "README.md"]
+  spec.files        += ["LICENSE", "CHANGELOG.md", "README.md", "USAGE.md"]
   spec.files        += ["link-header-parser.gemspec"]
 
   spec.require_paths = ["lib"]
@@ -27,4 +27,6 @@ Gem::Specification.new do |spec|
     "rubygems_mfa_required" => "true",
     "source_code_uri" => "#{spec.homepage}/src/tag/v#{spec.version}",
   }
+
+  spec.add_dependency "addressable", "~> 2.8"
 end

metadata

@@ -1,14 +1,28 @@
 --- !ruby/object:Gem::Specification
 name: link-header-parser
 version: !ruby/object:Gem::Version
-  version: 6.1.1
+  version: 7.0.0
 platform: ruby
 authors:
 - Jason Garber
 bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
-dependencies: []
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: addressable
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.8'
 description: Parse HTTP Link headers.
 email:
 - jason@sixtwothree.org
@@ -19,21 +33,23 @@ files:
 - CHANGELOG.md
 - LICENSE
 - README.md
+- USAGE.md
 - lib/link-header-parser.rb
 - lib/link_header_parser/link_header.rb
-- lib/link_header_parser/link_header_parameter.rb
-- lib/link_header_parser/link_headers_collection.rb
+- lib/link_header_parser/link_header_set.rb
+- lib/link_header_parser/target_attribute.rb
+- lib/link_header_parser/target_attribute_set.rb
 - link-header-parser.gemspec
 homepage: https://codeberg.org/jgarber/link-header-parser-ruby
 licenses:
 - MIT
 metadata:
   bug_tracker_uri: https://codeberg.org/jgarber/link-header-parser-ruby/issues
-  changelog_uri: https://codeberg.org/jgarber/link-header-parser-ruby/releases/tag/v6.1.1
-  documentation_uri: https://rubydoc.info/gems/link-header-parser/6.1.1
+  changelog_uri: https://codeberg.org/jgarber/link-header-parser-ruby/releases/tag/v7.0.0
+  documentation_uri: https://rubydoc.info/gems/link-header-parser/7.0.0
   homepage_uri: https://codeberg.org/jgarber/link-header-parser-ruby
   rubygems_mfa_required: 'true'
-  source_code_uri: https://codeberg.org/jgarber/link-header-parser-ruby/src/tag/v6.1.1
+  source_code_uri: https://codeberg.org/jgarber/link-header-parser-ruby/src/tag/v7.0.0
 rdoc_options: []
 require_paths:
 - lib

data/lib/link_header_parser/link_header_parameter.rb

@@ -1,58 +0,0 @@
-# frozen_string_literal: true
-
-module LinkHeaderParser
-  class LinkHeaderParameter
-    PARAMETER_REGEXP_PATTERN = /^(?<name>.+?)(?:="?(?<value>.*?)"?)?$/.freeze
-    private_constant :PARAMETER_REGEXP_PATTERN
-
-    # The +String+ value used to create this {LinkHeaderParameter}.
-    #
-    # @return [String]
-    attr_reader :parameter
-
-    # Create a new parsed Link header parameter.
-    #
-    # @param parameter [String, #to_str]
-    def initialize(parameter)
-      @parameter = parameter.to_str
-    end
-
-    # @return [String]
-    def inspect
-      "#<#{self.class.name}:#{format("%#0x", object_id)} " \
-        "name: #{name.inspect}, " \
-        "value: #{value.inspect}>"
-    end
-
-    # @see https://tools.ietf.org/html/rfc8288#appendix-B.3
-    #   IETF RFC 8288 Web Linking Appendix B.3.2.9 Parsing Parameters
-    #
-    # @return [String]
-    def name
-      @name ||= parameter_match_data[:name].downcase
-    end
-
-    # @see https://tools.ietf.org/html/rfc8288#appendix-B.3
-    #   IETF RFC 8288 Web Linking Appendix B.3.2.8 Parsing Parameters
-    #
-    # @return [String]
-    def value
-      @value ||= parameter_match_data[:value].to_s
-    end
-
-    # Return an +Array+ representation of this {LinkHeaderParameter}.
-    #
-    # @return [Array<String>]
-    def to_ary
-      [name, value]
-    end
-
-    alias to_a to_ary
-
-    private
-
-    def parameter_match_data
-      @parameter_match_data ||= parameter.match(PARAMETER_REGEXP_PATTERN)
-    end
-  end
-end

data/lib/link_header_parser/link_headers_collection.rb

@@ -1,86 +0,0 @@
-# frozen_string_literal: true
-
-module LinkHeaderParser
-  class LinkHeadersCollection
-    extend Forwardable
-
-    include Enumerable
-
-    def_delegators :members, :[], :<<, :each, :last, :length, :push
-
-    # The +Array+ of HTTP Link headers used to create this
-    # {LinkHeadersCollection}.
-    #
-    # @return [Array<String>]
-    attr_reader :headers
-
-    # Parse an array of HTTP Link headers.
-    #
-    # @param headers [Array<String, #to_str>]
-    # @param base [String, #to_str]
-    def initialize(*headers, base:)
-      headers = headers.to_ary
-
-      headers.flatten!
-
-      @headers = headers.map!(&:to_str)
-      @base = base.to_str
-
-      push(*distinct_link_headers)
-    end
-
-    # Retrieve a +Hash+ of this collection's {LinkHeader}s grouped by their
-    # relation type(s).
-    #
-    # @return [Hash{Symbol => Array<LinkHeaderParser::LinkHeader>}]
-    def group_by_relation_type
-      relation_types.to_h do |relation_type|
-        [relation_type.to_sym, select_by_relation_type(relation_type)]
-      end
-    end
-
-    # @return [String]
-    def inspect
-      "#<#{self.class.name}:#{format("%#0x", object_id)} " \
-        "headers: #{headers.inspect}, " \
-        "relation_types: #{relation_types.inspect}>"
-    end
-
-    # Retrieve a unique sorted +Array+ of this collection's {LinkHeader}
-    # relation types.
-    #
-    # @return [Array<String>]
-    def relation_types
-      @relation_types ||= Set.new(flat_map(&:relation_types)).to_a.sort
-    end
-
-    # Return an +Array+ representation of this {LinkHeadersCollection}.
-    #
-    # @see LinkHeader#to_hash
-    #
-    # @return [Array<Hash>}>]
-    def to_ary
-      map(&:to_hash)
-    end
-
-    alias to_a to_ary
-
-    private
-
-    attr_reader :base
-
-    def distinct_link_headers
-      headers
-        .flat_map { |header| header.split(/,(?=[\s|<])/) }
-        .map { |header| LinkHeader.new(header.strip, base: base) }
-    end
-
-    def members
-      @members ||= []
-    end
-
-    def select_by_relation_type(relation_type)
-      select { |member| member.relation_types.include?(relation_type) }
-    end
-  end
-end