100% code and documentation coverage.

Author: ioquatix

guides/getting-started/readme.md

@@ -149,6 +149,27 @@ Protocol::URL::Path.expand("/a/b/file.html", "other.html", false)
 # => "/a/b/file.html/other.html"
 ```
 
+### Converting to Local File System Paths
+
+Convert URL paths to local file system paths safely:
+
+``` ruby
+# Convert URL path to local file system path:
+Protocol::URL::Path.to_local_path("/documents/report.pdf")
+# => "/documents/report.pdf"
+
+# Handles percent-encoded characters:
+Protocol::URL::Path.to_local_path("/files/My%20Document.txt")
+# => "/files/My Document.txt"
+
+# Security: Preserves percent-encoded path separators
+# This prevents directory traversal attacks:
+Protocol::URL::Path.to_local_path("/folder/safe%2Fname/file.txt")
+# => "/folder/safe%2Fname/file.txt"
+# %2F (/) and %5C (\) are NOT decoded, preventing them from creating
+# additional path components in the file system
+```
+
 ## Working with References
 
 {ruby Protocol::URL::Reference} extends relative URLs with query parameters and fragments. For detailed information on working with references, see the [Working with References](../working-with-references/) guide.

guides/working-with-references/readme.md

@@ -10,7 +10,21 @@ This guide explains how to use {ruby Protocol::URL::Reference} for managing URLs
 
 You can create references in several ways:
 
-### Constructing from Components
+### Parsing External URLs (Untrusted Data)
+
+Use {ruby Protocol::URL.parse} or {ruby Protocol::URL.[]} to parse URL strings from external sources (user input, APIs, web pages). These methods validate and decode the input:
+
+``` ruby
+# Parse a reference with query and fragment:
+reference = Protocol::URL["/api/users?active=true&role=admin#list"]
+reference.path      # => "/api/users"
+reference.query     # => "active=true&role=admin"
+reference.fragment  # => "list"
+```
+
+### Constructing from Known Values (Trusted Data)
+
+Use {ruby Protocol::URL::Reference.new} when you have known good values from your code. This method doesn't validate and expects unencoded values:
 
 ``` ruby
 require "protocol/url"
@@ -23,25 +37,58 @@ reference.to_s  # => "/api/users"
 reference = Protocol::URL::Reference.new("/search", "q=ruby&page=2")
 reference.to_s  # => "/search?q=ruby&page=2"
 
-# Reference with fragment:
-reference = Protocol::URL::Reference.new("/docs", nil, "section-3")
-reference.to_s  # => "/docs#section-3"
-
 # Reference with all components:
 reference = Protocol::URL::Reference.new("/api/users", "status=active", "results")
 reference.to_s  # => "/api/users?status=active#results"
+
+# Using parameters (recommended for query strings):
+reference = Protocol::URL::Reference.new("/search", nil, nil, {q: "ruby", page: 2})
+reference.to_s  # => "/search?q=ruby&page=2"
 ```
 
-### Parsing from Strings
+## Understanding Encoding
+
+References use different encoding strategies depending on how they're constructed:
+
+### With parse() - Decodes Input
 
-Use {ruby Protocol::URL.[]} to parse complete URL strings:
+`parse()` expects already-encoded URLs and decodes them for internal storage:
 
 ``` ruby
-# Parse a reference with query and fragment:
-reference = Protocol::URL["/api/users?active=true&role=admin#list"]
-reference.path      # => "/api/users"
-reference.query     # => "active=true&role=admin"
-reference.fragment  # => "list"
+ref = Protocol::URL::Reference.parse("path%20with%20spaces?foo=bar#frag%20ment")
+ref.path      # => "path with spaces" (decoded)
+ref.fragment  # => "frag ment" (decoded)
+ref.to_s      # => "path%20with%20spaces?foo=bar#frag%20ment" (re-encoded)
+```
+
+### With new() - Expects Unencoded Input
+
+`new()` expects raw, unencoded values and encodes them during output:
+
+``` ruby
+ref = Protocol::URL::Reference.new("path with spaces", "foo=bar", "frag ment")
+ref.path      # => "path with spaces"
+ref.fragment  # => "frag ment"
+ref.to_s      # => "path%20with%20spaces?foo=bar#frag%20ment"
+```
+
+**Warning**: Passing encoded values to `new()` causes double-encoding:
+
+``` ruby
+# Wrong - will double-encode:
+ref = Protocol::URL::Reference.new("path%20with%20spaces")
+ref.to_s  # => "path%2520with%2520spaces" (double-encoded!)
+
+# Correct - use parse() for encoded input:
+ref = Protocol::URL::Reference.parse("path%20with%20spaces")
+ref.to_s  # => "path%20with%20spaces"
+```
+
+Unicode and special characters are handled automatically:
+
+``` ruby
+ref = Protocol::URL::Reference.new("I/❤️/UNICODE")
+ref.to_s  # => "I/%E2%9D%A4%EF%B8%8F/UNICODE"
 ```
 
 ## Accessing Components
@@ -227,6 +274,22 @@ result.to_s  # => "/search?q=ruby&lang=en#result-5"
 - Use {ruby Protocol::URL::Relative} for simple path-only URLs
 - Use {ruby Protocol::URL::Absolute} for complete URLs with scheme and host
 
+### parse() vs new()
+
+Choose the right method based on your data source:
+
+- **Use `parse()` or `[]`** for external/untrusted data (user input, URLs from web pages, API responses). These methods validate and decode the URL.
+- **Use `new()`** for known good values from your code. This is more efficient since it skips validation and expects unencoded values.
+
+``` ruby
+# External data - use parse():
+user_input = "/search?q=ruby%20gems"
+reference = Protocol::URL[user_input]  # Validates and decodes
+
+# Internal data - use new():
+reference = Protocol::URL::Reference.new("/api/users", "status=active")  # Direct construction
+```
+
 ### Query String Management
 
 The library provides built-in parameter handling through the `parameters` attribute:

lib/protocol/url/absolute.rb

@@ -33,6 +33,18 @@ def authority?
 			#
 			# @parameter other [String, Relative, Reference, Absolute] The reference to resolve.
 			# @returns [Absolute, String] The resolved absolute URL.
+			#
+			# @example Resolve a relative path.
+			# 	base = Absolute.new("https", "example.com", "/documents/reports/")
+			# 	relative = Relative.new("summary.pdf")
+			# 	result = base + relative
+			# 	result.to_s  # => "https://example.com/documents/reports/summary.pdf"
+			#
+			# @example Navigate to parent directory.
+			# 	base = Absolute.new("https", "example.com", "/documents/reports/2024/")
+			# 	relative = Relative.new("../../archive/")
+			# 	result = base + relative
+			# 	result.to_s  # => "https://example.com/documents/archive/"
 			def +(other)
 				case other
 				when Absolute
@@ -92,6 +104,16 @@ def append(buffer = String.new)
 			# @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.
+			#
+			# @example Change the scheme.
+			# 	url = Absolute.new("http", "example.com", "/page")
+			# 	secure = url.with(scheme: "https")
+			# 	secure.to_s  # => "https://example.com/page"
+			#
+			# @example Update the query string.
+			# 	url = Absolute.new("https", "example.com", "/search", "query=ruby")
+			# 	updated = url.with(query: "query=python")
+			# 	updated.to_s  # => "https://example.com/search?query=python"
 			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

lib/protocol/url/encoding.rb

@@ -11,6 +11,14 @@ module Encoding
 			#
 			# @parameter string [String] The string to escape.
 			# @returns [String] The escaped string.
+			#
+			# @example Escape spaces and special characters.
+			# 	Encoding.escape("hello world!")
+			# 	# => "hello%20world%21"
+			#
+			# @example Escape unicode characters.
+			# 	Encoding.escape("café")
+			# 	# => "caf%C3%A9"
 			def self.escape(string, encoding = string.encoding)
 				string.b.gsub(/([^a-zA-Z0-9_.\-]+)/) do |m|
 					"%" + m.unpack("H2" * m.bytesize).join("%").upcase
@@ -21,12 +29,48 @@ def self.escape(string, encoding = string.encoding)
 			#
 			# @parameter string [String] The string to unescape.
 			# @returns [String] The unescaped string.
+			#
+			# @example Unescape spaces and special characters.
+			# 	Encoding.unescape("hello%20world%21")
+			# 	# => "hello world!"
+			#
+			# @example Unescape unicode characters.
+			# 	Encoding.unescape("caf%C3%A9")
+			# 	# => "café"
 			def self.unescape(string, encoding = string.encoding)
 				string.b.gsub(/%(\h\h)/) do |hex|
 					Integer($1, 16).chr
 				end.force_encoding(encoding)
 			end
 
+			# Unescapes a percent encoded path component, preserving encoded path separators.
+			#
+			# This method unescapes percent-encoded characters except for path separators
+			# (forward slash `/` and backslash `\`). This prevents encoded separators like
+			# `%2F` or `%5C` from being decoded into actual path separators, which could
+			# allow bypassing path component boundaries.
+			#
+			# @parameter string [String] The path component to unescape.
+			# @returns [String] The unescaped string with separators still encoded.
+			#
+			# @example
+			#   Encoding.unescape_path("hello%20world")     # => "hello world"
+			#   Encoding.unescape_path("safe%2Fname")       # => "safe%2Fname" (%2F not decoded)
+			#   Encoding.unescape_path("name%5Cfile")       # => "name%5Cfile" (%5C not decoded)
+			def self.unescape_path(string, encoding = string.encoding)
+				string.b.gsub(/%(\h\h)/) do |hex|
+					byte = Integer($1, 16)
+					char = byte.chr
+					
+					# Don't decode forward slash (0x2F) or backslash (0x5C)
+					if byte == 0x2F || byte == 0x5C
+						hex  # Keep as %2F or %5C
+					else
+						char
+					end
+				end.force_encoding(encoding)
+			end
+			
 			# Matches characters that are not allowed in a URI path segment. According to RFC 3986 Section 3.3 (https://tools.ietf.org/html/rfc3986#section-3.3), a valid path segment consists of "pchar" characters. This pattern identifies characters that must be percent-encoded when included in a URI path segment.
 			NON_PATH_CHARACTER_PATTERN = /([^a-zA-Z0-9_\-\.~!$&'()*+,;=:@\/]+)/.freeze
 
@@ -37,6 +81,10 @@ def self.unescape(string, encoding = string.encoding)
 			#
 			# @parameter path [String] The path to escape.
 			# @returns [String] The escaped path.
+			#
+			# @example Escape spaces while preserving path separators.
+			# 	Encoding.escape_path("/documents/my reports/summary.pdf")
+			# 	# => "/documents/my%20reports/summary.pdf"
 			def self.escape_path(path)
 				encoding = path.encoding
 				path.b.gsub(NON_PATH_CHARACTER_PATTERN) do |m|
@@ -59,6 +107,14 @@ def self.escape_fragment(fragment)
 			#
 			# @parameter value [Hash | Array | Nil] The value to encode.
 			# @parameter prefix [String] The prefix to use for keys.
+			#
+			# @example Encode simple parameters.
+			# 	Encoding.encode({"name" => "Alice", "age" => "30"})
+			# 	# => "name=Alice&age=30"
+			#
+			# @example Encode nested parameters.
+			# 	Encoding.encode({"user" => {"name" => "Alice", "role" => "admin"}})
+			# 	# => "user[name]=Alice&user[role]=admin"
 			def self.encode(value, prefix = nil)
 				case value
 				when Array
@@ -105,21 +161,33 @@ def self.split(name)
 
 			# Assign a value to a nested hash.
 			#
+			# This method handles building nested data structures from query string parameters, including arrays of objects. When processing array elements (empty key like `[]`), it intelligently decides whether to add to the last array element or create a new one.
+			#
 			# @parameter keys [Array(String)] The parts of the key.
 			# @parameter value [Object] The value to assign.
 			# @parameter parent [Hash] The parent hash.
+			#
+			# @example Building an array of objects.
+			# 	# Query: items[][name]=a&items[][value]=1&items[][name]=b&items[][value]=2
+			# 	# When "name" appears again, it creates a new array element
+			# 	# Result: {"items" => [{"name" => "a", "value" => "1"}, {"name" => "b", "value" => "2"}]}
 			def self.assign(keys, value, parent)
 				top, *middle = keys
 
 				middle.each_with_index do |key, index|
 					if key.nil? or key.empty?
+						# Array element (e.g., items[]):
 						parent = (parent[top] ||= Array.new)
 						top = parent.size
 
+						# Check if we should reuse the last array element or create a new one. If there's a nested key coming next, and the last array element already has that key, then we need a new array element. Otherwise, add to the existing one.
 						if nested = middle[index+1] and last = parent.last
+							# If the last element doesn't include the nested key, reuse it (decrement index).
+							# If it does include the key, keep current index (creates new element).
 							top -= 1 unless last.include?(nested)
 						end
 					else
+						# Hash key (e.g., user[name]):
 						parent = (parent[top] ||= Hash.new)
 						top = key
 					end
@@ -134,6 +202,14 @@ def self.assign(keys, value, parent)
 			# @parameter maximum [Integer] The maximum number of keys in a path.
 			# @parameter symbolize_keys [Boolean] Whether to symbolize keys.
 			# @returns [Hash] The decoded query string.
+			#
+			# @example Decode simple parameters.
+			# 	Encoding.decode("name=Alice&age=30")
+			# 	# => {"name" => "Alice", "age" => "30"}
+			#
+			# @example Decode nested parameters.
+			# 	Encoding.decode("user[name]=Alice&user[role]=admin")
+			# 	# => {"user" => {"name" => "Alice", "role" => "admin"}}
 			def self.decode(string, maximum = 8, symbolize_keys: false)
 				parameters = {}