# frozen_string_literal: true

# Released under the MIT License.
# Copyright, 2018-2025, by Samuel Williams.

require_relative "url"

module Protocol
	module HTTP
		# A relative reference, excluding any authority. The path part of an HTTP request.
		class Reference
			include Comparable
			
			# Generate a reference from a path and user parameters. The path may contain a `#fragment` or `?query=parameters`.
			def self.parse(path = "/", parameters = nil)
				base, fragment = path.split("#", 2)
				path, query = base.split("?", 2)
				
				self.new(path, query, fragment, parameters)
			end
			
			# Initialize the reference.
			#
			# @parameter path [String] The path component, e.g. `/foo/bar/index.html`.
			# @parameter query [String | Nil] The un-parsed query string, e.g. 'x=10&y=20'.
			# @parameter fragment [String | Nil] The fragment, the part after the '#'.
			# @parameter parameters [Hash | Nil] User supplied parameters that will be appended to the query part.
			def initialize(path = "/", query = nil, fragment = nil, parameters = nil)
				@path = path
				@query = query
				@fragment = fragment
				@parameters = parameters
			end
			
			# @attribute [String] The path component, e.g. `/foo/bar/index.html`.
			attr_accessor :path
			
			# @attribute [String] The un-parsed query string, e.g. 'x=10&y=20'.
			attr_accessor :query
			
			# @attribute [String] The fragment, the part after the '#'.
			attr_accessor :fragment
			
			# @attribute [Hash] User supplied parameters that will be appended to the query part.
			attr_accessor :parameters
			
			# Freeze the reference.
			#
			#	@returns [Reference] The frozen reference.
			def freeze
				return self if frozen?
				
				@path.freeze
				@query.freeze
				@fragment.freeze
				@parameters.freeze
				
				super
			end
			
			# Implicit conversion to an array.
			#
			# @returns [Array] The reference as an array, `[path, query, fragment, parameters]`.
			def to_ary
				[@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
			
			# 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?
			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
			
			# Append the reference to the given buffer.
			def append(buffer = String.new)
				if query?
					buffer << URL.escape_path(@path) << "?" << @query
					buffer << "&" << URL.encode(@parameters) if parameters?
				else
					buffer << URL.escape_path(@path)
					buffer << "?" << URL.encode(@parameters) if parameters?
				end
				
				if fragment?
					buffer << "#" << URL.escape(@fragment)
				end
				
				return buffer
			end
			
			# Convert the reference to a string, e.g. `/foo/bar/index.html?x=10&y=20#section`
			#
			# @returns [String] The reference as a string.
			def to_s
				append
			end
			
			# Merges two references as specified by RFC2396, similar to `URI.join`.
			def + other
				other = self.class[other]
				
				self.class.new(
					expand_path(self.path, other.path, true),
					other.query,
					other.fragment,
					other.parameters,
				)
			end
			
			# Just the base path, without any query string, parameters or fragment.
			def base
				self.class.new(@path, nil, nil, nil)
			end
			
			# Update the reference with the given path, parameters and fragment.
			# @argument path [String] Append the string to this reference similar to `File.join`.
			# @argument parameters [Hash] Append the parameters to this reference.
			# @argument fragment [String] Set the fragment to this value.
			# @argument pop [Boolean] If the path contains a trailing filename, pop the last component of the path before appending the new path.
			# @argument merge [Boolean] If the parameters are specified, merge them with the existing parameters.
			def with(path: nil, parameters: nil, fragment: @fragment, pop: false, merge: true)
				if @parameters
					if parameters and merge
						parameters = @parameters.merge(parameters)
					else
						parameters = @parameters
					end
				end
				
				if @query and !merge
					query = nil
				else
					query = @query
				end
				
				if path
					path = expand_path(@path, path, pop)
				else
					path = @path
				end
				
				self.class.new(path, query, fragment, parameters)
			end
			
			private
			
			def split(path)
				if path.empty?
					[path]
				else
					path.split("/", -1)
				end
			end
			
			def expand_absolute_path(path, parts)
				parts.each do |part|
					if part == ".."
						path.pop
					elsif part == "."
						# Do nothing.
					else
						path << part
					end
				end
				
				if path.first != ""
					path.unshift("")
				end
			end
			
			def expand_relative_path(path, parts)
				parts.each do |part|
					if part == ".." and path.any?
						path.pop
					elsif part == "."
						# Do nothing.
					else
						path << part
					end
				end
			end
			
			# @param pop [Boolean] whether to remove the last path component of the base path, to conform to URI merging behaviour, as defined by RFC2396.
			def expand_path(base, relative, pop = true)
				if relative.start_with? "/"
					return relative
				end
				
				path = split(base)
				
				# RFC2396 Section 5.2:
				# 6) a) All but the last segment of the base URI's path component is
				# copied to the buffer.  In other words, any characters after the
				# last (right-most) slash character, if any, are excluded.
				path.pop if pop or path.last == ""
				
				parts = split(relative)
				
				# Absolute path:
				if path.first == ""
					expand_absolute_path(path, parts)
				else
					expand_relative_path(path, parts)
				end	
				
				return path.join("/")
			end
		end
	end
end
