link-header-parser 4.0.0 → 5.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 173d1c05e3a5c2fe7d8e99454249d73ce780cfcc3bb120d7be5145e9b376ea54
-  data.tar.gz: a79af8ae39af06d3a4625eab54aa8f51d4574f5789c913d570919c20f877febc
+  metadata.gz: a3bede096a22050eb158b8c5e55a8467cf2a0abb91a7058962ab99b1aebe9162
+  data.tar.gz: 02a647ff14be96c4dfc11f571694d90ef2e75fe2b3930ceb09c0ecb0ab55d92a
 SHA512:
-  metadata.gz: 48085ca777ca8b2e6d859e2920165d7336cd2b909efbdfcc63aaff1980859d77e8cb6f0455dc61c8b089d143206d435639b49a9aef9a7f151c21ca683e9af07d
-  data.tar.gz: 8fbd4c92cced717fc2a41d213209067824288810d14053236e6ca3ee1363c421a89c49be4ac6f34f9cc3736c91108ec58779a2638fca1efcbbf314ae5bbf1c84
+  metadata.gz: af0da321a1652d3f6740fb4396a95d66213334b04eec1bd794652de894f2c7b6d9effd52701722ca851fbb01bcc38601e4c80b20290cede4b4856f36e6436520
+  data.tar.gz: ea527e8a58c23acafc460a73224d72204d9b82074dfa53275518eea5fd1aad940489d4efc5b770700a7aaf120160e8f589c36f56d9965ffba47d23174a09c73a

data/CHANGELOG.md

@@ -1,11 +1,20 @@
 # Changelog
 
+## 5.0.0 / 2022-11-09
+
+- **Breaking change:** Add `#to_ary`/`#to_a` method to `LinkHeadersCollection` (6a478ed)
+	- Note: marking this as a breaking change since it changes the existing behavior to return an `Array` of `Hash`es instead of an `Array` of `LinkHeader`s
+- **Breaking change:** Update project Ruby version to 2.7.6 and minimum Ruby version to 2.7 (1e9df45)
+- Improve documentation and privatize constants (8a68aa0)
+- Remove Reek development dependency (423bc7a)
+- Use ruby/debug gem instead of pry-byebug (4cd9d26)
+
 ## 4.0.0 / 2022-01-06
 
 - Remove Addressable dependency (daedf22)
 - **Breaking change:** Update minimum Ruby version to 2.6 (e2343ed)
 - Migrate to GitHub Actions (509b2c4)
-- Update project Ruby version to 2.6.9 (c39bc66)
+- Update project Ruby version to 2.6.10 (c39bc66)
 
 ## 3.0.0 / 2021-05-22
 

data/CONTRIBUTING.md

@@ -8,9 +8,9 @@ There are a couple ways you can help improve link-header-parser-ruby:
 
 ## Getting Started
 
-link-header-parser-ruby is developed using Ruby 2.6.9 and is additionally tested against Ruby 2.7, 3.0, and 3.1 using [GitHub Actions](https://github.com/jgarber623/link-header-parser-ruby/actions).
+link-header-parser-ruby is developed using Ruby 2.7.6 and is additionally tested against Ruby 3.0 and 3.1 using [GitHub Actions](https://github.com/jgarber623/link-header-parser-ruby/actions).
 
-Before making changes to link-header-parser-ruby, you'll want to install Ruby 2.6.9. It's recommended that you use 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). Once you've installed Ruby 2.6.9 using your method of choice, install the project's gems by running:
+Before making changes to link-header-parser-ruby, you'll want to install Ruby 2.7.6. It's recommended that you use 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). Once you've installed Ruby 2.7.6 using your method of choice, install the project's gems by running:
 
 ```sh
 bundle install
@@ -22,7 +22,7 @@ bundle install
 1. Install development dependencies as outlined above.
 1. Create a feature branch for the code changes you're looking to make: `git checkout -b my-new-feature`.
 1. _Write some code!_
-1. If your changes would benefit from testing, add the necessary tests and verify everything passes by running `bin/ci`.
+1. If your changes would benefit from testing, add the necessary tests and verify everything passes by running `bundle exec rspec`.
 1. Commit your changes: `git commit -am 'Add some new feature or fix some issue'`. _(See [this excellent article](https://chris.beams.io/posts/git-commit/) for tips on writing useful Git commit messages.)_
 1. Push the branch to your fork: `git push -u origin my-new-feature`.
 1. Create a new [pull request][pulls] and we'll review your changes.

data/README.md

@@ -10,9 +10,9 @@
 
 ## 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. It's recommended that you use 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).
+Before installing and using link-header-parser-ruby, you'll want to have [Ruby](https://www.ruby-lang.org) 2.7 (or newer) installed. It's recommended that you use 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).
 
-link-header-parser-ruby is developed using Ruby 2.6.9 and is additionally tested against Ruby 2.7, 3.0, and 3.1 using [GitHub Actions](https://github.com/jgarber623/link-header-parser-ruby/actions).
+link-header-parser-ruby is developed using Ruby 2.7.6 and is additionally tested against Ruby 3.0 and 3.1 using [GitHub Actions](https://github.com/jgarber623/link-header-parser-ruby/actions).
 
 ## Installation
 
@@ -35,14 +35,13 @@ $ bundle install
 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 'http'
+require 'net/http'
 require 'link-header-parser'
 
-response = HTTP.get('https://sixtwothree.org')
+url = 'https://sixtwothree.org'
+link_headers = Net::HTTP.get_response(URI.parse(url)).get_fields('Link')
 
-link_headers = response.headers.get('link')
-
-collection = LinkHeaderParser.parse(link_headers, base: response.uri)
+collection = LinkHeaderParser.parse(link_headers, base: url)
 ```
 
 The `parse` method accepts two arguments:

data/lib/link-header-parser.rb

@@ -9,11 +9,20 @@ require_relative 'link_header_parser/link_header_parameter'
 require_relative 'link_header_parser/link_headers_collection'
 
 module LinkHeaderParser
-  # Parse an array of HTTP Link headers
+  # Parse an array of HTTP Link headers.
   #
-  # @param headers [Array<String>]
-  # @param base [String]
-  # @return [LinkHeaderParser::LinkHeadersCollection]
+  # Convenience method for {LinkHeaderParser::LinkHeadersCollection#initialize}.
+  #
+  # @example
+  #   require 'net/http'
+  #
+  #   url = 'https://sixtwothree.org'
+  #   link_headers = Net::HTTP.get_response(URI.parse(url)).get_fields('Link')
+  #
+  #   LinkHeaderParser.parse(link_headers, base: url)
+  #
+  # @param (see LinkHeaderParser::LinkHeadersCollection#initialize)
+  # @return (see LinkHeaderParser::LinkHeadersCollection#initialize)
   def self.parse(*headers, base:)
     LinkHeadersCollection.new(*headers, base: base)
   end

data/lib/link_header_parser/link_header.rb

@@ -3,30 +3,43 @@
 module LinkHeaderParser
   class LinkHeader
     FIELD_VALUE_REGEXP_PATTERN = /^\s*<\s*(?<target_string>[^>]+)\s*>\s*(?<parameters>;\s*.*)$/.freeze
+    private_constant :FIELD_VALUE_REGEXP_PATTERN
+
     PARAMETERS_REGEXP_PATTERN = /(?<!;)\s*([^;]+)/.freeze
+    private_constant :PARAMETERS_REGEXP_PATTERN
 
+    # The +String+ value used to create this {LinkHeader}.
+    #
+    # @return [String]
     attr_reader :field_value
 
-    # Create a new parsed Link header
+    # Create a new parsed Link header.
+    #
     # @see https://tools.ietf.org/html/rfc8288#appendix-B.2
+    #   IETF RFC 8288 Web Linking Appendix B.2 Parsing a Link Field Value
     #
-    # @param field_value [String]
-    # @param base [String]
+    # @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
     end
 
-    # The context URL for this Link header extracted from field_value (or target URL if no context URL is present)
-    # @see https://tools.ietf.org/html/rfc8288#appendix-B.2 (Appendix B.2.2.11)
+    # The context URL for this Link header extracted from +field_value+ (or
+    # target URL if no context URL is present).
+    #
+    # @see https://tools.ietf.org/html/rfc8288#appendix-B.2
+    #   IETF RFC 8288 Web Linking Appendix B.2.2.11 Parsing a Link Field Value
     #
     # @return [String]
     def context_string
       @context_string ||= grouped_link_parameters[:anchor]&.first || target_string
     end
 
-    # The resolved context URL for this Link header
-    # @see https://tools.ietf.org/html/rfc8288#appendix-B.2 (Appendix B.2.2.12)
+    # The resolved context URL for this Link header.
+    #
+    # @see https://tools.ietf.org/html/rfc8288#appendix-B.2
+    #   IETF RFC 8288 Web Linking Appendix B.2.2.12 Parsing a Link Field Value
     #
     # @return [String]
     def context_uri
@@ -40,8 +53,10 @@ module LinkHeaderParser
         "relation_types: #{relation_types.inspect}>"
     end
 
-    # The parsed parameters for this Link header extracted from field_value
+    # 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
@@ -50,38 +65,50 @@ module LinkHeaderParser
                                                               .map { |parameter| LinkHeaderParameter.new(parameter) }
     end
 
-    # The relations_string value returned as an Array
-    # @see https://tools.ietf.org/html/rfc8288#appendix-B.2 (Appendix B.2.2.10 and Appendix B.2.2.17.1)
+    # 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)
     end
 
-    # The relation types for this Link header extracted from field_value
-    # @see https://tools.ietf.org/html/rfc8288#appendix-B.2 (Appendix B.2.2.9)
+    # The relation types 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.9 Parsing a Link Field Value
     #
     # @return [String]
     def relations_string
       @relations_string ||= grouped_link_parameters[:rel]&.first.to_s
     end
 
-    # The target URL for this Link header extracted from field_value
-    # @see https://tools.ietf.org/html/rfc8288#appendix-B.2 (Appendix B.2.2.4)
+    # 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.2.4 Parsing a Link Field Value
     #
     # @return [String]
     def target_string
       @target_string ||= field_value_match_data[:target_string]
     end
 
-    # The resolved target URL for this Link header
-    # @see https://tools.ietf.org/html/rfc8288#appendix-B.2 (Appendix B.2.2.8)
+    # The resolved target URL for this Link header.
+    #
+    # @see https://tools.ietf.org/html/rfc8288#appendix-B.2
+    #   IETF RFC 8288 Web Linking Appendix B.2.2.8 Parsing a Link Field Value
     #
     # @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
       {

data/lib/link_header_parser/link_header_parameter.rb

@@ -3,10 +3,16 @@
 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
 
-    # @param parameter [String]
+    # Create a new parsed Link header parameter.
+    #
+    # @param parameter [String, #to_str]
     def initialize(parameter)
       @parameter = parameter.to_str
     end
@@ -18,20 +24,24 @@ module LinkHeaderParser
         "value: #{value.inspect}>"
     end
 
-    # @see https://tools.ietf.org/html/rfc8288#appendix-B.3 (Appendix B.3.2.9)
+    # @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 (Appendix B.3.2.8)
+    # @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]

data/lib/link_header_parser/link_headers_collection.rb

@@ -8,17 +8,26 @@ module LinkHeaderParser
 
     def_delegators :members, :[], :<<, :each, :last, :length, :push
 
+    # The +Array+ of HTTP Link headers used to create this
+    # {LinkHeadersCollection}.
+    #
+    # @return [Array<String>]
     attr_reader :headers
 
-    # @param headers [Array<String>]
-    # @param base [String]
+    # 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.flatten.map(&:to_str)
       @base = base.to_str
 
-      distinct_headers.each { |header| push(LinkHeader.new(header, base: base)) }
+      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|
@@ -33,17 +42,32 @@ module LinkHeaderParser
         "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 ||= flat_map(&:relation_types).uniq.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_headers
-      @distinct_headers ||= headers.flat_map { |header| header.split(/,(?=[\s|<])/) }.map(&:strip)
+    def distinct_link_headers
+      headers.flat_map { |header| header.split(/,(?=[\s|<])/) }
+             .map { |header| LinkHeader.new(header.strip, base: base) }
     end
 
     def members

data/lib/link_header_parser/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module LinkHeaderParser
-  VERSION = '4.0.0'
+  VERSION = '5.0.0'
 end

data/link-header-parser.gemspec

@@ -3,7 +3,7 @@
 require_relative 'lib/link_header_parser/version'
 
 Gem::Specification.new do |spec|
-  spec.required_ruby_version = '>= 2.6', '< 4'
+  spec.required_ruby_version = '>= 2.7', '< 4'
 
   spec.name          = 'link-header-parser'
   spec.version       = LinkHeaderParser::VERSION

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: link-header-parser
 version: !ruby/object:Gem::Version
-  version: 4.0.0
+  version: 5.0.0
 platform: ruby
 authors:
 - Jason Garber
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-01-06 00:00:00.000000000 Z
+date: 2022-11-09 00:00:00.000000000 Z
 dependencies: []
 description: Parse HTTP Link headers.
 email:
@@ -32,7 +32,7 @@ licenses:
 - MIT
 metadata:
   bug_tracker_uri: https://github.com/jgarber623/link-header-parser-ruby/issues
-  changelog_uri: https://github.com/jgarber623/link-header-parser-ruby/blob/v4.0.0/CHANGELOG.md
+  changelog_uri: https://github.com/jgarber623/link-header-parser-ruby/blob/v5.0.0/CHANGELOG.md
   rubygems_mfa_required: 'true'
 post_install_message: 
 rdoc_options: []
@@ -42,7 +42,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.6'
+      version: '2.7'
   - - "<"
     - !ruby/object:Gem::Version
       version: '4'
@@ -52,7 +52,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.33
+rubygems_version: 3.3.16
 signing_key: 
 specification_version: 4
 summary: Parse HTTP Link headers.