More consistent implementation of Reference.

Author: ioquatix

guides/getting-started/readme.md

@@ -25,7 +25,7 @@ Additionally, the {ruby Protocol::URL::Path} module provides low-level utilities
 Parse complete URLs with scheme and authority:
 
 ``` ruby
-require 'protocol/url'
+require "protocol/url"
 
 # Parse an absolute URL:
 url = Protocol::URL["https://api.example.com:8080/v1/users?page=2#results"]
@@ -170,7 +170,7 @@ updated.to_s  # => "/api/users?status=inactive#results"
 The library handles URL encoding automatically for path components:
 
 ``` ruby
-require 'protocol/url/encoding'
+require "protocol/url/encoding"
 
 # Escape path components (preserves slashes):
 escaped = Protocol::URL::Encoding.escape_path("/path/with spaces/file.html")

guides/working-with-references/readme.md

@@ -13,7 +13,7 @@ You can create references in several ways:
 ### Constructing from Components
 
 ``` ruby
-require 'protocol/url'
+require "protocol/url"
 
 # Reference with path only:
 reference = Protocol::URL::Reference.new("/api/users")
@@ -125,9 +125,9 @@ You can update multiple components at once:
 base = Protocol::URL::Reference.new("/api/users")
 
 modified = base.with(
-  path: "posts",
-  query: "author=john&status=published",
-  fragment: "top"
+		path: "posts",
+		query: "author=john&status=published",
+		fragment: "top"
 )
 modified.to_s  # => "/api/posts?author=john&status=published#top"
 ```

lib/protocol/url.rb

@@ -10,19 +10,20 @@
 require_relative "url/absolute"
 
 module Protocol
-	# Helpers for working with URLs.
 	module URL
 		# RFC 3986 URI pattern with named capture groups.
 		# Matches: [scheme:][//authority][path][?query][#fragment]
+		# Rejects strings containing whitespace or control characters (matching standard URI behavior).
 		PATTERN = %r{
 			\A
 			(?:(?<scheme>[a-z][a-z0-9+.-]*):)?      # scheme (optional)
-			(?<authority>//[^/?#]*)?                # authority with // (optional)
-			(?<path>[^?#]*)                         # path
-			(?:\?(?<query>[^#]*))?                  # query (optional)
-			(?:\#(?<fragment>.*))?                  # fragment (optional)
+			(?://(?<authority>[^/?#\s]*))?          # authority (optional, without //, no whitespace)
+			(?<path>[^?#\s]*)                       # path (no whitespace)
+			(?:\?(?<query>[^#\s]*))?                # query (optional, no whitespace)
+			(?:\#(?<fragment>[^\s]*))?              # fragment (optional, no whitespace)
 			\z
 		}ix
+		private_constant :PATTERN
 
 		# Coerce a value into an appropriate URL type (Absolute or Relative).
 		#
@@ -38,12 +39,6 @@ def self.[](value)
 					query = match[:query]
 					fragment = match[:fragment]
 
-					# Strip the "//" prefix from authority
-					authority = authority[2..-1] if authority
-					
-					# Decode the fragment if present
-					fragment = Encoding.unescape(fragment) if fragment
-					
 					# If we have a scheme or authority, it's an absolute URL
 					if scheme || authority
 						Absolute.new(scheme, authority, path, query, fragment)
@@ -52,7 +47,7 @@ def self.[](value)
 						Relative.new(path, query, fragment)
 					end
 				else
-					raise ArgumentError, "Invalid URL: #{value}"
+					raise ArgumentError, "Invalid URL (contains whitespace or control characters): #{value.inspect}"
 				end
 			when Relative
 				value

lib/protocol/url/absolute.rb

@@ -21,6 +21,14 @@ def initialize(scheme, authority, path = "/", query = nil, fragment = nil)
 			attr :scheme
 			attr :authority
 
+			def scheme?
+				@scheme and !@scheme.empty?
+			end
+			
+			def authority?
+				@authority and !@authority.empty?
+			end
+			
 			# Combine this absolute URL with a relative reference according to RFC 3986 Section 5.
 			#
 			# @parameter other [String, Relative, Reference, Absolute] The reference to resolve.
@@ -73,6 +81,29 @@ def append(buffer = String.new)
 				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).
+			# @parameter authority [String, nil] The authority to use (nil to remove authority).
+			# @parameter path [String, nil] The path to merge with the current path.
+			# @parameter query [String, nil] The query string to use.
+			# @parameter fragment [String, nil] The fragment to use.
+			# @parameter pop [Boolean] Whether to pop the last path component before merging.
+			# @returns [Absolute] A new Absolute URL with the modified components.
+			def with(scheme: @scheme, authority: @authority, path: nil, query: @query, fragment: @fragment, pop: true)
+				self.class.new(scheme, authority, Path.expand(@path, path, pop), query, fragment)
+			end
+			
+			def to_ary
+				[@scheme, @authority, @path, @query, @fragment]
+			end
+			
+			def <=>(other)
+				to_ary <=> other.to_ary
+			end
+			
 			def to_s
 				append
 			end

lib/protocol/url/path.rb

@@ -63,7 +63,7 @@ def self.simplify(components)
 			# @parameter pop [Boolean] whether to remove the last path component of the base path, to conform to URI merging behaviour, as defined by RFC2396.
 			def self.expand(base, relative, pop = true)
 				# Empty relative path means no change:
-				return base if relative.empty?
+				return base if relative.nil? || relative.empty?
 
 				components = split(base)
 

lib/protocol/url/reference.rb

@@ -14,12 +14,33 @@ module URL
 		class Reference < Relative
 			include Comparable
 
-			# Generate a reference from a path and user parameters. The path may contain a `#fragment` or `?query=parameters`.
-			def self.parse(value, parameters = nil)
-				base, fragment = value.split("#", 2)
-				path, query = base.split("?", 2)
-				
-				self.new(path, query, fragment, parameters)
+			def self.[](value, parameters = nil)
+				case value
+				when String
+					if match = value.match(PATTERN)
+						path = match[:path]
+						query = match[:query]
+						fragment = match[:fragment]
+						
+						# 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
+						
+						self.new(path, query, fragment, parameters)
+					else
+						raise ArgumentError, "Invalid URL (contains whitespace or control characters): #{value.inspect}"
+					end
+				when Relative
+					self.new(value.path, value.query, value.fragment, parameters)
+				when nil
+					nil
+				else
+					raise ArgumentError, "Cannot coerce #{value.inspect} to Reference!"
+				end
+			end			# Generate a reference from a path and user parameters. The path may contain a `#fragment` or `?query=parameters`.
+			def self.parse(value = "/", parameters = nil)
+				self.[](value, parameters)
 			end
 
 			# Initialize the reference.
@@ -59,18 +80,6 @@ def <=> other
 				to_ary <=> other.to_ary
 			end
 
-			# Type-cast a reference.
-			#
-			# @parameter reference [Reference | String] The reference to type-cast.
-			# @returns [Reference] The type-casted reference.
-			def self.[] reference
-				if reference.is_a? self
-					return reference
-				else
-					return self.parse(reference)
-				end
-			end
-			
 			# @returns [Boolean] Whether the reference has parameters.
 			def parameters?
 				@parameters and !@parameters.empty?
@@ -108,14 +117,22 @@ def fragment?
 			end
 
 			# Append the reference to the given buffer.
-			private def append_query(buffer = String.new)
+			# Encodes the path and fragment which are stored unescaped internally.
+			# Query strings are passed through as-is (they contain = and & which are valid syntax).
+			def append(buffer = String.new)
+				buffer << Encoding.escape_path(@path)
+				
 				if @query and !@query.empty?
 					buffer << "?" << @query
 					buffer << "&" << Encoding.encode(@parameters) if parameters?
 				elsif parameters?
 					buffer << "?" << Encoding.encode(@parameters)
 				end
 
+				if @fragment and !@fragment.empty?
+					buffer << "#" << Encoding.escape_fragment(@fragment)
+				end
+				
 				return buffer
 			end
 
@@ -143,7 +160,7 @@ def base
 			# @parameter fragment [String] Set the fragment to this value.
 			# @parameter pop [Boolean] If the path contains a trailing filename, pop the last component of the path before appending the new path.
 			# @parameter merge [Boolean] If the parameters are specified, merge them with the existing parameters, otherwise replace them (including query string).
-			def with(path: nil, parameters: false, fragment: @fragment, pop: false, merge: true)
+			def with(path: nil, query: @query, fragment: @fragment, parameters: false, pop: false, merge: true)
 				if merge
 					# Merge mode: combine new parameters with existing, keep query:
 					# parameters = (@parameters || {}).merge(parameters || {})
@@ -156,26 +173,18 @@ def with(path: nil, parameters: false, fragment: @fragment, pop: false, merge: t
 					elsif !parameters
 						parameters = @parameters
 					end
-					
-					query = @query
 				else
 					# Replace mode: use new parameters if provided, clear query when replacing:
 					if parameters == false
 						# No new parameters provided, keep existing:
 						parameters = @parameters
-						query = @query
 					else
 						# New parameters provided, replace and clear query:
-						# parameters = parameters
 						query = nil
 					end
 				end
 
-				if path
-					path = Path.expand(@path, path, pop)
-				else
-					path = @path
-				end
+				path = Path.expand(@path, path, pop)
 
 				self.class.new(path, query, fragment, parameters)
 			end

lib/protocol/url/relative.rb

@@ -10,6 +10,8 @@ module Protocol
 	module URL
 		# Represents a relative URL, which does not include a scheme or authority.
 		class Relative
+			include Comparable
+			
 			def initialize(path, query = nil, fragment = nil)
 				@path = path.to_s
 				@query = query
@@ -20,6 +22,16 @@ def initialize(path, query = nil, fragment = nil)
 			attr :query
 			attr :fragment
 
+			# @returns [Boolean] If there is a query string.
+			def query?
+				@query and !@query.empty?
+			end
+			
+			# @returns [Boolean] If there is a fragment.
+			def fragment?
+				@fragment and !@fragment.empty?
+			end
+			
 			# Combine this relative URL with another URL or path.
 			#
 			# @parameter other [String, Absolute, Relative] The URL or path to combine.
@@ -45,26 +57,41 @@ def +(other)
 				end
 			end
 
-			private def append_query(buffer = String.new)
-				if @query and !@query.empty?
-					buffer << "?" << @query
-				end
-				return buffer
+			# Create a new Relative URL with modified components.
+			#
+			# @parameter path [String, nil] The path to merge with the current path.
+			# @parameter query [String, nil] The query string to use.
+			# @parameter fragment [String, nil] The fragment to use.
+			# @parameter pop [Boolean] Whether to pop the last path component before merging.
+			# @returns [Relative] A new Relative URL with the modified components.
+			def with(path: nil, query: @query, fragment: @fragment, pop: true)
+				self.class.new(Path.expand(@path, path, pop), query, fragment)
 			end
 
 			# Append the relative URL to the given buffer.
+			# The path, query, and fragment are expected to already be properly encoded.
 			def append(buffer = String.new)
-				buffer << Encoding.escape_path(@path)
+				buffer << @path
 
-				append_query(buffer)
+				if @query and !@query.empty?
+					buffer << "?" << @query
+				end
 
 				if @fragment and !@fragment.empty?
-					buffer << "#" << Encoding.escape_fragment(@fragment)
+					buffer << "#" << @fragment
 				end
 
 				return buffer
 			end
 
+			def to_ary
+				[@path, @query, @fragment]
+			end
+			
+			def <=>(other)
+				to_ary <=> other.to_ary
+			end
+			
 			def to_s
 				append
 			end

lib/protocol/url/version.rb

@@ -3,7 +3,9 @@
 # Released under the MIT License.
 # Copyright, 2025, by Samuel Williams.
 
+# @namespace
 module Protocol
+	# @namespace
 	module URL
 		VERSION = "0.0.0"
 	end

test/protocol/url.rb

@@ -40,10 +40,22 @@
 			expect(url).to be_equal(relative)
 		end
 
-		it "raises error for invalid input" do
+		it "raises error for invalid input type" do
 			expect do
 				Protocol::URL[123]
 			end.to raise_exception(ArgumentError, message: be =~ /Cannot coerce/)
 		end
+		
+		it "rejects strings with whitespace" do
+			expect do
+				Protocol::URL[" "]
+			end.to raise_exception(ArgumentError, message: be =~ /Invalid URL.*whitespace/)
+		end
+		
+		it "rejects strings with control characters" do
+			expect do
+				Protocol::URL["\r\n"]
+			end.to raise_exception(ArgumentError, message: be =~ /Invalid URL.*control characters/)
+		end
 	end
 end