Class: Protocol::HTTP::Reference

Inherits:
Object
  • Object
show all
Includes:
Comparable
Defined in:
lib/protocol/http/reference.rb

Overview

A relative reference, excluding any authority. The path part of an HTTP request.

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(path = '/', query_string = nil, fragment = nil, parameters = nil) ⇒ Reference

Returns a new instance of Reference.



39
40
41
42
43
44
# File 'lib/protocol/http/reference.rb', line 39

def initialize(path = '/', query_string = nil, fragment = nil, parameters = nil)
	@path = path
	@query_string = query_string
	@fragment = fragment
	@parameters = parameters
end

Instance Attribute Details

#fragmentObject

A fragment, the part after the ‘#’



53
54
55
# File 'lib/protocol/http/reference.rb', line 53

def fragment
  @fragment
end

#parametersObject

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



56
57
58
# File 'lib/protocol/http/reference.rb', line 56

def parameters
  @parameters
end

#pathObject

The path component, e.g. /foo/bar/index.html



47
48
49
# File 'lib/protocol/http/reference.rb', line 47

def path
  @path
end

#query_stringObject

The un-parsed query string, e.g. ‘x=10&y=20’



50
51
52
# File 'lib/protocol/http/reference.rb', line 50

def query_string
  @query_string
end

Class Method Details

.[](reference) ⇒ Object



77
78
79
80
81
82
83
# File 'lib/protocol/http/reference.rb', line 77

def self.[] reference
	if reference.is_a? self
		return reference
	else
		return self.parse(reference)
	end
end

.parse(path = '/', parameters = nil) ⇒ Object

Generate a reference from a path and user parameters. The path may contain a ‘#fragment` or `?query=parameters`.



32
33
34
35
36
37
# File 'lib/protocol/http/reference.rb', line 32

def self.parse(path = '/', parameters = nil)
	base, fragment = path.split('#', 2)
	path, query_string = base.split('?', 2)
	
	self.new(path, query_string, fragment, parameters)
end

Instance Method Details

#+(other) ⇒ Object

Merges two references as specified by RFC2396, similar to ‘URI.join`.



120
121
122
123
124
125
126
127
128
129
# File 'lib/protocol/http/reference.rb', line 120

def + other
	other = self.class[other]
	
	self.class.new(
		expand_path(self.path, other.path, true),
		other.query_string,
		other.fragment,
		other.parameters,
	)
end

#<=>(other) ⇒ Object



73
74
75
# File 'lib/protocol/http/reference.rb', line 73

def <=> other
	to_ary <=> other.to_ary
end

#append(buffer) ⇒ Object



97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
# File 'lib/protocol/http/reference.rb', line 97

def append(buffer)
	if query_string?
		buffer << URL.escape_path(@path) << '?' << @query_string
		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

#baseObject

Just the base path, without any query string, parameters or fragment.



132
133
134
# File 'lib/protocol/http/reference.rb', line 132

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

#dup(path = nil, parameters = nil, merge_parameters = true) ⇒ Object

The arguments to this function are legacy, prefer to use ‘with`.



158
159
160
161
162
163
164
# File 'lib/protocol/http/reference.rb', line 158

def dup(path = nil, parameters = nil, merge_parameters = true)
	if merge_parameters
		with(path: path, parameters: parameters)
	else
		self.base.with(path: path, parameters: parameters)
	end
end

#fragment?Boolean

Returns:

  • (Boolean)


93
94
95
# File 'lib/protocol/http/reference.rb', line 93

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

#freezeObject



58
59
60
61
62
63
64
65
66
67
# File 'lib/protocol/http/reference.rb', line 58

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

#parameters?Boolean

Returns:

  • (Boolean)


85
86
87
# File 'lib/protocol/http/reference.rb', line 85

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

#query_string?Boolean

Returns:

  • (Boolean)


89
90
91
# File 'lib/protocol/http/reference.rb', line 89

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

#to_aryObject



69
70
71
# File 'lib/protocol/http/reference.rb', line 69

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

#to_strObject Also known as: to_s



113
114
115
# File 'lib/protocol/http/reference.rb', line 113

def to_str
	append(String.new)
end

#with(path: nil, parameters: nil, fragment: @fragment) ⇒ Object

Parameters:

  • path (Hash) (defaults to: nil)

    a customizable set of options

  • parameters (Hash) (defaults to: nil)

    a customizable set of options

  • fragment (Hash) (defaults to: @fragment)

    a customizable set of options

Options Hash (path:):

  • Append (String)

    the string to this reference similar to ‘File.join`.

Options Hash (parameters:):

  • Append (Hash)

    the parameters to this reference.

Options Hash (fragment:):

  • Set (String)

    the fragment to this value.



139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
# File 'lib/protocol/http/reference.rb', line 139

def with(path: nil, parameters: nil, fragment: @fragment)
	if @parameters
		if parameters
			parameters = @parameters.merge(parameters)
		else
			parameters = @parameters
		end
	end
	
	if path
		path = expand_path(@path, path, false)
	else
		path = @path
	end
	
	self.class.new(path, @query_string, fragment, parameters)
end