protocol-url 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ff6accb882e5c993ee454290f6d282d67df6b4d13ee01bdd24b042ea764ee03c
-  data.tar.gz: abc0495ee011bccd902d3f60bebcf4d8231e3559b14305fe5594d62df285eeae
+  metadata.gz: 10d18a95d6f20f5ca2457a52a2defa8d961ecf26eb372d45bea1f2d339f3a5c6
+  data.tar.gz: f15a84b24bd971e6262306b84e271196b5c20cde76983eba4625af28b0895ddd
 SHA512:
-  metadata.gz: 1a1852872d62c65b0d78f8cd698deaaca69ceea65b79fb2e9d04b0b1b347cf6555ba41c27b0c836e2b963981f0c9be9a8feeec55622cdede7018a01321d7bca6
-  data.tar.gz: 4c6a01694dda0e059d944e5155f365c27c00c244e8e5ea7310288b875f2f307e4ef0c610dd8ea906e30fd5338d13f33fb1d2b83dcd5c076d57e34a60eb515b3b
+  metadata.gz: e1493486247a9e36b696bf62225a33888905d7e4a5a83b31357dc67d227b3a6f481844e2423befc5cc21f4c0a14aebc4ea507faa68a06a50490619e455396950
+  data.tar.gz: ee45f80e209b66b2a30d6b155188138a513e9a2c632bf1a4edc0322823e9bef209d2515babc955030c43c26c9da9ea687303a2aa91fa9704a2ac0594405d8cda

data/lib/protocol/url/absolute.rb

@@ -10,6 +10,13 @@ module Protocol
 		# Represents an absolute URL with scheme and/or authority.
 		# Examples: "https://example.com/path", "//cdn.example.com/lib.js", "http://localhost/"
 		class Absolute < Relative
+			# Initialize a new absolute URL.
+			#
+			# @parameter scheme [String] The URL scheme (e.g., "https", "http").
+			# @parameter authority [String] The authority component (e.g., "example.com", "user@host:port").
+			# @parameter path [String] The path component (defaults to "/").
+			# @parameter query [String, nil] The query string.
+			# @parameter fragment [String, nil] The fragment identifier.
 			def initialize(scheme, authority, path = "/", query = nil, fragment = nil)
 				@scheme = scheme
 				@authority = authority
@@ -18,13 +25,22 @@ module Protocol
 				super(path, query, fragment)
 			end
 			
+			# @attribute [String] The URL scheme.
 			attr :scheme
+			
+			# @attribute [String] The authority component.
 			attr :authority
 			
+			# Check if the URL has a non-empty scheme.
+			#
+			# @returns [Boolean] True if a scheme is present and non-empty.
 			def scheme?
 				@scheme and !@scheme.empty?
 			end
 			
+			# Check if the URL has a non-empty authority.
+			#
+			# @returns [Boolean] True if an authority is present and non-empty.
 			def authority?
 				@authority and !@authority.empty?
 			end
@@ -93,8 +109,6 @@ module Protocol
 				super(buffer)
 			end
 			
-			UNSPECIFIED = Object.new
-			
 			# Create a new Absolute URL with modified components.
 			#
 			# @parameter scheme [String, nil] The scheme to use (nil to remove scheme).
@@ -118,14 +132,24 @@ module Protocol
 				self.class.new(scheme, authority, Path.expand(@path, path, pop), query, fragment)
 			end
 			
+			# Convert the URL to an array representation.
+			#
+			# @returns [Array] An array of `[scheme, authority, path, query, fragment]`.
 			def to_ary
 				[@scheme, @authority, @path, @query, @fragment]
 			end
 			
+			# Compare this URL with another for sorting purposes.
+			#
+			# @parameter other [Absolute] The URL to compare with.
+			# @returns [Integer] -1, 0, or 1 based on component-wise comparison.
 			def <=>(other)
 				to_ary <=> other.to_ary
 			end
 			
+			# Convert the URL to its string representation.
+			#
+			# @returns [String] The formatted absolute URL string.
 			def to_s
 				append
 			end

data/lib/protocol/url/encoding.rb

@@ -233,6 +233,17 @@ module Protocol
 				
 				return parameters
 			end
+			
+			# Decode an `application/x-www-form-urlencoded` string into a hash.
+			# In addition to percent encoding, this format represents spaces using `+`.
+			#
+			# @parameter string [String] The form-encoded string to decode.
+			# @parameter maximum [Integer] The maximum number of keys in a path.
+			# @parameter symbolize_keys [Boolean] Whether to symbolize keys.
+			# @returns [Hash] The decoded form values.
+			def self.decode_www_form(string, maximum = 8, symbolize_keys: false)
+				return self.decode(string.gsub("+", "%20"), maximum, symbolize_keys: symbolize_keys)
+			end
 		end
 	end
 end

data/lib/protocol/url/form_data/nested.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require_relative "../encoding"
+
+module Protocol
+	module URL
+		module FormData
+			# Builds nested form data from names and values.
+			class Nested
+				# The default maximum depth of a bracketed form name.
+				MAXIMUM_DEPTH = 8
+				
+				# Initialize the nested form data.
+				# @parameter maximum_depth [Integer | Nil] The maximum depth of a bracketed form name.
+				def initialize(maximum_depth: MAXIMUM_DEPTH)
+					@maximum_depth = maximum_depth
+					@root = {}
+				end
+				
+				# Add a form data value using its bracketed name.
+				# @parameter name [String] The form data name.
+				# @parameter value [Object] The form data value.
+				# @returns [Nested] The receiver.
+				def add(name, value)
+					keys = Encoding.split(name)
+					
+					if keys.empty?
+						raise ArgumentError, "Invalid form data name: #{name.inspect}!"
+					end
+					
+					if @maximum_depth and keys.size > @maximum_depth
+						raise RangeError, "Form data depth exceeded limit of #{@maximum_depth}!"
+					end
+					
+					Encoding.assign(keys, value, @root)
+					
+					return self
+				end
+				
+				# Convert the arguments to a nested hash.
+				# @returns [Hash] The nested arguments.
+				def to_h
+					return @root
+				end
+			end
+		end
+	end
+end

data/lib/protocol/url/form_data/parser.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require_relative "nested"
+
+module Protocol
+	module URL
+		# @namespace
+		module FormData
+			# Incrementally parses `application/x-www-form-urlencoded` form data.
+			class Parser
+				CONTENT_TYPE = "application/x-www-form-urlencoded"
+				
+				# The default maximum encoded body size.
+				MAXIMUM_TOTAL_SIZE = 2 * 1024 * 1024
+				
+				# The default maximum number of form pairs.
+				MAXIMUM_PAIR_COUNT = 1024
+				
+				# Initialize the form data parser.
+				# @parameter maximum_total_size [Integer | Nil] The maximum encoded body size.
+				# @parameter maximum_pair_count [Integer | Nil] The maximum number of form pairs.
+				# @parameter maximum_depth [Integer | Nil] The maximum depth of a bracketed form name.
+				def initialize(maximum_total_size: MAXIMUM_TOTAL_SIZE, maximum_pair_count: MAXIMUM_PAIR_COUNT, maximum_depth: Nested::MAXIMUM_DEPTH)
+					@maximum_total_size = maximum_total_size
+					@maximum_pair_count = maximum_pair_count
+					@maximum_depth = maximum_depth
+				end
+				
+				# Parse URL-encoded form data into a nested hash.
+				#
+				# When a block is given, each decoded value is passed through the block before assignment. The value returned by the block is assigned to the result.
+				#
+				# @parameter body [Object] A readable body which yields chunks from `#read`.
+				# @yields {|name, value| ...} Each decoded form pair before assignment.
+				# @returns [Hash] The nested form data.
+				def parse(body)
+					nested = Nested.new(maximum_depth: @maximum_depth)
+					
+					each(body) do |name, value|
+						value = yield(name, value) if block_given?
+						nested.add(name, value)
+					end
+					
+					return nested.to_h
+				end
+				
+				# Incrementally enumerate URL-encoded form data as ordered name/value pairs.
+				# @parameter body [Object] A readable body which yields chunks from `#read`.
+				# @yields {|name, value| ...} Each decoded form pair.
+				# @returns [Enumerator | Boolean] An enumerator without a block, or true when complete.
+				def each(body)
+					return to_enum(__method__, body) unless block_given?
+					
+					buffer = String.new.b
+					total_size = 0
+					pair_count = 0
+					
+					while chunk = body.read
+						break if chunk.empty?
+						
+						total_size += chunk.bytesize
+						check_limit(:total_size, total_size, @maximum_total_size)
+						buffer << chunk
+						
+						while separator = buffer.index("&")
+							assignment = buffer.slice!(0, separator + 1)
+							assignment.chop!
+							
+							unless assignment.empty?
+								pair_count += 1
+								check_limit(:pair_count, pair_count, @maximum_pair_count)
+								yield_pair(assignment) {|name, value| yield name, value}
+							end
+						end
+					end
+					
+					unless buffer.empty?
+						pair_count += 1
+						check_limit(:pair_count, pair_count, @maximum_pair_count)
+						yield_pair(buffer) {|name, value| yield name, value}
+					end
+					
+					return true
+				end
+				
+				private
+				
+				def yield_pair(assignment)
+					name, value = assignment.split("=", 2)
+					
+					if value
+						value = decode_component(value)
+					end
+					
+					yield decode_component(name), value
+				end
+				
+				def decode_component(component)
+					return Encoding.unescape(component.tr("+", " "))
+				end
+				
+				def check_limit(name, value, maximum)
+					if maximum and value > maximum
+						raise RangeError, "Form data #{name} exceeded limit of #{maximum}!"
+					end
+				end
+			end
+		end
+	end
+end

data/lib/protocol/url/reference.rb

@@ -17,6 +17,35 @@ module Protocol
 		class Reference < Relative
 			include Comparable
 			
+			# Coerce a value into a {Reference} instance.
+			#
+			# This method provides flexible conversion from various types into a {Reference}.
+			# When given a {String}, it parses the URL-encoded path, query, and fragment components
+			# and unescapes them for internal storage. When given a {Relative}, it converts the
+			# encoded values to unescaped form suitable for {Reference} instances.
+			#
+			# @parameter value [String | Relative | Nil] The value to coerce.
+			# @parameter parameters [Hash | Nil] Optional user-supplied parameters to append to the query string.
+			#
+			# @returns [Reference | Nil] A new reference instance, or `nil` if the input is `nil`.
+			#
+			# @raises [ArgumentError] If the string contains whitespace or control characters.
+			# @raises [ArgumentError] If the value cannot be coerced to a {Reference}.
+			#
+			# @example Coerce a string with path, query, and fragment.
+			# 	reference = Reference["/search?q=ruby#results"]
+			# 	reference.path      # => "/search"
+			# 	reference.query     # => "q=ruby"
+			# 	reference.fragment  # => "results"
+			#
+			# @example Coerce with additional parameters.
+			# 	reference = Reference["/search", {"limit" => "10"}]
+			# 	reference.to_s  # => "/search?limit=10"
+			#
+			# @example Coerce a Relative instance.
+			# 	relative = Relative.new("/path%20with%20spaces", nil, "top")
+			# 	reference = Reference[relative]
+			# 	reference.path  # => "/path with spaces"
 			def self.[](value, parameters = nil)
 				case value
 				when String
@@ -25,7 +54,7 @@ module Protocol
 						query = match[:query]
 						fragment = match[:fragment]
 						
-						# Unescape path and fragment for user-friendly internal storage
+						# Unescape path and fragment for user-friendly internal storage:
 						# Query strings are kept as-is since they contain = and & syntax
 						path = Encoding.unescape(path) if path && !path.empty?
 						fragment = Encoding.unescape(fragment) if fragment
@@ -35,7 +64,7 @@ module Protocol
 						raise ArgumentError, "Invalid URL (contains whitespace or control characters): #{value.inspect}"
 					end
 				when Relative
-					# Relative stores encoded values, so we need to unescape them for Reference
+					# Relative stores encoded values, so we need to unescape them for Reference:
 					path = value.path
 					fragment = value.fragment
 					

data/lib/protocol/url/relative.rb

@@ -12,16 +12,29 @@ module Protocol
 		class Relative
 			include Comparable
 			
+			# Initialize a new relative URL.
+			#
+			# @parameter path [String] The path component.
+			# @parameter query [String, nil] The query string.
+			# @parameter fragment [String, nil] The fragment identifier.
 			def initialize(path, query = nil, fragment = nil)
 				@path = path.to_s
 				@query = query
 				@fragment = fragment
 			end
 			
+			# @attribute [String] The path component of the URL.
 			attr :path
+			
+			# @attribute [String, nil] The query string component.
 			attr :query
+			
+			# @attribute [String, nil] The fragment identifier.
 			attr :fragment
 			
+			# Convert the URL path to a local filesystem path.
+			#
+			# @returns [String] The local filesystem path.
 			def to_local_path
 				Path.to_local_path(@path)
 			end
@@ -131,42 +144,76 @@ module Protocol
 				return buffer
 			end
 			
+			# Convert the URL to an array representation.
+			#
+			# @returns [Array] An array of `[path, query, fragment]`.
 			def to_ary
 				[@path, @query, @fragment]
 			end
 			
+			# Compute a hash value for the URL based on its components.
+			#
+			# @returns [Integer] The hash value.
 			def hash
 				to_ary.hash
 			end
 			
+			# Check if this URL is equal to another URL by comparing components.
+			#
+			# @parameter other [Relative] The URL to compare with.
+			# @returns [Boolean] True if the URLs have identical components.
 			def equal?(other)
 				to_ary == other.to_ary
 			end
 			
+			# Compare this URL with another for sorting purposes.
+			#
+			# @parameter other [Relative] The URL to compare with.
+			# @returns [Integer] -1, 0, or 1 based on component-wise comparison.
 			def <=>(other)
 				to_ary <=> other.to_ary
 			end
 			
+			# Check structural equality by comparing components.
+			#
+			# @parameter other [Relative] The URL to compare with.
+			# @returns [Boolean] True if the URLs have identical components.
 			def ==(other)
 				to_ary == other.to_ary
 			end
 			
+			# Check string equality, useful for case statements.
+			#
+			# @parameter other [String, Relative] The value to compare with.
+			# @returns [Boolean] True if the string representations match.
 			def ===(other)
 				to_s === other
 			end
 			
+			# Convert the URL to its string representation.
+			#
+			# @returns [String] The formatted URL string.
 			def to_s
 				append
 			end
 			
+			# Convert the URL to a JSON-compatible representation.
+			#
+			# @returns [String] The URL as a string.
 			def as_json(...)
 				to_s
 			end
 			
+			# Convert the URL to JSON.
+			#
+			# @returns [String] The JSON-encoded URL.
 			def to_json(...)
 				as_json.to_json(...)
 			end
 			
+			# Generate a human-readable representation for debugging.
+			#
+			# @returns [String] A string like `#<Protocol::URL::Relative /path?query#fragment>`.
 			def inspect
 				"#<#{self.class} #{to_s}>"
 			end

data/lib/protocol/url/version.rb

@@ -7,6 +7,6 @@
 module Protocol
 	# @namespace
 	module URL
-		VERSION = "0.4.0"
+		VERSION = "0.6.0"
 	end
 end

data/lib/protocol/url.rb

@@ -6,6 +6,8 @@
 require_relative "url/version"
 require_relative "url/pattern"
 require_relative "url/encoding"
+require_relative "url/form_data/nested"
+require_relative "url/form_data/parser"
 require_relative "url/reference"
 require_relative "url/relative"
 require_relative "url/absolute"

data/readme.md

@@ -6,11 +6,11 @@ Provides abstractions for working with URLs.
 
 ## Usage
 
-Please see the [project documentation](https://github.com/socketry/protocol-url) for more details.
+Please see the [project documentation](https://socketry.github.io/protocol-url/) for more details.
 
-  - [Getting Started](https://github.com/socketry/protocol-urlguides/getting-started/index) - This guide explains how to get started with `protocol-url` for parsing, manipulating, and constructing URLs in Ruby.
+  - [Getting Started](https://socketry.github.io/protocol-url/guides/getting-started/index) - This guide explains how to get started with `protocol-url` for parsing, manipulating, and constructing URLs in Ruby.
 
-  - [Working with References](https://github.com/socketry/protocol-urlguides/working-with-references/index) - This guide explains how to use <code class="language-ruby">Protocol::URL::Reference</code> for managing URLs with query parameters and fragments.
+  - [Working with References](https://socketry.github.io/protocol-url/guides/working-with-references/index) - This guide explains how to use <code class="language-ruby">Protocol::URL::Reference</code> for managing URLs with query parameters and fragments.
 
 ## Contributing
 
@@ -32,7 +32,16 @@ This project is best served by a collaborative and respectful environment. Treat
 
 ## Releases
 
-Please see the [project releases](https://github.com/socketry/protocol-urlreleases/index) for all releases.
+Please see the [project releases](https://socketry.github.io/protocol-url/releases/index) for all releases.
+
+### v0.6.0
+
+  - Add `Protocol::URL::FormData::Parser` for incremental, limited parsing of `application/x-www-form-urlencoded` form data.
+  - Add `Protocol::URL::FormData::Nested` for consistently building nested form data while preserving absent and empty values.
+
+### v0.5.0
+
+  - Add `Protocol::URL::Encoding.decode_www_form` for decoding HTML form data where `+` represents a space.
 
 ### v0.4.0
 

data/releases.md

@@ -1,5 +1,14 @@
 # Releases
 
+## v0.6.0
+
+  - Add `Protocol::URL::FormData::Parser` for incremental, limited parsing of `application/x-www-form-urlencoded` form data.
+  - Add `Protocol::URL::FormData::Nested` for consistently building nested form data while preserving absent and empty values.
+
+## v0.5.0
+
+  - Add `Protocol::URL::Encoding.decode_www_form` for decoding HTML form data where `+` represents a space.
+
 ## v0.4.0
 
   - Add comparison methods to `Protocol::URL::Relative` (and by inheritance to `Protocol::URL::Absolute`):

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: protocol-url
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -45,6 +45,8 @@ files:
 - lib/protocol/url.rb
 - lib/protocol/url/absolute.rb
 - lib/protocol/url/encoding.rb
+- lib/protocol/url/form_data/nested.rb
+- lib/protocol/url/form_data/parser.rb
 - lib/protocol/url/path.rb
 - lib/protocol/url/pattern.rb
 - lib/protocol/url/reference.rb
@@ -58,6 +60,7 @@ licenses:
 - MIT
 metadata:
   source_code_uri: https://github.com/socketry/protocol-url.git
+  documentation_uri: https://socketry.github.io/protocol-url/
 rdoc_options: []
 require_paths:
 - lib
@@ -72,7 +75,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.7.2
+rubygems_version: 4.0.10
 specification_version: 4
 summary: Provides abstractions for working with URLs.
 test_files: []