protocol-media 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f2b4e5ba22b3b99614f42ca660be8745ea4d8b16a83dc8b97728461a5b4601d6
+  data.tar.gz: d9eea7f70012140ce42dee2501b48281b17476a5207e017ecd3a44891fac74fa
+SHA512:
+  metadata.gz: bb8adf6b0a4aa0df12f48cac05123671dc00bbdb53ee46825cd8e26676020fb4685302c99e4c1967e68ca6b2ab36d706b7f0b884a3e48c6d80d124ed48e43810
+  data.tar.gz: '0961e8287d2d249e37ffdf576fe17d27da6727070cacaa4694b8c84b6c0ef3f8b98a4f88b8cfca5f93758b8058b1522cc4cc728653d085985d5355fad9106df1'

data/lib/protocol/media/type.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require_relative "version"
+
+require "strscan"
+
+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.
+			#
+			# @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}"
+				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)
+			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`.
+			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?("*")
+					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")}\""
+				end
+			end
+		end
+	end
+end

data/lib/protocol/media/version.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+# @namespace
+module Protocol
+	# Models media types used by internet protocols and data formats.
+	module Media
+		VERSION = "0.0.1"
+	end
+end

data/license.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright, 2016-2026, by Samuel Williams.  
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/readme.md

@@ -0,0 +1,14 @@
+# Protocol::Media
+
+Provides a small representation of media types which can be shared by protocol implementations and registry backends.
+
+``` ruby
+require "protocol/media/type"
+
+type = Protocol::Media::Type.parse("text/plain; charset=utf-8")
+type.type # => "text"
+type.subtype # => "plain"
+type.parameters # => {"charset" => "utf-8"}
+```
+
+Registry data and indexed lookup are provided separately by `protocol-media-data`.

metadata

@@ -0,0 +1,43 @@
+--- !ruby/object:Gem::Specification
+name: protocol-media
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Samuel Williams
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/protocol/media/type.rb
+- lib/protocol/media/version.rb
+- license.md
+- readme.md
+homepage: https://github.com/socketry/protocol-media
+licenses:
+- MIT
+metadata:
+  documentation_uri: https://socketry.github.io/protocol-media/
+  source_code_uri: https://github.com/socketry/protocol-media.git
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: Provides abstractions for working with media types.
+test_files: []