accept_language 2.0.7 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 48e16c31c0c78f967fd5f06f753e83088342a4deafaf149f3de8e95f4dbece93
-  data.tar.gz: 4c62d54bea6c53797fea29ba73211bfb576fb34bc38c16f0c4fd941ce806bb9c
+  metadata.gz: 7273e9328183e3dee11fd68a6598d82c67efbb8bab156d6d9b3424d9ed45dcca
+  data.tar.gz: ec31e8a4ac07501f1c481e65452f362be2d7669d93eea626977f25c3aca88dc2
 SHA512:
-  metadata.gz: 4476afd57f2d399c7d588b2354de0c95b0cdbce0c3d3b0c3147950f61a6e41b66497bbe8bc076d80cb0e3ecbe208692f1496c9d0fa3e83c89a5ff747c78172d2
-  data.tar.gz: 65fe33bd3a1d9f6f9ad32ce94f19d3139683e019fd617fbfc36c66b3af2fca0be7c16d70497568f709f54605f6d55a88a465b4f23c4a7a4978b94201bebb7393
+  metadata.gz: 36120af5b03b49ea9dce1d50e5c7915c62bf9b0fa09c1130516090e4e3c882b924035f963ad2dc559fda0e818633b6a3e77aba3e46b25533bc972f5dc23ca729
+  data.tar.gz: d11855f60c7a4a35c8f675ea5ffc4b320db5a4b40cc95e57143b3dad3c188580830ae0052ac7e934f5ae4c5f2be582db47b4e85b9513b78b4ec1fc69a97ee850

data/LICENSE.md

@@ -1,6 +1,6 @@
 # The MIT License
 
-Copyright (c) 2019-2024 Cyril Kato
+Copyright (c) 2019-2026 Cyril Kato
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,89 +1,75 @@
-# Accept Language 🌐
+# AcceptLanguage
 
-Web applications often need to cater to users from around the world. One of the ways they can provide a better user experience is by presenting the content in the user's preferred language. This is where the `Accept-Language` HTTP header comes into play. Sent by the client (usually a web browser), this header tells the server the list of languages the user understands, and the user's preference order.
-
-Parsing the `Accept-Language` header can be complex due to its flexible format defined in [RFC 2616](https://tools.ietf.org/html/rfc2616#section-14.4). For instance, it can specify languages, countries, and scripts with varying degrees of preference (quality values).
-
-`Accept Language` is a lightweight, thread-safe Ruby library designed to parse the `Accept-Language` header, making it easier for your application to determine the best language to respond with. It calculates the intersection of the languages the user prefers and the languages your application supports, handling all the complexity of quality values and wildcards.
-
-Whether you're building a multilingual web application or just trying to make your service more accessible to users worldwide, `Accept Language` offers a reliable, simple solution.
-
-## Status
+A lightweight, thread-safe Ruby library for parsing `Accept-Language` HTTP headers as defined in [RFC 2616](https://tools.ietf.org/html/rfc2616#section-14.4).
 
 [![Version](https://img.shields.io/github/v/tag/cyril/accept_language.rb?label=Version&logo=github)](https://github.com/cyril/accept_language.rb/tags)
 [![Yard documentation](https://img.shields.io/badge/Yard-documentation-blue.svg?logo=github)](https://rubydoc.info/github/cyril/accept_language.rb/main)
-[![Ruby](https://github.com/cyril/accept_language.rb/workflows/Ruby/badge.svg?branch=main)](https://github.com/cyril/accept_language.rb/actions?query=workflow%3Aruby+branch%3Amain)
-[![RuboCop](https://github.com/cyril/accept_language.rb/workflows/RuboCop/badge.svg?branch=main)](https://github.com/cyril/accept_language.rb/actions?query=workflow%3Arubocop+branch%3Amain)
+![Ruby](https://github.com/cyril/accept_language.rb/actions/workflows/ruby.yml/badge.svg?branch=main)
+![RuboCop](https://github.com/cyril/accept_language.rb/actions/workflows/rubocop.yml/badge.svg?branch=main)
 [![License](https://img.shields.io/github/license/cyril/accept_language.rb?label=License&logo=github)](https://github.com/cyril/accept_language.rb/raw/main/LICENSE.md)
 
-## Why Choose Accept Language?
-
-There are a myriad of tools out there, so why should you consider Accept Language for your next project? Here's why:
+## Features
 
-- **Thread-Safe**: Multithreading can present unique challenges when dealing with shared resources. Our implementation is designed to be thread-safe, preventing potential concurrency issues.
-- **Compact and Robust**: Despite being small in size, Accept Language can handle even the trickiest cases with grace, ensuring you have a reliable tool at your disposal.
-- **Case-Insensitive Matching**: In line with the principle of robustness, our tool matches both strings and symbols regardless of case, providing greater flexibility.
-- **Independent of Framework**: While many tools require Rails, Rack, or i18n to function, Accept Language stands on its own. It works perfectly well without these dependencies, increasing its adaptability.
-- **BCP 47 Support**: BCP 47 defines a standard for language tags. This is crucial for specifying languages unambiguously. Accept Language complies with this standard, ensuring accurate language identification.
+- Thread-safe
+- No framework dependencies
+- Case-insensitive matching
+- BCP 47 language tag support
+- Wildcard and exclusion handling
 
 ## Installation
 
-Add this line to your application's Gemfile:
-
 ```ruby
 gem "accept_language"
 ```
 
-And then execute:
+## Usage
 
-```sh
-bundle install
+```ruby
+AcceptLanguage.parse("en-GB, en;q=0.9").match(:en, :"en-GB")
+# => :"en-GB"
 ```
 
-Or install it yourself as:
+### Quality values
 
-```sh
-gem install accept_language
-```
+Quality values (q-values) indicate preference order from 0 to 1:
 
-## Usage
+```ruby
+parser = AcceptLanguage.parse("da, en-GB;q=0.8, en;q=0.7")
 
-`Accept Language` library is primarily designed to assist web servers in serving multilingual content based on user preferences expressed in the `Accept-Language` header. This library finds the best matching language from the available languages your application supports and the languages the user prefers.
+parser.match(:en, :da)      # => :da
+parser.match(:en, :"en-GB") # => :"en-GB"
+parser.match(:fr)           # => nil
+```
 
-Below are some examples of how you might use the library:
+### Language variants
+
+A generic language tag matches its regional variants, but not the reverse:
 
 ```ruby
-# The user prefers Danish, then British English, and finally any kind of English.
-# Since your application supports English and Danish, it selects Danish as it's the user's first choice.
-AcceptLanguage.parse("da, en-GB;q=0.8, en;q=0.7").match(:en, :da) # => :da
+AcceptLanguage.parse("fr").match(:"fr-CH")    # => :"fr-CH"
+AcceptLanguage.parse("fr-CH").match(:fr)      # => nil
+```
 
-# The user prefers Danish, then English, and finally Uyghur. Your application supports British English and Chinese Uyghur.
-# Here, the library will return Chinese Uyghur because it's the highest ranked language in the user's list that your application supports.
-AcceptLanguage.parse("da, en;q=0.8, ug;q=0.9").match("en-GB", "ug-CN") # => "ug-CN"
+### Wildcards and exclusions
 
-# The user prefers Danish, then British English, and finally any kind of English. Your application only supports Japanese.
-# Since none of the user's preferred languages are supported, it returns nil.
-AcceptLanguage.parse("da, en-GB;q=0.8, en;q=0.7").match(:ja) # => nil
+The wildcard `*` matches any language. A q-value of 0 explicitly excludes a language:
 
-# The user only accepts Swiss French, but your application only supports French. Since Swiss French and French are not the same, it returns nil.
-AcceptLanguage.parse("fr-CH").match(:fr) # => nil
+```ruby
+AcceptLanguage.parse("de-DE, *;q=0.5").match(:fr)  # => :fr
+AcceptLanguage.parse("*, en;q=0").match(:en)       # => nil
+AcceptLanguage.parse("*, en;q=0").match(:fr)       # => :fr
+```
 
-# The user prefers German, then any language except French. Your application supports French.
-# Even though the user specified a wildcard, they explicitly excluded French. Therefore, it returns nil.
-AcceptLanguage.parse("de, zh;q=0.4, *;q=0.5, fr;q=0").match(:fr) # => nil
+### Case sensitivity
 
-# The user prefers Uyghur (in Latin script, as used in Uzbekistan). Your application supports this exact variant of Uyghur.
-# Since the user's first choice matches a language your application supports, it returns that language.
-AcceptLanguage.parse("uz-latn-uz").match("uz-Latn-UZ") # => "uz-Latn-UZ"
+Matching is case-insensitive but preserves the case of the available language tag:
 
-# The user doesn't mind what language they get, but they'd prefer not to have English. Your application supports English.
-# Even though the user specified a wildcard, they explicitly excluded English. Therefore, it returns nil.
-AcceptLanguage.parse("*, en;q=0").match("en") # => nil
+```ruby
+AcceptLanguage.parse("en-GB").match("en-gb") # => "en-gb"
+AcceptLanguage.parse("en-gb").match("en-GB") # => "en-GB"
 ```
 
-These examples show the flexibility and power of `Accept Language`. By giving your application a deep understanding of the user's language preferences, `Accept Language` can significantly improve user satisfaction and engagement with your application.
-
-### Rails integration example
+## Rails integration
 
 ```ruby
 # app/controllers/application_controller.rb
@@ -95,6 +81,7 @@ class ApplicationController < ActionController::Base
   end
 
   def best_locale_from_request
+    # HTTP_ACCEPT_LANGUAGE is the standardized key for the Accept-Language header in Rack/Rails
     return I18n.default_locale unless request.headers.key?("HTTP_ACCEPT_LANGUAGE")
 
     string = request.headers.fetch("HTTP_ACCEPT_LANGUAGE")
@@ -111,15 +98,16 @@ class ApplicationController < ActionController::Base
 end
 ```
 
-## Read more
+## Documentation
 
+- [API Documentation](https://rubydoc.info/github/cyril/accept_language.rb/main)
 - [Language negotiation with Ruby](https://dev.to/cyri_/language-negotiation-with-ruby-5166)
 - [Rubyで言語ネゴシエーション](https://qiita.com/cyril/items/45dc233edb7be9d614e7)
 
 ## Versioning
 
-__AcceptLanguage__ uses [Semantic Versioning 2.0.0](https://semver.org/)
+This library follows [Semantic Versioning 2.0.0](https://semver.org/).
 
 ## License
 
-The [gem](https://rubygems.org/gems/accept_language) is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+Available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/accept_language/matcher.rb

@@ -1,23 +1,20 @@
 # frozen_string_literal: true
 
 module AcceptLanguage
-  # A utility class that provides functionality to match the Accept-Language header value
-  # against the languages supported by your application. This helps in identifying the most
-  # suitable languages to present to the user based on their preferences.
+  # Matches Accept-Language header values against application-supported languages to determine
+  # the optimal language choice. Handles quality values, wildcards, and language tag matching
+  # according to RFC 2616 specifications.
   #
-  # @example
-  #   Matcher.new("da" => 1.0, "en-GB" => 0.8, "en" => 0.7).call(:ug, :kk, :ru, :en) # => :en
-  #   Matcher.new("da" => 1.0, "en-GB" => 0.8, "en" => 0.7).call(:fr, :en, :"en-GB") # => :"en-GB"
+  # @api private
+  # @note This class is intended for internal use by {Parser} and should not be instantiated directly.
   class Matcher
+    # @api private
     WILDCARD = "*"
 
+    # @api private
     attr_reader :excluded_langtags, :preferred_langtags
 
-    # Initialize a new Matcher object with the languages_range parameter representing the user's
-    # preferred languages and their respective quality values.
-    #
-    # @param [Hash<String, BigDecimal>] languages_range A hash where keys represent languages and
-    #   values are the quality of preference for each language. A value of zero means the language is not acceptable.
+    # @api private
     def initialize(**languages_range)
       @excluded_langtags = ::Set[]
       langtags = []
@@ -34,40 +31,46 @@ module AcceptLanguage
       @preferred_langtags = langtags.compact.reverse
     end
 
-    # Matches the user's preferred languages against the available languages of your application.
-    # It prioritizes higher quality values and returns the most suitable match.
-    #
-    # @param [Array<String, Symbol>] available_langtags An array representing the languages available in your application.
-    #
-    # @example When Uyghur, Kazakh, Russian and English languages are available.
-    #   call(:ug, :kk, :ru, :en)
-    #
-    # @return [String, Symbol, nil] The language that best matches the user's preferences, or nil if there is no match.
+    # @api private
     def call(*available_langtags)
-      available_langtags = drop_unacceptable(*available_langtags)
+      raise ::ArgumentError, "Language tags cannot be nil" if available_langtags.any?(&:nil?)
 
+      filtered_tags = drop_unacceptable(*available_langtags)
+      return nil if filtered_tags.empty?
+
+      find_best_match(filtered_tags)
+    end
+
+    private
+
+    def find_best_match(available_langtags)
       preferred_langtags.each do |preferred_tag|
-        if wildcard?(preferred_tag)
-          langtag = any_other_langtag(*available_langtags)
-          return langtag unless langtag.nil?
-        else
-          available_langtags.each do |available_langtag|
-            return available_langtag if available_langtag.match?(/\A#{preferred_tag}/i)
-          end
-        end
+        match = match_langtag(preferred_tag, available_langtags)
+        return match if match
       end
 
       nil
     end
 
-    private
+    def match_langtag(preferred_tag, available_langtags)
+      if wildcard?(preferred_tag)
+        any_other_langtag(*available_langtags)
+      else
+        find_matching_tag(preferred_tag, available_langtags)
+      end
+    end
+
+    def find_matching_tag(preferred_tag, available_langtags)
+      pattern = /\A#{::Regexp.escape(preferred_tag)}/i
+      available_langtags.find { |tag| tag.match?(pattern) }
+    end
 
     def any_other_langtag(*available_langtags)
       available_langtags.find do |available_langtag|
         langtags = preferred_langtags - [WILDCARD]
-
-        langtags.none? do |langtag|
-          available_langtag.match?(/\A#{langtag}/i)
+        langtags.none? do |tag|
+          pattern = /\A#{::Regexp.escape(tag)}/i
+          available_langtag.match?(pattern)
         end
       end
     end
@@ -81,8 +84,9 @@ module AcceptLanguage
     end
 
     def unacceptable?(langtag)
-      excluded_langtags.any? do |excluded_langtag|
-        langtag.match?(/\A#{excluded_langtag}/i)
+      excluded_langtags.any? do |excluded_tag|
+        pattern = /\A#{::Regexp.escape(excluded_tag)}/i
+        langtag.match?(pattern)
       end
     end
 

data/lib/accept_language/parser.rb

@@ -3,59 +3,77 @@
 require "bigdecimal"
 
 module AcceptLanguage
-  # Parser is a utility class responsible for parsing Accept-Language header fields.
-  # It processes the field to extract language tags and their respective quality values.
+  # Parses Accept-Language header fields into structured data, extracting language tags
+  # and their quality values (q-values). Validates input according to RFC 2616 specifications
+  # and handles edge cases like malformed inputs and implicit quality values.
   #
   # @example
-  #   Parser.new("da, en-GB;q=0.8, en;q=0.7")
-  #   # => #<AcceptLanguage::Parser:0x00007 @languages_range={"da"=>1.0, "en-GB"=>0.8, "en"=>0.7}>
+  #   parser = Parser.new("da, en-GB;q=0.8, en;q=0.7")
+  #   parser.match(:en, :da) # => :da
   #
-  # @see https://tools.ietf.org/html/rfc2616#section-14.4 for more information on Accept-Language header fields.
+  # @see https://tools.ietf.org/html/rfc2616#section-14.4
   class Parser
-    DEFAULT_QUALITY = BigDecimal("1")
+    # @api private
+    DEFAULT_QUALITY = "1"
+    # @api private
     SEPARATOR = ","
+    # @api private
     SPACE = " "
+    # @api private
     SUFFIX = ";q="
+    # @api private
+    QVALUE_PATTERN = /\A(?:0(?:\.[0-9]{1,3})?|1(?:\.0{1,3})?|\.[0-9]{1,3})\z/
+    # @api private
+    LANGTAG_PATTERN = /\A(?:\*|[a-zA-Z]{1,8}(?:-[a-zA-Z0-9]{1,8})*)\z/
 
+    # @api private
+    # @return [Hash<String, BigDecimal>] Parsed language tags and their quality values
     attr_reader :languages_range
 
     # Initializes a new Parser instance by importing and processing the given Accept-Language header field.
     #
-    # @param [String] field The Accept-Language header field to parse.
+    # @param field [String] The Accept-Language header field to parse.
     def initialize(field)
       @languages_range = import(field)
     end
 
-    # Uses the Matcher class to find the best language match from the list of available languages.
+    # Finds the best matching language from available options based on user preferences.
+    # Considers quality values and language tag specificity (e.g., "en-US" vs "en").
     #
-    # @param [Array<String, Symbol>] available_langtags An array of language tags that are available for matching.
+    # @param available_langtags [Array<String, Symbol>] Languages supported by your application
+    # @return [String, Symbol, nil] Best matching language tag or nil if no match found
     #
-    # @example When Uyghur, Kazakh, Russian and English languages are available.
-    #   match(:ug, :kk, :ru, :en)
-    #
-    # @return [String, Symbol, nil] The language tag that best matches the parsed languages from the Accept-Language header, or nil if no match found.
+    # @example Match against specific language options
+    #   parser.match("en", "fr", "de") # => "en" if English is preferred
+    # @example Match with region-specific tags
+    #   parser.match("en-US", "en-GB", "fr") # => "en-GB" if British English is preferred
     def match(*available_langtags)
       Matcher.new(**languages_range).call(*available_langtags)
     end
 
     private
 
-    # Processes the Accept-Language header field to extract language tags and their respective quality values.
-    #
-    # @example
-    #   import('da, en-GB;q=0.8, en;q=0.7')
-    #   # => {"da"=>1.0, "en-GB"=>0.8, "en"=>0.7}
-    #
-    # @return [Hash<String, BigDecimal>] A hash where keys represent language tags and values are their respective quality values.
     def import(field)
       "#{field}".delete(SPACE).split(SEPARATOR).inject({}) do |hash, lang|
         tag, quality = lang.split(SUFFIX)
-        next hash if tag.nil?
+        next hash unless valid_tag?(tag)
 
-        quality = quality.nil? ? DEFAULT_QUALITY : BigDecimal(quality)
-        hash.merge(tag => quality)
+        quality = DEFAULT_QUALITY if quality.nil?
+        next hash unless valid_quality?(quality)
+
+        hash.merge(tag => BigDecimal(quality))
       end
     end
+
+    def valid_quality?(quality)
+      quality.match?(QVALUE_PATTERN)
+    end
+
+    def valid_tag?(tag)
+      return false if tag.nil?
+
+      tag.match?(LANGTAG_PATTERN)
+    end
   end
 end
 

data/lib/accept_language.rb

@@ -1,31 +1,30 @@
 # frozen_string_literal: true
 
-# This module provides a tiny library for parsing the Accept-Language header as specified in RFC 2616.
-# It transforms the Accept-Language header field into a language range, providing a flexible way to determine
-# user's language preferences and match them with the available languages in your application.
+# AcceptLanguage is a lightweight library for parsing Accept-Language HTTP headers
+# as defined in RFC 2616. It determines user language preferences and matches them
+# against your application's supported languages.
 #
-# @example
-#   AcceptLanguage.parse("da, en-GB;q=0.8, en;q=0.7")
-#   # => #<AcceptLanguage::Parser:0x00007 @languages_range={"da"=>1.0, "en-GB"=>0.8, "en"=>0.7}>
+# @example Basic usage
+#   AcceptLanguage.parse("da, en-GB;q=0.8, en;q=0.7").match(:en, :da)
+#   # => :da
+#
+# @example With regional variants
+#   AcceptLanguage.parse("fr-CH, fr;q=0.9").match(:fr, :"fr-CH")
+#   # => :"fr-CH"
 #
 # @see https://tools.ietf.org/html/rfc2616#section-14.4
 module AcceptLanguage
-  # Parses an Accept-Language header field value into a Parser object, which can then be used to match
-  # user's preferred languages against the languages your application supports.
-  # This method accepts a string argument in the format as described in RFC 2616 Section 14.4, and returns
-  # a Parser object which responds to the #match method.
+  # Parses an Accept-Language header field value.
   #
-  # @param field [String] the Accept-Language header field value.
+  # @param field [String] The Accept-Language header field value
+  # @return [Parser] A parser object that responds to {Parser#match}
   #
   # @example
-  #   AcceptLanguage.parse("da, en-GB;q=0.8, en;q=0.7")
-  #   # => #<AcceptLanguage::Parser:0x00007 @languages_range={"da"=>1.0, "en-GB"=>0.8, "en"=>0.7}>
-  #
-  # @return [Parser] a Parser object that responds to #match method.
+  #   parser = AcceptLanguage.parse("en-GB, en;q=0.9")
+  #   parser.match(:en, :"en-GB") # => :"en-GB"
   def self.parse(field)
     Parser.new(field)
   end
 end
 
-# Load the Parser class
 require_relative File.join("accept_language", "parser")

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: accept_language
 version: !ruby/object:Gem::Version
-  version: 2.0.7
+  version: 2.1.0
 platform: ruby
 authors:
 - Cyril Kato
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-06-21 00:00:00.000000000 Z
-dependencies: []
+date: 2026-01-15 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bigdecimal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Parses the Accept-Language header from an HTTP request and produces a
   hash of languages and qualities.
 email: contact@cyril.email
@@ -27,7 +41,7 @@ licenses:
 - MIT
 metadata:
   rubygems_mfa_required: 'true'
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -35,15 +49,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.2.2
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.22
-signing_key: 
+rubygems_version: 3.4.19
+signing_key:
 specification_version: 4
 summary: "Parser for Accept-Language request HTTP header \U0001F310"
 test_files: []