http-accept 1.0.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 02b776cfc42af7c6a5cf36d154a76372a1190088
-  data.tar.gz: 17e40217b15891a3ab68a9a8262687104a826ff0
+  metadata.gz: 409b179f21a3c570060f5d16802137a640c997e0
+  data.tar.gz: 93108cf6d8302906d14f1e0e979e990721e733a7
 SHA512:
-  metadata.gz: 7abab3f7a1543dccffb606f0ca0136eeaebacb132d569abf614ba94469a9327c943972bb75860484b7a1d528476326760e5b4ea024ee18137972b99901c47bdb
-  data.tar.gz: 46609f96228bb2b0608b086fcf6bfdcff40b3cb0b2074cbbd8383ad01e88dc229982c2a89bfd6a108e8a035ab0dbab13479c684900ecc002475ffe3f269cc55c
+  metadata.gz: 2c154231b09a91b992b3f6bb1fabb092782f19bcc11fcaed933adf9682632a9e28a31e438447dc5284635c346e25b0a97b8f74a7ad771ffa64addf305bf5d098
+  data.tar.gz: aeab4528e8ebf4ad756a95059ceaaeea3ad357d350a80b2f147b9c8f20ebb3c3500a8c6e9e94bb74e9774823ae39e36abcd3317d7c9e95c0816799d302b788f6

data/README.md

@@ -28,6 +28,8 @@ Here are some examples of how to parse various headers.
 
 ### Parsing Accept: headers
 
+You can parse the incoming `Accept:` header:
+
 	media_types = HTTP::Accept::MediaTypes.parse("text/html;q=0.5, application/json; version=1")
 
 	expect(media_types[0].mime_type).to be == "application/json"
@@ -35,14 +37,51 @@ Here are some examples of how to parse various headers.
 	expect(media_types[1].mime_type).to be == "text/html"
 	expect(media_types[1].parameters).to be == {'q' => '0.5'}
 
+Normally, you'd want to match the media types against some set of available mime types:
+
+	module ToJSON
+		def content_type
+			"application/json"
+		end
+		
+		def convert(object, options)
+			object.to_json
+		end
+	end
+	
+	module ToXML
+		# Are you kidding?
+	end
+	
+	map = HTTP::Accept::MediaTypes::Map.new
+	map << ToJSON
+	map << ToXML
+	
+	object, media_range = map.for(media_types)
+	content = object.convert(model, media_range.parameters)
+	response = [200, {'Content-Type' => object.content_type}, [content]]
+
 ### Parsing Accept-Language: headers
 
+You can parse the incoming `Accept-Language:` header:
+
 	languages = HTTP::Accept::Language.parse("da, en-gb;q=0.8, en;q=0.7")
 
 	expect(languages[0].locale).to be == "da"
 	expect(languages[1].locale).to be == "en-gb"
 	expect(languages[2].locale).to be == "en"`
 
+Normally, you'd want to match the languages against some set of available localizations:
+
+	available_localizations = HTTP::Accept::Languages::Locales.new(["en-nz", "en-us"])
+	
+	# Given the languages that the user wants, and the localizations available, compute the set of desired localizations.
+	desired_localizations = available_localizations & languages
+	
+The `desired_localizations` in the example above is a subset of `available_localizations`.
+
+`HTTP::Accept::Languages::Locales` provides an efficient data-structure for matching the Accept-Languages header to set of available localizations according to https://tools.ietf.org/html/rfc7231#section-5.3.5 and https://tools.ietf.org/html/rfc4647#section-2.3
+
 ## Contributing
 
 1. Fork it

data/lib/http/accept/languages.rb

@@ -25,7 +25,7 @@ require_relative 'sort'
 
 module HTTP
 	module Accept
-		class Languages
+		module Languages
 			LOCALE = /\*|[A-Z]{1,8}(-[A-Z]{1,8})*/i
 			
 			# https://www.w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.9
@@ -33,6 +33,48 @@ module HTTP
 			
 			LANGUAGE_RANGE = /(?<locale>#{LOCALE})(;q=(?<q>#{QVALUE}))?/
 			
+			# Provides an efficient data-structure for matching the Accept-Languages header to set of available locales according to https://tools.ietf.org/html/rfc7231#section-5.3.5 and https://tools.ietf.org/html/rfc4647#section-2.3
+			class Locales < Array
+				def self.expand(locale, into)
+					parts = locale.split('-')
+					
+					while parts.size > 0
+						key = parts.join('-')
+						
+						into[key] ||= locale
+						
+						parts.pop
+					end
+				end
+				
+				def initialize(names)
+					super(names)
+					
+					@patterns = {}
+					
+					self.each{|name| self.class.expand(name, @patterns)}
+					
+					self.freeze
+				end
+				
+				def freeze
+					@patterns.freeze
+					
+					super
+				end
+				
+				attr :patterns
+				
+				# Returns the intersection of others retaining order.
+				def & languages
+					languages.collect{|language_range| @patterns[language_range.locale]}.compact
+				end
+				
+				def include? locale_name
+					@patterns.include? locale_name
+				end
+			end
+			
 			class LanguageRange < Struct.new(:locale, :q)
 				def quality_factor
 					(q || 1.0).to_f
@@ -50,11 +92,6 @@ module HTTP
 					
 					raise ParseError.new("Could not parse entire string!") unless scanner.eos?
 				end
-				
-				# If the user ask for 'en', this satisfies any language that begins with 'en-'
-				def prefix_of? other
-					other.start_with(locale)
-				end
 			end
 			
 			def self.parse(text)
@@ -67,4 +104,3 @@ module HTTP
 		end
 	end
 end
-

data/lib/http/accept/media_types.rb

@@ -26,18 +26,73 @@ require_relative 'sort'
 
 module HTTP
 	module Accept
-		class MediaTypes
+		module MediaTypes
 			# According to https://tools.ietf.org/html/rfc7231#section-5.3.2
 			MIME_TYPE = /(#{TOKEN})\/(#{TOKEN})/
 			PARAMETER = /\s*;\s*(?<key>#{TOKEN})=((?<value>#{TOKEN})|(?<quoted_value>#{QUOTED_STRING}))/
 			
+			# Map a set of mime types to objects.
+			class Map
+				WILDCARD = '*'.freeze
+				
+				def initialize
+					@media_types = Hash.new{|h,k| h[k] = {}}
+					
+					# Primarily for implementing #freeze efficiently.
+					@all = []
+				end
+				
+				def freeze
+					@media_types.freeze
+					@media_types.each{|key,value| value.freeze}
+					
+					@all.freeze
+					@all.each(&:freeze)
+					
+					super
+				end
+				
+				# Given a list of content types (e.g. from browser_preferred_content_types), return the best converter.
+				def for(media_types)
+					media_types.each do |media_range|
+						type, subtype = media_range.split
+						
+						if object = @media_types[type][subtype]
+							return object, media_range
+						end
+					end
+					
+					return nil
+				end
+				
+				# Add a converter to the collection. A converter can be anything that responds to #content_type.
+				def << object
+					type, subtype = object.content_type.split('/')
+					
+					if @media_types.empty?
+						@media_types[WILDCARD][WILDCARD] = object
+					end
+					
+					if @media_types[type].empty?
+						@media_types[type][WILDCARD] = object
+					end
+					
+					@media_types[type][subtype] = object
+					@all << object
+				end
+			end
+			
 			class MediaRange < Struct.new(:mime_type, :parameters)
 				def quality_factor
 					parameters.fetch('q', 1.0).to_f
 				end
 				
-				def self.parse(scanner)
-					return to_enum(:parse, scanner) unless block_given?
+				def split
+					@type, @subtype = mime_type.split('/')
+				end
+				
+				def self.parse(scanner, normalize_whitespace = true)
+					return to_enum(:parse, scanner, normalize_whitespace) unless block_given?
 					
 					while mime_type = scanner.scan(MIME_TYPE)
 						parameters = {}
@@ -48,7 +103,7 @@ module HTTP
 							if value = scanner[:value]
 								parameters[key] = value
 							elsif quoted_value = scanner[:quoted_value]
-								parameters[key] = QuotedString.new(quoted_value)
+								parameters[key] = QuotedString.unquote(quoted_value, normalize_whitespace)
 							else
 								raise ParseError.new("Could not parse parameter!")
 							end
@@ -64,10 +119,10 @@ module HTTP
 				end
 			end
 			
-			def self.parse(text)
+			def self.parse(text, normalize_whitespace = true)
 				scanner = StringScanner.new(text)
 				
-				media_types = MediaRange.parse(scanner)
+				media_types = MediaRange.parse(scanner, normalize_whitespace)
 				
 				return Sort.by_quality_factor(media_types)
 			end

data/lib/http/accept/quoted_string.rb

@@ -24,30 +24,21 @@ module HTTP
 		TOKEN = /[!#$%&'*+\-.^_`|~0-9A-Z]+/i
 		QUOTED_STRING = /"(?:.(?!(?<!\\)"))*.?"/
 		
-		class QuotedString
-			def initialize(value)
-				@value = value
-			end
-			
-			def unquote(normalize_whitespace = false)
-				value = @value[1...-1]
+		module QuotedString
+			# Unquote a "quoted-string" value according to https://tools.ietf.org/html/rfc7230#section-3.2.6
+			# It should already match the QUOTED_STRING pattern above by the parser.
+			def self.unquote(value, normalize_whitespace = true)
+				value = value[1...-1]
 				
 				value.gsub!(/\\(.)/, '\1') 
 				
 				if normalize_whitespace
-					value.gsub!(/[\r\n]\s+/, ' ')
+					# LWS = [CRLF] 1*( SP | HT )
+					value.gsub!(/[\r\n]+\s+/, ' ')
 				end
 				
 				return value
 			end
-			
-			def to_str
-				unquote(true)
-			end
-			
-			def to_s
-				to_str
-			end
 		end
 	end
 end

data/lib/http/accept/version.rb

@@ -20,6 +20,6 @@
 
 module HTTP
 	module Accept
-		VERSION = "1.0.1"
+		VERSION = "1.1.0"
 	end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: http-accept
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.1.0
 platform: ruby
 authors:
 - Samuel Williams
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-02-03 00:00:00.000000000 Z
+date: 2016-02-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler