protocol-media 0.0.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f2b4e5ba22b3b99614f42ca660be8745ea4d8b16a83dc8b97728461a5b4601d6
-  data.tar.gz: d9eea7f70012140ce42dee2501b48281b17476a5207e017ecd3a44891fac74fa
+  metadata.gz: 41cc93afe36dc9af35b5ca77721b8859543b270627a3cb9f7f6cc2df2334d83e
+  data.tar.gz: 306bf200c34635b7eba643945121d6150054759ffa7ffa9ce5f08bf0668aa3b0
 SHA512:
-  metadata.gz: bb8adf6b0a4aa0df12f48cac05123671dc00bbdb53ee46825cd8e26676020fb4685302c99e4c1967e68ca6b2ab36d706b7f0b884a3e48c6d80d124ed48e43810
-  data.tar.gz: '0961e8287d2d249e37ffdf576fe17d27da6727070cacaa4694b8c84b6c0ef3f8b98a4f88b8cfca5f93758b8058b1522cc4cc728653d085985d5355fad9106df1'
+  metadata.gz: 7ab4060ead68e7b62f6486e298155e23060019bf7eb4bc9d2524efcb5cfe65e0a018945d46305730359b0c7e6bca158b44632ce5b7ca06ffd6c3c0bc2b8d327c
+  data.tar.gz: 84ccb4d5c42a6431cdc7da7d5ba6d1c776581bb561f0bde140d002c7cc5549f13304023c5d55bf4385c3e1de5a17be86c9d0aefcd2f708969aef3476772faa39

data/lib/protocol/media/map.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require_relative "type"
+
+module Protocol
+	module Media
+		# An immutable map from concrete media types to objects for range-based lookup.
+		class Map
+			# Incrementally constructs an immutable media map.
+			class Builder
+				# Initialize an empty media map builder.
+				def initialize
+					@index = {}
+				end
+				
+				# Associate a concrete media type with an object.
+				#
+				# @parameter media_type [String | Object] The concrete media type or compatible object.
+				# @parameter object [Object] The object associated with the media type.
+				def []=(media_type, object)
+					media_type = Type.for(media_type)
+					
+					# Preserve the first registration as the default for wildcard queries:
+					@index["*/*"] ||= object
+					@index["#{media_type.type}/*"] ||= object
+					@index[media_type.name] = object
+				end
+				
+				# Compile the current registrations into an immutable map.
+				# @returns [Map] The immutable media map.
+				def build
+					return Map.new(@index).freeze
+				end
+			end
+			
+			# Construct an immutable map using a builder.
+			# @yields {|builder| ...} The mutable builder.
+			# @returns [Map] The immutable media map.
+			def self.build
+				builder = Builder.new
+				
+				if block_given?
+					yield builder
+				end
+				
+				return builder.build
+			end
+			
+			# Convert keyed entries into a media map.
+			#
+			# Existing maps are returned unchanged, including their frozen state.
+			#
+			# @parameter entries [Map | Enumerable] The existing map or keyed media range entries.
+			# @returns [Map] The existing map or a newly constructed immutable map.
+			def self.for(entries)
+				return entries if entries.instance_of?(self)
+				
+				return build do |builder|
+					entries.each do |media_type, object|
+						builder[media_type] = object
+					end
+				end
+			end
+			
+			# Initialize a new media map with a given index.
+			#
+			# The index is retained without copying or freezing it.
+			#
+			# @parameter index [Hash] The keyed media range entries.
+			def initialize(index)
+				@index = index
+			end
+			
+			# Freeze the media map and its index.
+			# @returns [self]
+			def freeze
+				return self if frozen?
+				
+				@index.freeze
+				
+				return super
+			end
+			
+			# Find the object matching a media type or range.
+			#
+			# @parameter media_range [String | Object] The media type or compatible range.
+			# @returns [Object | nil] The matching object, if one exists.
+			def [](media_range)
+				return lookup(Range.for(media_range))
+			end
+			
+			# Find the first object matching an ordered sequence of media ranges.
+			#
+			# @parameter media_ranges [Enumerable] The media types or ranges in preference order.
+			# @returns [Array(Object, Range | String) | nil] The matching object and original range, if one exists.
+			def for(media_ranges)
+				media_ranges.each do |media_range|
+					if object = lookup(Range.for(media_range))
+						return [object, media_range]
+					end
+				end
+				
+				return nil
+			end
+			
+			private
+			
+			def lookup(media_range)
+				media_range = Range.build(media_range.type, media_range.subtype)
+				return @index[media_range.name]
+			end
+		end
+	end
+end

data/lib/protocol/media/range.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require_relative "version"
+
+require "strscan"
+
+module Protocol
+	module Media
+		# A media range and its parameters.
+		class Range
+			TOKEN = /[!#$%&'*+\-.^_`|~0-9A-Z]+/i
+			QUOTED_STRING = /"(?:.(?!(?<!\\)"))*.?"/
+			MEDIA_TYPE = /(?<type>#{TOKEN})\/(?<subtype>#{TOKEN})/
+			PARAMETER = /\s*;\s*(?<key>#{TOKEN})=((?<value>#{TOKEN})|(?<quoted_value>#{QUOTED_STRING}))/
+			
+			# Build a normalized media range.
+			#
+			# @parameter type [String] The top-level type.
+			# @parameter subtype [String] The subtype.
+			# @parameter parameters [Hash] The media range parameters.
+			# @returns [Range] The normalized media range.
+			def self.build(type, subtype = "*", parameters = {})
+				type = type.downcase
+				subtype = subtype.downcase
+				
+				# A wildcard type requires a wildcard subtype:
+				if type == "*"
+					if subtype != "*"
+						raise ArgumentError, "Invalid wildcards in media range: #{type}/#{subtype}"
+					end
+				end
+				
+				return new(type, subtype, parameters)
+			end
+			
+			# Parse strings into media ranges while preserving compatible objects.
+			#
+			# @parameter value [String | Object] A media range string or compatible object.
+			# @returns [Range | Object] The parsed range or original object.
+			def self.for(value)
+				if value.is_a?(String)
+					parse(value)
+				else
+					value
+				end
+			end
+			
+			# Parse a media range.
+			#
+			# @parameter text [String] The media range, including any parameters.
+			# @parameter normalize_whitespace [Boolean] Whether to normalize whitespace in quoted parameter values.
+			# @returns [Range] The parsed media range.
+			def self.parse(text, normalize_whitespace = true)
+				scanner = StringScanner.new(text)
+				
+				unless scanner.scan(MEDIA_TYPE)
+					raise ArgumentError, "Invalid media range: #{text.inspect}"
+				end
+				
+				type = scanner[:type]
+				subtype = scanner[:subtype]
+				parameters = parse_parameters(scanner, normalize_whitespace)
+				
+				unless scanner.eos?
+					raise ArgumentError, "Invalid media range: #{text.inspect}"
+				end
+				
+				return build(type, subtype, parameters)
+			end
+			
+			# Parse media type parameters from the scanner.
+			#
+			# @parameter scanner [StringScanner] The scanner positioned after the type and subtype.
+			# @parameter normalize_whitespace [Boolean] Whether to normalize whitespace in quoted values.
+			# @returns [Hash] The parsed parameters.
+			def self.parse_parameters(scanner, normalize_whitespace = true)
+				parameters = {}
+				
+				while scanner.scan(PARAMETER)
+					key = scanner[:key]
+					
+					if value = scanner[:value]
+						parameters[key] = value
+					elsif quoted_value = scanner[:quoted_value]
+						parameters[key] = unquote(quoted_value, normalize_whitespace)
+					end
+				end
+				
+				parameters
+			end
+			
+			# @attribute [String] The top-level type, e.g. `text` or `*`.
+			attr_reader :type
+			
+			# @attribute [String] The subtype, e.g. `plain` or `*`.
+			attr_reader :subtype
+			
+			# @attribute [Hash] The media range parameters.
+			attr_reader :parameters
+			
+			# @parameter type [String] The top-level type.
+			# @parameter subtype [String] The subtype.
+			# @parameter parameters [Hash] The media range parameters.
+			def initialize(type, subtype = "*", parameters = {})
+				@type = type
+				@subtype = subtype
+				@parameters = parameters
+			end
+			
+			# The complete media range name.
+			#
+			# @returns [String]
+			def name
+				"#{@type}/#{@subtype}"
+			end
+			
+			alias mime_type name
+			
+			# Convert the media range and parameters to a string.
+			#
+			# @returns [String] The serialized media range.
+			def to_s
+				name + @parameters.collect do |key, value|
+					"; #{key}=#{quote(value.to_s)}"
+				end.join
+			end
+			
+			alias to_str to_s
+			
+			# Freeze the media range and its direct values.
+			# @returns [self]
+			def freeze
+				return self if frozen?
+				
+				@type.freeze
+				@subtype.freeze
+				@parameters.freeze
+				
+				return super
+			end
+			
+			# Whether this range matches the given media type or range.
+			#
+			# @parameter media_range [Range] The media type or range to match.
+			# @returns [Boolean] Whether the type and subtype are compatible.
+			def match?(media_range)
+				# Both type components must be compatible:
+				unless component_match?(@type, media_range.type)
+					return false
+				end
+				
+				# Both subtype components must be compatible:
+				unless component_match?(@subtype, media_range.subtype)
+					return false
+				end
+				
+				return true
+			end
+			
+			alias === match?
+			
+			# Compare this media range with another media range.
+			#
+			# @parameter other [Object] The object to compare.
+			# @returns [Boolean] Whether the values are equal.
+			def eql?(other)
+				other.instance_of?(self.class) && @type.eql?(other.type) && @subtype.eql?(other.subtype) && @parameters.eql?(other.parameters)
+			end
+			
+			alias == eql?
+			
+			# Generate a hash key consistent with {#eql?}.
+			#
+			# @returns [Integer] The hash value.
+			def hash
+				[self.class, @type, @subtype, @parameters].hash
+			end
+			
+			private
+			
+			def component_match?(component, other_component)
+				# A wildcard on either side matches any component:
+				if component == "*"
+					return true
+				end
+				
+				if other_component == "*"
+					return true
+				end
+				
+				return component == other_component
+			end
+			
+			def self.unquote(value, normalize_whitespace)
+				value = value[1...-1]
+				value.gsub!(/\\(.)/, '\\1')
+				value.gsub!(/[\r\n]+\s+/, " ") if normalize_whitespace
+				value
+			end
+			
+			def quote(value)
+				if value.match?(/\A#{TOKEN}\z/)
+					value
+				else
+					"\"#{value.gsub(/["\\]/, "\\\\\\0")}\""
+				end
+			end
+		end
+	end
+end

data/lib/protocol/media/set.rb

@@ -0,0 +1,247 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require_relative "range"
+
+require "set"
+
+module Protocol
+	module Media
+		# An immutable set of compatible media ranges.
+		class Set
+			include Enumerable
+			
+			# An immutable set which matches any media range.
+			class Any
+				include Enumerable
+				
+				RANGE = Range.new("*", "*").freeze
+				private_constant :RANGE
+				
+				# Whether the set contains a compatible media type or range.
+				# @parameter media_range [String | Object] The media type or range to validate.
+				# @returns [Boolean]
+				def include?(media_range)
+					media_range = Range.for(media_range)
+					
+					Range.build(media_range.type, media_range.subtype)
+					
+					return true
+				end
+				
+				alias === include?
+				alias match? include?
+				
+				# Enumerate the universal media range.
+				# @yields {|media_range| ...} The universal media range.
+				# @returns [Enumerator | self]
+				def each
+					return to_enum unless block_given?
+					
+					yield RANGE
+					
+					return self
+				end
+				
+				# The number of membership ranges.
+				# @returns [Integer]
+				def size
+					return 1
+				end
+				
+				# Whether there are no membership ranges.
+				# @returns [Boolean]
+				def empty?
+					return false
+				end
+			end
+			
+			ANY = Any.new.freeze
+			
+			private_constant :Any, :ANY
+			
+			# Incrementally constructs an immutable media set.
+			class Builder
+				# Initialize an empty media set builder.
+				def initialize
+					@types = {}
+				end
+				
+				# Add a media range to the set under construction.
+				# @parameter media_range [String | Object] The media range or compatible object.
+				# @returns [self]
+				def add(media_range)
+					if @types.instance_of?(Any)
+						return self
+					end
+					
+					media_range = Range.for(media_range)
+					media_range = Range.build(media_range.type, media_range.subtype)
+					type = media_range.type.freeze
+					subtype = media_range.subtype.freeze
+					
+					if type == "*"
+						@types = ANY
+					elsif subtype == "*"
+						@types[type] = ANY
+					elsif subtypes = @types[type]
+						unless subtypes.instance_of?(Any)
+							subtypes.add(subtype)
+						end
+					else
+						@types[type] = ::Set.new([subtype])
+					end
+					
+					return self
+				end
+				
+				alias << add
+				
+				# Compile the current ranges into an immutable set.
+				# @returns [Set] The immutable media set.
+				def build
+					if @types.instance_of?(Any)
+						return @types
+					end
+					
+					return Set.new(@types).freeze
+				end
+			end
+			
+			# Construct an immutable set using a builder.
+			# @yields {|builder| ...} The mutable builder.
+			# @returns [Set] The immutable media set.
+			def self.build
+				builder = Builder.new
+				
+				if block_given?
+					yield builder
+				end
+				
+				return builder.build
+			end
+			
+			# Convert a sequence of ranges into a media set.
+			#
+			# Existing sets are returned unchanged, including their frozen state.
+			#
+			# @parameter media_ranges [Set | Enumerable] The existing set or media ranges.
+			# @returns [Set] The existing set or a newly constructed immutable set.
+			def self.for(media_ranges)
+				# Preserve an existing media set:
+				if media_ranges.instance_of?(self)
+					return media_ranges
+				end
+				
+				# Preserve the universal media set:
+				if media_ranges.instance_of?(Any)
+					return media_ranges
+				end
+				
+				return build do |builder|
+					media_ranges.each do |media_range|
+						builder << media_range
+					end
+				end
+			end
+			
+			# Initialize a new media set with the given type index.
+			#
+			# The index is retained without copying or freezing it.
+			#
+			# @parameter types [Hash] The indexed media ranges.
+			def initialize(types)
+				@types = types
+			end
+			
+			# Freeze the media set and its index.
+			# @returns [self]
+			def freeze
+				return self if frozen?
+				
+				@types.each_value(&:freeze)
+				@types.freeze
+				
+				return super
+			end
+			
+			# Whether the set contains a compatible media type or range.
+			# @parameter media_range [String | Object] The media type or range to match.
+			# @returns [Boolean]
+			def include?(media_range)
+				media_range = normalize(media_range)
+				type = media_range.type
+				subtype = media_range.subtype
+				
+				# A wildcard type matches any non-empty set:
+				if type == "*"
+					return !@types.empty?
+				end
+				
+				subtypes = @types[type]
+				
+				# An unknown type cannot match:
+				unless subtypes
+					return false
+				end
+				
+				# A wildcard subtype matches any known type:
+				if subtype == "*"
+					return true
+				end
+				
+				# A type-wide wildcard matches every subtype:
+				if subtypes.instance_of?(Any)
+					return true
+				end
+				
+				return subtypes.include?(subtype)
+			end
+			
+			alias === include?
+			alias match? include?
+			
+			# Enumerate the canonical media ranges which define membership.
+			# @yields {|media_range| ...} Each canonical media range.
+			# @returns [Enumerator | self]
+			def each
+				return to_enum unless block_given?
+				
+				@types.each do |type, subtypes|
+					if subtypes.instance_of?(Any)
+						yield Range.new(type, "*")
+					else
+						subtypes.each do |subtype|
+							yield Range.new(type, subtype)
+						end
+					end
+				end
+				
+				return self
+			end
+			
+			# The number of canonical membership ranges.
+			# @returns [Integer]
+			def size
+				return @types.sum do |_type, subtypes|
+					subtypes.size
+				end
+			end
+			
+			# Whether the set contains no media ranges.
+			# @returns [Boolean]
+			def empty?
+				return @types.empty?
+			end
+			
+			private
+			
+			def normalize(media_range)
+				media_range = Range.for(media_range)
+				return Range.build(media_range.type, media_range.subtype)
+			end
+		end
+	end
+end

data/lib/protocol/media/type.rb

@@ -3,130 +3,42 @@
 # Released under the MIT License.
 # Copyright, 2026, by Samuel Williams.
 
-require_relative "version"
-
-require "strscan"
+require_relative "range"
 
 module Protocol
 	module Media
 		# A concrete media type and its parameters.
-		class Type
-			TOKEN = /[!#$%&'*+\-.^_`|~0-9A-Z]+/i
-			QUOTED_STRING = /"(?:.(?!(?<!\\)"))*.?"/
-			MEDIA_TYPE = /(?<type>#{TOKEN})\/(?<subtype>#{TOKEN})/
-			PARAMETER = /\s*;\s*(?<key>#{TOKEN})=((?<value>#{TOKEN})|(?<quoted_value>#{QUOTED_STRING}))/
-			
-			# Parse a concrete media type.
+		class Type < Range
+			# Parse strings and normalize compatible media type objects.
 			#
-			# @parameter text [String] The media type, including any parameters.
-			# @parameter normalize_whitespace [Boolean] Whether to normalize whitespace in quoted parameter values.
-			# @returns [Type] The parsed media type.
-			def self.parse(text, normalize_whitespace = true)
-				scanner = StringScanner.new(text)
-				
-				unless scanner.scan(MEDIA_TYPE)
-					raise ArgumentError, "Invalid media type: #{text.inspect}"
+			# @parameter value [String | Object] A media type string or compatible object.
+			# @returns [Type] The normalized concrete media type.
+			def self.for(value)
+				if value.is_a?(String)
+					return parse(value)
 				end
 				
-				type = scanner[:type]
-				subtype = scanner[:subtype]
-				parameters = parse_parameters(scanner, normalize_whitespace)
-				
-				unless scanner.eos?
-					raise ArgumentError, "Invalid media type: #{text.inspect}"
-				end
-				
-				new(type, subtype, parameters)
+				return build(value.type, value.subtype, value.parameters)
 			end
 			
-			# Parse media type parameters from the scanner.
+			# Build a normalized concrete media type.
 			#
-			# @parameter scanner [StringScanner] The scanner positioned after the type and subtype.
-			# @parameter normalize_whitespace [Boolean] Whether to normalize whitespace in quoted values.
-			# @returns [Hash] The parsed parameters.
-			def self.parse_parameters(scanner, normalize_whitespace = true)
-				parameters = {}
-				
-				while scanner.scan(PARAMETER)
-					key = scanner[:key]
-					
-					if value = scanner[:value]
-						parameters[key] = value
-					elsif quoted_value = scanner[:quoted_value]
-						parameters[key] = unquote(quoted_value, normalize_whitespace)
-					end
-				end
-				
-				parameters
-			end
-			
-			# @attribute [String] The top-level type, e.g. `text`.
-			attr_reader :type
-			
-			# @attribute [String] The subtype, e.g. `plain`.
-			attr_reader :subtype
-			
-			# @attribute [Hash] The media type parameters.
-			attr_reader :parameters
-			
 			# @parameter type [String] The top-level type.
 			# @parameter subtype [String] The subtype.
 			# @parameter parameters [Hash] The media type parameters.
-			def initialize(type, subtype, parameters = {})
-				if type.include?("*") || subtype.include?("*")
+			# @returns [Type] The normalized concrete media type.
+			def self.build(type, subtype, parameters = {})
+				# Concrete media types cannot use a wildcard type:
+				if type == "*"
 					raise ArgumentError, "Media types cannot contain wildcards: #{type}/#{subtype}"
 				end
 				
-				@type = type.downcase
-				@subtype = subtype.downcase
-				@parameters = parameters
-			end
-			
-			# The complete media type name.
-			#
-			# @returns [String]
-			def name
-				"#{@type}/#{@subtype}"
-			end
-			
-			alias mime_type name
-			
-			# Convert the media type and parameters to a string.
-			def to_s
-				name + @parameters.collect do |key, value|
-					"; #{key}=#{quote(value.to_s)}"
-				end.join
-			end
-			
-			alias to_str to_s
-			
-			# Compare this media type with another media type.
-			def ==(other)
-				other.is_a?(Type) && @type == other.type && @subtype == other.subtype && @parameters == other.parameters
-			end
-			
-			alias eql? ==
-			
-			# Generate a hash key consistent with {#eql?}.
-			def hash
-				[@type, @subtype, @parameters].hash
-			end
-			
-			private
-			
-			def self.unquote(value, normalize_whitespace)
-				value = value[1...-1]
-				value.gsub!(/\\(.)/, '\\1')
-				value.gsub!(/[\r\n]+\s+/, " ") if normalize_whitespace
-				value
-			end
-			
-			def quote(value)
-				if value.match?(/\A#{TOKEN}\z/)
-					value
-				else
-					"\"#{value.gsub(/["\\]/, "\\\\\\0")}\""
+				# Concrete media types cannot use a wildcard subtype:
+				if subtype == "*"
+					raise ArgumentError, "Media types cannot contain wildcards: #{type}/#{subtype}"
 				end
+				
+				return super
 			end
 		end
 	end

data/lib/protocol/media/version.rb

@@ -7,6 +7,6 @@
 module Protocol
 	# Models media types used by internet protocols and data formats.
 	module Media
-		VERSION = "0.0.1"
+		VERSION = "0.2.0"
 	end
 end

data/readme.md

@@ -2,13 +2,14 @@
 
 Provides a small representation of media types which can be shared by protocol implementations and registry backends.
 
-``` ruby
-require "protocol/media/type"
+## Usage
 
-type = Protocol::Media::Type.parse("text/plain; charset=utf-8")
-type.type # => "text"
-type.subtype # => "plain"
-type.parameters # => {"charset" => "utf-8"}
-```
+Please see the [project documentation](https://socketry.github.io/protocol-media/) for more details.
 
-Registry data and indexed lookup are provided separately by `protocol-media-data`.
+  - [Getting Started](https://socketry.github.io/protocol-media/guides/getting-started/index) - This guide explains how to represent, compare, and map media types with `protocol-media`.
+
+  - [Content Negotiation](https://socketry.github.io/protocol-media/guides/content-negotiation/index) - This guide explains how to combine `protocol-media` with an HTTP parser to select an application representation.
+
+## See Also
+
+  - [Protocol::Media::Registry](https://github.com/socketry/protocol-media-registry) provides registry data and indexed lookup by media type or file extension.

data/releases.md

@@ -0,0 +1,6 @@
+# Releases
+
+## Unreleased
+
+  - Introduce `Protocol::Media::Set` for compatible media range membership.
+  - Make `Protocol::Media::Map` and `Protocol::Media::Set` immutable, with builders for incremental construction and indexed lookups.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: protocol-media
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -13,10 +13,14 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- lib/protocol/media/map.rb
+- lib/protocol/media/range.rb
+- lib/protocol/media/set.rb
 - lib/protocol/media/type.rb
 - lib/protocol/media/version.rb
 - license.md
 - readme.md
+- releases.md
 homepage: https://github.com/socketry/protocol-media
 licenses:
 - MIT