protocol-url 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 12a81d3a05c932207c77a583df784431d7120f3f1f9ee68c9ea593a47c666831
-  data.tar.gz: 3307c15e0d16d4907259cd186c0483d46d78358e0b1bfee99e3cf3186a1c74d2
+  metadata.gz: fb5e51237375afb74dda311e130ad550240453d53c42c5c0c05ddc532231261f
+  data.tar.gz: fbcf705936fedf9e967af1eb66ef2d901f68448bfe9e47d3ffd21156486207f0
 SHA512:
-  metadata.gz: 8e948fff9470b6676b5b28638af7fdc64eaa31e3565c980071a539eadbf3651b8c10037ed1bcec70b43360a30fbb595f14bf965898e6ab4f1b4e8baf1e942491
-  data.tar.gz: 86de1d30699c4c3f7c85878ca3c0edf45da61991593d4600bfc83be2b667525ccc8bb01ea5a51ddf82248045933b49a3ef8879947100a5ac88d67d94a2947786
+  metadata.gz: c49c2bc6639b2b0777ae93c3b8ee34bd7c496831deb32da8af725ebc4f873d2666a47b68bc6aa031d7b1dbee522488927011c1d5ceb9b81140e4ea3c4ae2e575
+  data.tar.gz: 05c41426fdc297a5bae0a59d6ef4ca31e88a0cc592769038474c28b948b7615b5cecae17943d6263fe8bd02b079f178d427b2cdc7c4ea1393a5e28da8ccaa55f

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/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
 					
@@ -95,14 +124,6 @@ module Protocol
 				[@path, @query, @fragment, @parameters]
 			end
 			
-			# Compare two references.
-			#
-			# @parameter other [Reference] The other reference to compare.
-			# @returns [Integer] -1, 0, 1 if the reference is less than, equal to, or greater than the other reference.
-			def <=> other
-				to_ary <=> other.to_ary
-			end
-			
 			# @returns [Boolean] Whether the reference has parameters.
 			def parameters?
 				@parameters and !@parameters.empty?

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,18 +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.3.0"
+		VERSION = "0.5.0"
 	end
 end

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,23 @@ 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.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`):
+      - `#==` for structural equality comparison (compares path, query, fragment components).
+      - `#===` for string equality comparison (enables case statement matching).
+      - `#<=>` for ordering and sorting.
+      - `#hash` for hash key support.
+      - `#equal?` for component-based equality checking.
+  - Add JSON serialization support to `Protocol::URL::Relative`:
+      - `#as_json` returns the string representation.
+      - `#to_json` returns a JSON-encoded string.
 
 ### v0.3.0
 

data/releases.md

@@ -1,5 +1,21 @@
 # Releases
 
+## 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`):
+      - `#==` for structural equality comparison (compares path, query, fragment components).
+      - `#===` for string equality comparison (enables case statement matching).
+      - `#<=>` for ordering and sorting.
+      - `#hash` for hash key support.
+      - `#equal?` for component-based equality checking.
+  - Add JSON serialization support to `Protocol::URL::Relative`:
+      - `#as_json` returns the string representation.
+      - `#to_json` returns a JSON-encoded string.
+
 ## v0.3.0
 
   - Add `relative(target, from)` for computing relative paths between URLs.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: protocol-url
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -58,6 +58,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 +73,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: []

metadata.gz.sig

@@ -1,2 +1,3 @@
-4���:U���F���}��M����GL��������+���$�����!�┋M#jh��}�_:���x�ǂ��K���@���sڼ�j��4�qЎI�Ɇ+�-�C�r�e�<��u��
��_�!Qn �(�-䊍=0�������x����4=�Jۈ�W�͡�|�*�L��3��[�𹢶�[�[
��d���fRᾉ�����3���N�C�e)ݔ�m���ҋ�k�G!�LO;
-nL�B���<�u`����5OPĭK�:��qX�)��UF��Dɿ[y�P��W��ڰ���\�%R�qֻNz
+s��Ѽ�2=�p���
+�_|�xy-ꡨ]A=�q��L������,h��H�*��m�DR�oM��A���C�u���1���ϻ���T���r���IA���eK��5`}���E͎5����j�;�,
����\��2����0��m��*�v#��r�=s�Z�@K^�N�Lw�`��TOS"�K ����k|wN(� 0��r�g�FmM���3�T$8��_�z�}6
+HH���bX!��r�����U�v����dDN���EP�ۛ�<�Z�wx8��{��`��J?6��֩��S0ڲ����,1g�Sľ���P������	Fq{13�X�?c�.p. ��,�N�3!��