accept_language 2.0.8 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0afa534a141f111edb4f47449bccb2b44795abd11512319bee75909f672133ab
-  data.tar.gz: e90f24a3a8104eb8fff13ee15ce7660705e31565769c95e62d4fb4577ff1c816
+  metadata.gz: 7273e9328183e3dee11fd68a6598d82c67efbb8bab156d6d9b3424d9ed45dcca
+  data.tar.gz: ec31e8a4ac07501f1c481e65452f362be2d7669d93eea626977f25c3aca88dc2
 SHA512:
-  metadata.gz: 6d098319c113b5ed61b7b57a57ce78cde8b799d9256240dc076de8626d5021ad4840f96b23b94bcba1d64dc7930e66514da17d4d55d8107c417a9c102a99925b
-  data.tar.gz: c4695ea31539c0c94713b569e424fd2901a85a4ac67a448ef1c9cd200333fdaa1ab4bfe7429d1b7155fb2c4f4d2ffcf4218d2fee2060f9ffb6b629accc50a56e
+  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,148 +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?
+## Features
 
-There are a myriad of tools out there, so why should you consider Accept Language for your next project? Here's why:
-
-- **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:
-
-```sh
-bundle install
-```
-
-Or install it yourself as:
-
-```sh
-gem install accept_language
-```
-
 ## Usage
 
-The `Accept Language` library helps web applications serve content in the user's preferred language by parsing the `Accept-Language` HTTP header. This header indicates the user's language preferences and their priority order.
-
-### Basic Syntax
-
-The library has two main methods:
-
-- `AcceptLanguage.parse(header)`: Parses the Accept-Language header
-- `match(*available_languages)`: Matches against the languages your application supports
-
 ```ruby
-AcceptLanguage.parse("fr-CH, fr;q=0.9").match(:fr, :"fr-CH") # => :"fr-CH"
+AcceptLanguage.parse("en-GB, en;q=0.9").match(:en, :"en-GB")
+# => :"en-GB"
 ```
 
-### Understanding Language Preferences
+### Quality values
 
-#### Simple Language Matching
+Quality values (q-values) indicate preference order from 0 to 1:
 
 ```ruby
-# Header: "da" (Danish is the preferred language)
-# Available: :en and :da
-AcceptLanguage.parse("da").match(:en, :da) # => :da
-
-# No match available - returns nil
-AcceptLanguage.parse("da").match(:fr, :en) # => nil
-```
+parser = AcceptLanguage.parse("da, en-GB;q=0.8, en;q=0.7")
 
-#### Quality Values (q-values)
-
-Q-values range from 0 to 1 and indicate preference order:
-
-```ruby
-# Header: "da, en-GB;q=0.8, en;q=0.7"
-# Means:
-#   - Danish (da): q=1.0 (highest priority)
-#   - British English (en-GB): q=0.8 (second choice)
-#   - Generic English (en): q=0.7 (third choice)
-AcceptLanguage.parse("da, en-GB;q=0.8, en;q=0.7").match(:en, :da) # => :da
-AcceptLanguage.parse("da, en-GB;q=0.8, en;q=0.7").match(:en, :"en-GB") # => :"en-GB"
+parser.match(:en, :da)      # => :da
+parser.match(:en, :"en-GB") # => :"en-GB"
+parser.match(:fr)           # => nil
 ```
 
-#### Language Variants
+### Language variants
 
-The library handles specific language variants (regional or script variations):
+A generic language tag matches its regional variants, but not the reverse:
 
 ```ruby
-# Specific variants must match exactly
-AcceptLanguage.parse("fr-CH").match(:fr) # => nil (Swiss French ≠ Generic French)
-
-# But generic variants can match specific ones
-AcceptLanguage.parse("fr").match(:"fr-CH") # => :"fr-CH"
-
-# Script variants are also supported
-AcceptLanguage.parse("uz-Latn-UZ").match("uz-Latn-UZ") # => "uz-Latn-UZ"
+AcceptLanguage.parse("fr").match(:"fr-CH")    # => :"fr-CH"
+AcceptLanguage.parse("fr-CH").match(:fr)      # => nil
 ```
 
-#### Wildcards and Exclusions
-
-The `*` wildcard matches any language, and `q=0` excludes languages:
-
-```ruby
-# Accept any language but prefer German
-AcceptLanguage.parse("de-DE, *;q=0.5").match(:fr) # => :fr (matched by wildcard)
-
-# Accept any language EXCEPT English
-AcceptLanguage.parse("*, en;q=0").match(:en) # => nil (explicitly excluded)
-AcceptLanguage.parse("*, en;q=0").match(:fr) # => :fr (matched by wildcard)
-```
+### Wildcards and exclusions
 
-#### Complex Example
+The wildcard `*` matches any language. A q-value of 0 explicitly excludes a language:
 
 ```ruby
-# Header: "de-LU, fr;q=0.9, en;q=0.7, *;q=0.5"
-# Means:
-#   - Luxembourg German: q=1.0 (highest priority)
-#   - French: q=0.9 (second choice)
-#   - English: q=0.7 (third choice)
-#   - Any other language: q=0.5 (lowest priority)
-header = "de-LU, fr;q=0.9, en;q=0.7, *;q=0.5"
-parser = AcceptLanguage.parse(header)
-
-parser.match(:de, :"de-LU") # => :"de-LU" (exact match)
-parser.match(:fr, :en)      # => :fr (higher q-value)
-parser.match(:es, :it)      # => :es (matched by wildcard)
+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
 ```
 
-### Case Sensitivity
+### Case sensitivity
 
-The matching is case-insensitive but preserves the case of the returned value:
+Matching is case-insensitive but preserves the case of the available language tag:
 
 ```ruby
 AcceptLanguage.parse("en-GB").match("en-gb") # => "en-gb"
 AcceptLanguage.parse("en-gb").match("en-GB") # => "en-GB"
 ```
 
-### Rails integration example
+## Rails integration
 
 ```ruby
 # app/controllers/application_controller.rb
@@ -171,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

@@ -5,19 +5,16 @@ module AcceptLanguage
   # 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,15 +31,7 @@ module AcceptLanguage
       @preferred_langtags = langtags.compact.reverse
     end
 
-    # Finds the optimal language match by comparing user preferences against available languages.
-    # Handles priorities based on:
-    # 1. Explicit quality values (q-values)
-    # 2. Language tag specificity (exact matches preferred over partial matches)
-    # 3. Order of preference in the original Accept-Language header
-    #
-    # @param [Array<String, Symbol>] available_langtags Languages supported by your application
-    # @return [String, Symbol, nil] Best matching language or nil if no acceptable match found
-    # @raise [ArgumentError] If any language tag is nil
+    # @api private
     def call(*available_langtags)
       raise ::ArgumentError, "Language tags cannot be nil" if available_langtags.any?(&:nil?)
 
@@ -72,13 +61,17 @@ module AcceptLanguage
     end
 
     def find_matching_tag(preferred_tag, available_langtags)
-      available_langtags.find { |tag| tag.match?(/\A#{preferred_tag}/i) }
+      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? { |tag| available_langtag.match?(/\A#{tag}/i) }
+        langtags.none? do |tag|
+          pattern = /\A#{::Regexp.escape(tag)}/i
+          available_langtag.match?(pattern)
+        end
       end
     end
 
@@ -91,7 +84,10 @@ module AcceptLanguage
     end
 
     def unacceptable?(langtag)
-      excluded_langtags.any? { |excluded_tag| langtag.match?(/\A#{excluded_tag}/i) }
+      excluded_langtags.any? do |excluded_tag|
+        pattern = /\A#{::Regexp.escape(excluded_tag)}/i
+        langtag.match?(pattern)
+      end
     end
 
     def wildcard?(value)

data/lib/accept_language/parser.rb

@@ -8,27 +8,31 @@ module AcceptLanguage
   # 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
+    # @api private
     DEFAULT_QUALITY = "1"
+    # @api private
     SEPARATOR = ","
+    # @api private
     SPACE = " "
+    # @api private
     SUFFIX = ";q="
-
-    # Validates q-values according to RFC 2616:
-    # - Must be between 0 and 1
-    # - Can have up to 3 decimal places
-    # - Allows both forms: .8 and 0.8
+    # @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
@@ -36,8 +40,9 @@ module AcceptLanguage
     # 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 Languages supported by your application
+    # @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 Match against specific language options
     #   parser.match("en", "fr", "de") # => "en" if English is preferred
     # @example Match with region-specific tags
@@ -48,13 +53,6 @@ module AcceptLanguage
 
     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)
@@ -72,7 +70,9 @@ module AcceptLanguage
     end
 
     def valid_tag?(tag)
-      !tag.nil? && !tag.empty?
+      return false if tag.nil?
+
+      tag.match?(LANGTAG_PATTERN)
     end
   end
 end

data/lib/accept_language.rb

@@ -1,44 +1,30 @@
 # frozen_string_literal: true
 
-# AcceptLanguage is a lightweight library that parses Accept-Language HTTP headers (RFC 2616) to determine
-# user language preferences. It converts raw header values into a structured format for matching against
-# your application's supported languages.
+# 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 Integration with Rails
-#   class ApplicationController < ActionController::Base
-#     before_action :set_locale
-#
-#     private
-#
-#     def set_locale
-#       header = request.env["HTTP_ACCEPT_LANGUAGE"]
-#       locale = AcceptLanguage.parse(header).match(*I18n.available_locales)
-#       I18n.locale = locale || I18n.default_locale
-#     end
-#   end
+# @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.8
+  version: 2.1.0
 platform: ruby
 authors:
 - Cyril Kato
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-12-15 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
@@ -35,14 +49,14 @@ 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.10
+rubygems_version: 3.4.19
 signing_key:
 specification_version: 4
 summary: "Parser for Accept-Language request HTTP header \U0001F310"