class Reference

reference = Reference["/search?q=ruby#results"]
reference.path.to_s # => "/search"
reference.query     # => "q=ruby"
reference.fragment  # => "results"

reference = Reference["/search", {"limit" => "10"}]
reference.to_s  # => "/search?limit=10"

relative = Relative.new("/path%20with%20spaces", nil, "top")
reference = Reference[relative]
reference.path.components  # => ["", "path with spaces"]

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 class Protocol::URL::Reference.

def self.[](value, parameters = nil)
	case value
	when String
		if match = value.match(PATTERN)
			path = match[:path]
			query = match[:query]
			fragment = match[:fragment]
			
			# Paths retain their encoded structure while exposing decoded components.
			path = Path[path]
			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
		# Relative stores an encoded path; preserve its component boundaries.
		path = value.path
		fragment = value.fragment
		fragment = Encoding.unescape(fragment) if fragment
		
		self.new(path, value.query, fragment, parameters)
	when nil
		nil
	else
		raise ArgumentError, "Cannot coerce #{value.inspect} to Reference!"
	end
end

reference = Reference.parse("/search?query=ruby#results")
reference.path.to_s # => "/search"
reference.query     # => "query=ruby"
reference.fragment  # => "results"

def self.parse(value = "/", parameters = nil)
	self.[](value, parameters)
end

reference = Reference.new("/search", nil, nil, {"query" => "ruby", "limit" => "10"})
reference.to_s  # => "/search?query=ruby&limit=10"

parameter　path　String | Path

The encoded path string, or an existing path.

parameter　query　String | Nil

An already-formatted query string.

parameter　fragment　String | Nil

The unescaped fragment.

parameter　parameters　Hash | Nil

User supplied parameters that will be safely encoded.

def initialize(path = "/", query = nil, fragment = nil, parameters = nil)
	super(path, query, fragment)
	@parameters = parameters
end

attribute　Hash | Nil

User supplied parameters that will be appended to the query part.

returns　Reference

The frozen reference.

def freeze
	return self if frozen?
	
	@parameters.freeze
	
	super
end

returns　Array

The reference as an array, [path, query, fragment, parameters].

def to_ary
	[@path, @query, @fragment, @parameters]
end

returns　Boolean

Whether the reference has parameters.

def parameters?
	@parameters and !@parameters.empty?
end

returns　Hash

The merged parameters.

def parse_query!(encoding = Encoding)
	if @query and !@query.empty?
		parsed = encoding.decode(@query)
		
		if @parameters
			@parameters = @parameters.merge(parsed)
		else
			@parameters = parsed
		end
		
		@query = nil
	end
	
	return @parameters
end

returns　Boolean

Whether the reference has a query string.

def query?
	@query and !@query.empty?
end

returns　Boolean

Whether the reference has a fragment.

def fragment?
	@fragment and !@fragment.empty?
end

parameter　explicit　Boolean

Whether the result should be lexically identifiable as a URL in a mixed grammar.

def append(buffer = String.new, explicit: false)
	append_path(buffer, explicit: explicit)
	
	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

def + other
	other = self.class[other]
	
	self.class.new(
		@path.join(other.path),
		other.query,
		other.fragment,
		other.parameters,
	)
end

def base
	self.class.new(@path, nil, nil, nil)
end

reference = Reference.new("/search", nil, nil, {"query" => "ruby"})
updated = reference.with(parameters: {"limit" => "10"})
updated.to_s  # => "/search?query=ruby&limit=10"

reference = Reference.new("/search", nil, nil, {"query" => "ruby"})
updated = reference.with(parameters: {"query" => "python"}, merge: false)
updated.to_s  # => "/search?query=python"

parameter　path　String | Path

Append the encoded path to this reference similar to File.join.

parameter　query　String | Nil

Replace the query string. Defaults to keeping the existing query if not specified.

parameter　fragment　String | Nil

Replace the fragment. Defaults to keeping the existing fragment if not specified.

parameter　parameters　Hash | false

Parameters to merge or replace. Pass false (default) to keep existing parameters.

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

Controls how parameters are handled. When true (default), new parameters are merged with existing ones and query is kept. When false and new parameters are provided, parameters replace existing ones and query is cleared. Explicitly passing query: always overrides this behavior.

def with(path: nil, query: false, fragment: @fragment, parameters: false, pop: false, merge: true)
	if merge
		# If merging, we keep existing query unless explicitly overridden:
		if query == false
			query = @query
		end
		
		# Merge mode: combine new parameters with existing, keep query:
		# parameters = (@parameters || {}).merge(parameters || {})
		if @parameters
			if parameters
				parameters = @parameters.merge(parameters)
			else
				parameters = @parameters
			end
		elsif !parameters
			parameters = @parameters
		end
	else
		# Replace mode: use new parameters if provided, clear query when replacing:
		if parameters == false
			# No new parameters provided, keep existing:
			parameters = @parameters
			
			# Also keep query if not explicitly specified:
			if query == false
				query = @query
			end
		else
			# New parameters provided, clear query unless explicitly specified:
			if query == false
				query = nil
			end
		end
	end
	
	if path.nil?
		path = @path
	else
		path = @path.join(path, pop: pop)
	end
	
	self.class.new(path, query, fragment, parameters)
end