protocol-media 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fcbab91700c5745af1309a24fa474c1c6b05a491bf995c657eb3dbcc739d1b8e
-  data.tar.gz: bf8a3fd2b20cdf4f54695333c33effdb509cf458cd1386d277294541bb1df2a7
+  metadata.gz: 41cc93afe36dc9af35b5ca77721b8859543b270627a3cb9f7f6cc2df2334d83e
+  data.tar.gz: 306bf200c34635b7eba643945121d6150054759ffa7ffa9ce5f08bf0668aa3b0
 SHA512:
-  metadata.gz: 92c4bac474b6aa04042b6152449c11dcab50d82dd1a0ca9c1dcb4d34878b7362c533b62bdc680ec9b33697748e8934c8598224102dc6b7a4989a55d76aef87d1
-  data.tar.gz: ce4ff11c22723981cdd2d09ae0c4cecdce7144c807bc73bf6cf0f72cf870d5cd3b7aa1fdbe5f6944e46f152c7d06a4d11f4bfd164e715edbdbec53dbc87fe2b8
+  metadata.gz: 7ab4060ead68e7b62f6486e298155e23060019bf7eb4bc9d2524efcb5cfe65e0a018945d46305730359b0c7e6bca158b44632ce5b7ca06ffd6c3c0bc2b8d327c
+  data.tar.gz: 84ccb4d5c42a6431cdc7da7d5ba6d1c776581bb561f0bde140d002c7cc5549f13304023c5d55bf4385c3e1de5a17be86c9d0aefcd2f708969aef3476772faa39

data/lib/protocol/media/map.rb

@@ -3,88 +3,114 @@
 # Released under the MIT License.
 # Copyright, 2026, by Samuel Williams.
 
-require_relative "range"
+require_relative "type"
 
 module Protocol
 	module Media
-		# Maps media types and ranges to objects using type/subtype compatibility.
+		# An immutable map from concrete media types to objects for range-based lookup.
 		class Map
-			# Initialize an empty media map.
-			def initialize
-				@entries = {}
+			# 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
 			
-			# Associate a media type or range with an object.
-			#
-			# @parameter range [String | Object] The media type or compatible range.
-			# @parameter object [Object] The object associated with the range.
-			def []=(range, object)
-				range = Range.for(range)
+			# 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
 				
-				@entries[name(range)] = [range, object]
+				return builder.build
 			end
 			
-			# Find the object matching a media type or range.
+			# Convert keyed entries into a media map.
 			#
-			# Exact type/subtype registrations take priority, followed by the first compatible registration.
+			# Existing maps are returned unchanged, including their frozen state.
 			#
-			# @parameter range [String | Object] The media type or compatible range.
-			# @returns [Object | nil] The matching object, if one exists.
-			def [](range)
-				if entry = lookup(Range.for(range))
-					entry.last
+			# @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
 			
-			# Find the first object matching an ordered sequence of media ranges.
+			# Initialize a new media map with a given index.
 			#
-			# @parameter 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(ranges)
-				ranges.each do |range|
-					if entry = lookup(Range.for(range))
-						return [entry.last, range]
-					end
-				end
-				
-				return nil
+			# 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 map and its internal entries.
-			#
-			# @returns [self] The frozen map.
+			# Freeze the media map and its index.
+			# @returns [self]
 			def freeze
-				unless frozen?
-					@entries.each_value(&:freeze)
-					@entries.freeze
-				end
+				return self if frozen?
+				
+				@index.freeze
 				
-				super
+				return super
 			end
 			
-			private
-			
-			def name(range)
-				"#{range.type.downcase}/#{range.subtype.downcase}"
+			# 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
 			
-			def lookup(range)
-				range_name = name(range)
-				return @entries[range_name] if @entries.key?(range_name)
-				
-				@entries.each_value do |entry|
-					return entry if match?(range, entry.first)
+			# 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
 			
-			def match?(left, right)
-				match_component?(left.type, right.type) && match_component?(left.subtype, right.subtype)
-			end
+			private
 			
-			def match_component?(left, right)
-				left == "*" || right == "*" || left.casecmp?(right)
+			def lookup(media_range)
+				media_range = Range.build(media_range.type, media_range.subtype)
+				return @index[media_range.name]
 			end
 		end
 	end

data/lib/protocol/media/range.rb

@@ -16,6 +16,26 @@ module Protocol
 			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.
@@ -48,7 +68,7 @@ module Protocol
 					raise ArgumentError, "Invalid media range: #{text.inspect}"
 				end
 				
-				new(type, subtype, parameters)
+				return build(type, subtype, parameters)
 			end
 			
 			# Parse media type parameters from the scanner.
@@ -85,12 +105,8 @@ module Protocol
 			# @parameter subtype [String] The subtype.
 			# @parameter parameters [Hash] The media range parameters.
 			def initialize(type, subtype = "*", parameters = {})
-				unless valid_wildcard?(type, subtype)
-					raise ArgumentError, "Invalid wildcards in media range: #{type}/#{subtype}"
-				end
-				
-				@type = type.downcase
-				@subtype = subtype.downcase
+				@type = type
+				@subtype = subtype
 				@parameters = parameters
 			end
 			
@@ -114,13 +130,34 @@ module Protocol
 			
 			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 other [Range] The media type or range to match.
+			# @parameter media_range [Range] The media type or range to match.
 			# @returns [Boolean] Whether the type and subtype are compatible.
-			def match?(other)
-				(@type == "*" || other.type == "*" || @type == other.type) &&
-					(@subtype == "*" || other.subtype == "*" || @subtype == other.subtype)
+			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?
@@ -129,11 +166,11 @@ module Protocol
 			#
 			# @parameter other [Object] The object to compare.
 			# @returns [Boolean] Whether the values are equal.
-			def ==(other)
-				other.instance_of?(self.class) && @type == other.type && @subtype == other.subtype && @parameters == other.parameters
+			def eql?(other)
+				other.instance_of?(self.class) && @type.eql?(other.type) && @subtype.eql?(other.subtype) && @parameters.eql?(other.parameters)
 			end
 			
-			alias eql? ==
+			alias == eql?
 			
 			# Generate a hash key consistent with {#eql?}.
 			#
@@ -144,11 +181,17 @@ module Protocol
 			
 			private
 			
-			def valid_wildcard?(type, subtype)
-				return subtype == "*" if type == "*"
-				return false if type.include?("*")
+			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
 				
-				subtype == "*" || !subtype.include?("*")
+				return component == other_component
 			end
 			
 			def self.unquote(value, normalize_whitespace)

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

@@ -9,16 +9,36 @@ module Protocol
 	module Media
 		# A concrete media type and its parameters.
 		class Type < Range
+			# Parse strings and normalize compatible media type objects.
+			#
+			# @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
+				
+				return build(value.type, value.subtype, value.parameters)
+			end
 			
+			# Build a normalized concrete media type.
+			#
 			# @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
+				
+				# Concrete media types cannot use a wildcard subtype:
+				if subtype == "*"
 					raise ArgumentError, "Media types cannot contain wildcards: #{type}/#{subtype}"
 				end
 				
-				super
+				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.1.0"
+		VERSION = "0.2.0"
 	end
 end

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.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -15,10 +15,12 @@ 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