protocol-media 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 41cc93afe36dc9af35b5ca77721b8859543b270627a3cb9f7f6cc2df2334d83e
-  data.tar.gz: 306bf200c34635b7eba643945121d6150054759ffa7ffa9ce5f08bf0668aa3b0
+  metadata.gz: b242140a081b74335a73f8e92656c41a45f7c07b6d25d49d710a3b10192de458
+  data.tar.gz: af83ab4f1cc8e8e02c110a38c2d38fbc62cf7d8649cfb0b5fdbd765a11ef663e
 SHA512:
-  metadata.gz: 7ab4060ead68e7b62f6486e298155e23060019bf7eb4bc9d2524efcb5cfe65e0a018945d46305730359b0c7e6bca158b44632ce5b7ca06ffd6c3c0bc2b8d327c
-  data.tar.gz: 84ccb4d5c42a6431cdc7da7d5ba6d1c776581bb561f0bde140d002c7cc5549f13304023c5d55bf4385c3e1de5a17be86c9d0aefcd2f708969aef3476772faa39
+  metadata.gz: f6536b595d6c5ec253898823de7ab9e0d8875e767e6b0e35d70865962beafedf80e3659f652894e17333612a3f7504d185c25ebd080570b0a75b6cc57cd44de4
+  data.tar.gz: adc4678525e9ac20e227db5b89256caadcbefeba5a9b4972cffd8937ae02b129c039ae301960142884773d0fb6d548c4b991605b81aa8c7ce45f96cd180ae7d7

data/lib/protocol/media/map.rb

@@ -7,48 +7,8 @@ require_relative "type"
 
 module Protocol
 	module Media
-		# An immutable map from concrete media types to objects for range-based lookup.
+		# A 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.
@@ -58,28 +18,44 @@ module Protocol
 			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
+				return new(entries).freeze
 			end
 			
-			# Initialize a new media map with a given index.
+			# Initialize a new mutable media map with the given entries.
 			#
-			# The index is retained without copying or freezing it.
+			# Freezing the map compiles the entries into an efficient immutable index.
 			#
-			# @parameter index [Hash] The keyed media range entries.
-			def initialize(index)
-				@index = index
+			# @parameter entries [Enumerable] The keyed media type entries.
+			def initialize(entries = {})
+				@entries = {}
+				@index = nil
+				
+				entries.each do |media_type, object|
+					self[media_type] = object
+				end
+			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)
+				raise FrozenError, "can't modify frozen #{self.class}" if frozen?
+				
+				media_type = Type.for(media_type)
+				
+				@entries[media_type.name] = [media_type, object]
+				@index = nil
 			end
 			
-			# Freeze the media map and its index.
+			# Freeze the media map, compiling its entries into an efficient index.
 			# @returns [self]
 			def freeze
 				return self if frozen?
 				
-				@index.freeze
+				index = self.index
+				@entries = nil
+				
+				index.freeze
 				
 				return super
 			end
@@ -110,7 +86,25 @@ module Protocol
 			
 			def lookup(media_range)
 				media_range = Range.build(media_range.type, media_range.subtype)
-				return @index[media_range.name]
+				
+				return index[media_range.name]
+			end
+			
+			def index
+				return @index ||= compile(@entries)
+			end
+			
+			def compile(entries)
+				index = {}
+				
+				entries.each_value do |media_type, object|
+					# Preserve the first registration as the default for wildcard queries:
+					index["*/*"] ||= object
+					index["#{media_type.type}/*"] ||= object
+					index[media_type.name] = object
+				end
+				
+				return index
 			end
 		end
 	end

data/lib/protocol/media/set.rb

@@ -9,7 +9,7 @@ require "set"
 
 module Protocol
 	module Media
-		# An immutable set of compatible media ranges.
+		# A set of compatible media ranges.
 		class Set
 			include Enumerable
 			
@@ -56,73 +56,18 @@ module Protocol
 				def empty?
 					return false
 				end
+				
+				# Whether this set matches every media range.
+				# @returns [Boolean]
+				def universal?
+					return true
+				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.
@@ -140,29 +85,58 @@ module Protocol
 					return media_ranges
 				end
 				
-				return build do |builder|
-					media_ranges.each do |media_range|
-						builder << media_range
-					end
+				set = new(media_ranges)
+				set.freeze
+				
+				if set.universal?
+					return ANY
 				end
+				
+				return set
 			end
 			
-			# Initialize a new media set with the given type index.
+			# Initialize a new mutable media set with the given media ranges.
 			#
-			# The index is retained without copying or freezing it.
+			# Freezing the set compiles the ranges into an efficient immutable index.
 			#
-			# @parameter types [Hash] The indexed media ranges.
-			def initialize(types)
-				@types = types
+			# @parameter media_ranges [Enumerable] The existing media ranges.
+			def initialize(media_ranges = [])
+				@entries = []
+				@types = nil
+				
+				media_ranges.each do |media_range|
+					add(media_range)
+				end
+			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)
+				raise FrozenError, "can't modify frozen #{self.class}" if frozen?
+				
+				media_range = normalize(media_range)
+				
+				@entries << media_range
+				@types = nil
+				
+				return self
 			end
 			
-			# Freeze the media set and its index.
+			alias << add
+			
+			# Freeze the media set, compiling its ranges into an efficient index.
 			# @returns [self]
 			def freeze
 				return self if frozen?
 				
-				@types.each_value(&:freeze)
-				@types.freeze
+				types = self.types
+				@entries = nil
+				
+				unless types.instance_of?(Any)
+					types.each_value(&:freeze)
+					types.freeze
+				end
 				
 				return super
 			end
@@ -174,13 +148,18 @@ module Protocol
 				media_range = normalize(media_range)
 				type = media_range.type
 				subtype = media_range.subtype
+				types = self.types
+				
+				if types.instance_of?(Any)
+					return true
+				end
 				
 				# A wildcard type matches any non-empty set:
 				if type == "*"
-					return !@types.empty?
+					return !types.empty?
 				end
 				
-				subtypes = @types[type]
+				subtypes = types[type]
 				
 				# An unknown type cannot match:
 				unless subtypes
@@ -206,10 +185,17 @@ module Protocol
 			# 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?
+			def each(&block)
+				return to_enum unless block
+				
+				types = self.types
+				
+				if types.instance_of?(Any)
+					types.each(&block)
+					return self
+				end
 				
-				@types.each do |type, subtypes|
+				types.each do |type, subtypes|
 					if subtypes.instance_of?(Any)
 						yield Range.new(type, "*")
 					else
@@ -225,7 +211,13 @@ module Protocol
 			# The number of canonical membership ranges.
 			# @returns [Integer]
 			def size
-				return @types.sum do |_type, subtypes|
+				types = self.types
+				
+				if types.instance_of?(Any)
+					return types.size
+				end
+				
+				return types.sum do |_type, subtypes|
 					subtypes.size
 				end
 			end
@@ -233,11 +225,44 @@ module Protocol
 			# Whether the set contains no media ranges.
 			# @returns [Boolean]
 			def empty?
-				return @types.empty?
+				return types.empty?
+			end
+			
+			# Whether this set matches every media range.
+			# @returns [Boolean]
+			def universal?
+				return types.instance_of?(Any)
 			end
 			
 			private
 			
+			def types
+				return @types ||= compile(@entries)
+			end
+			
+			def compile(media_ranges)
+				types = {}
+				
+				media_ranges.each do |media_range|
+					type = media_range.type.freeze
+					subtype = media_range.subtype.freeze
+					
+					if type == "*"
+						return 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
+				end
+				
+				return types
+			end
+			
 			def normalize(media_range)
 				media_range = Range.for(media_range)
 				return Range.build(media_range.type, media_range.subtype)

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.2.0"
+		VERSION = "0.3.0"
 	end
 end

data/readme.md

@@ -2,6 +2,8 @@
 
 Provides a small representation of media types which can be shared by protocol implementations and registry backends.
 
+[![Development Status](https://github.com/socketry/protocol-media/workflows/Test/badge.svg)](https://github.com/socketry/protocol-media/actions?workflow=Test)
+
 ## Usage
 
 Please see the [project documentation](https://socketry.github.io/protocol-media/) for more details.
@@ -10,6 +12,20 @@ Please see the [project documentation](https://socketry.github.io/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.
 
+## Releases
+
+Please see the [project releases](https://socketry.github.io/protocol-media/releases/index) for all releases.
+
+### v0.3.0
+
+  - Replace media map and set builders with mutable collections that can be frozen after construction.
+  - Simplify lazy compilation of media map and set indexes.
+
+### v0.2.1
+
+  - 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.
+
 ## 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

@@ -1,6 +1,11 @@
 # Releases
 
-## Unreleased
+## v0.3.0
+
+  - Replace media map and set builders with mutable collections that can be frozen after construction.
+  - Simplify lazy compilation of media map and set indexes.
+
+## v0.2.1
 
   - 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,12 +1,41 @@
 --- !ruby/object:Gem::Specification
 name: protocol-media
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Samuel Williams
 bindir: bin
-cert_chain: []
+cert_chain:
+- |
+  -----BEGIN CERTIFICATE-----
+  MIIE2DCCA0CgAwIBAgIBATANBgkqhkiG9w0BAQsFADBhMRgwFgYDVQQDDA9zYW11
+  ZWwud2lsbGlhbXMxHTAbBgoJkiaJk/IsZAEZFg1vcmlvbnRyYW5zZmVyMRIwEAYK
+  CZImiZPyLGQBGRYCY28xEjAQBgoJkiaJk/IsZAEZFgJuejAeFw0yMjA4MDYwNDUz
+  MjRaFw0zMjA4MDMwNDUzMjRaMGExGDAWBgNVBAMMD3NhbXVlbC53aWxsaWFtczEd
+  MBsGCgmSJomT8ixkARkWDW9yaW9udHJhbnNmZXIxEjAQBgoJkiaJk/IsZAEZFgJj
+  bzESMBAGCgmSJomT8ixkARkWAm56MIIBojANBgkqhkiG9w0BAQEFAAOCAY8AMIIB
+  igKCAYEAomvSopQXQ24+9DBB6I6jxRI2auu3VVb4nOjmmHq7XWM4u3HL+pni63X2
+  9qZdoq9xt7H+RPbwL28LDpDNflYQXoOhoVhQ37Pjn9YDjl8/4/9xa9+NUpl9XDIW
+  sGkaOY0eqsQm1pEWkHJr3zn/fxoKPZPfaJOglovdxf7dgsHz67Xgd/ka+Wo1YqoE
+  e5AUKRwUuvaUaumAKgPH+4E4oiLXI4T1Ff5Q7xxv6yXvHuYtlMHhYfgNn8iiW8WN
+  XibYXPNP7NtieSQqwR/xM6IRSoyXKuS+ZNGDPUUGk8RoiV/xvVN4LrVm9upSc0ss
+  RZ6qwOQmXCo/lLcDUxJAgG95cPw//sI00tZan75VgsGzSWAOdjQpFM0l4dxvKwHn
+  tUeT3ZsAgt0JnGqNm2Bkz81kG4A2hSyFZTFA8vZGhp+hz+8Q573tAR89y9YJBdYM
+  zp0FM4zwMNEUwgfRzv1tEVVUEXmoFCyhzonUUw4nE4CFu/sE3ffhjKcXcY//qiSW
+  xm4erY3XAgMBAAGjgZowgZcwCQYDVR0TBAIwADALBgNVHQ8EBAMCBLAwHQYDVR0O
+  BBYEFO9t7XWuFf2SKLmuijgqR4sGDlRsMC4GA1UdEQQnMCWBI3NhbXVlbC53aWxs
+  aWFtc0BvcmlvbnRyYW5zZmVyLmNvLm56MC4GA1UdEgQnMCWBI3NhbXVlbC53aWxs
+  aWFtc0BvcmlvbnRyYW5zZmVyLmNvLm56MA0GCSqGSIb3DQEBCwUAA4IBgQB5sxkE
+  cBsSYwK6fYpM+hA5B5yZY2+L0Z+27jF1pWGgbhPH8/FjjBLVn+VFok3CDpRqwXCl
+  xCO40JEkKdznNy2avOMra6PFiQyOE74kCtv7P+Fdc+FhgqI5lMon6tt9rNeXmnW/
+  c1NaMRdxy999hmRGzUSFjozcCwxpy/LwabxtdXwXgSay4mQ32EDjqR1TixS1+smp
+  8C/NCWgpIfzpHGJsjvmH2wAfKtTTqB9CVKLCWEnCHyCaRVuKkrKjqhYCdmMBqCws
+  JkxfQWC+jBVeG9ZtPhQgZpfhvh+6hMhraUYRQ6XGyvBqEUe+yo6DKIT3MtGE2+CP
+  eX9i9ZWBydWb8/rvmwmX2kkcBbX0hZS1rcR593hGc61JR6lvkGYQ2MYskBveyaxt
+  Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
+  voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
+  -----END CERTIFICATE-----
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
 executables: []