Class: Iri

Inherits:
Object
  • Object
show all
Defined in:
lib/iri.rb

Overview

It is a simple URI builder.

require 'iri'
url = Iri.new('http://google.com/')
  .add(q: 'books about OOP', limit: 50)
  .del(:q) // remove this query parameter
  .del('limit') // remove this one too
  .over(q: 'books about tennis', limit: 10) // replace these params
  .scheme('https')
  .host('localhost')
  .port('443')
  .to_s

For more information read README file.

Author

Yegor Bugayenko ([email protected])

Copyright

Copyright © 2019-2024 Yegor Bugayenko

License

MIT

Defined Under Namespace

Classes: InvalidArguments, InvalidURI

Instance Method Summary collapse

Constructor Details

#initialize(uri = '', safe: true) ⇒ Iri

Makes a new object.

You can even ignore the argument, which will produce an empty URI.

By default, this class will never throw any exceptions, even if your URI is not valid. It will just assume that the URI is“/”. However, you can turn this mode off, by specifying safe as FALSE.



61
62
63
64
# File 'lib/iri.rb', line 61

def initialize(uri = '', safe: true)
  @uri = uri
  @safe = safe
end

Instance Method Details

#add(hash) ⇒ Object

Add a few query arguments.

For example:

Iri.new('https://google.com').add(q: 'test', limit: 10)

You can add many of them and they will all be present in the resulting URI, even if their names are the same. In order to make sure you have only one instance of a query argument, use del first:

Iri.new('https://google.com').del(:q).add(q: 'test')

Raises:



93
94
95
96
97
98
99
100
101
# File 'lib/iri.rb', line 93

def add(hash)
  raise InvalidArguments unless hash.is_a?(Hash)
  modify_query do |params|
    hash.each do |k, v|
      params[k.to_s] = [] unless params[k.to_s]
      params[k.to_s] << v
    end
  end
end

#append(part) ⇒ Object

Append something new to the path.

For example:

Iri.new('https://google.com/a/b?q=test').append('/hello')

The result will contain “google.com/a/b/hello?q=test”.



195
196
197
198
199
200
# File 'lib/iri.rb', line 195

def append(part)
  modify do |c|
    tail = (c.path.end_with?('/') ? '' : '/') + CGI.escape(part.to_s)
    c.path = c.path + tail
  end
end

#cut(path = '/') ⇒ Object

Remove the entire path+query+fragment part.

For example:

Iri.new('https://google.com/a/b?q=test').cut('/hello')

The result will contain “google.com/hello”.



180
181
182
183
184
185
186
# File 'lib/iri.rb', line 180

def cut(path = '/')
  modify do |c|
    c.query = nil
    c.path = path
    c.fragment = nil
  end
end

#del(*keys) ⇒ Object

Delete a few query arguments.

For example:

Iri.new('https://google.com?q=test').del(:q)


109
110
111
112
113
114
115
# File 'lib/iri.rb', line 109

def del(*keys)
  modify_query do |params|
    keys.each do |k|
      params.delete(k.to_s)
    end
  end
end

#fragment(val) ⇒ Object

Replace the fragment part of the URI.



160
161
162
163
164
# File 'lib/iri.rb', line 160

def fragment(val)
  modify do |c|
    c.fragment = val.to_s
  end
end

#host(val) ⇒ Object

Replace the host.



139
140
141
142
143
# File 'lib/iri.rb', line 139

def host(val)
  modify do |c|
    c.host = val
  end
end

#inspectObject

Inspect it, like a string can be inspected.



72
73
74
# File 'lib/iri.rb', line 72

def inspect
  @uri.to_s.inspect
end

#over(hash) ⇒ Object

Replace query argument(s).

Iri.new('https://google.com?q=test').over(q: 'hey you!')

Raises:



121
122
123
124
125
126
127
128
129
# File 'lib/iri.rb', line 121

def over(hash)
  raise InvalidArguments unless hash.is_a?(Hash)
  modify_query do |params|
    hash.each do |k, v|
      params[k.to_s] = [] unless params[k]
      params[k.to_s] = [v]
    end
  end
end

#path(val) ⇒ Object

Replace the path part of the URI.



153
154
155
156
157
# File 'lib/iri.rb', line 153

def path(val)
  modify do |c|
    c.path = val
  end
end

#port(val) ⇒ Object

Replace the port.



146
147
148
149
150
# File 'lib/iri.rb', line 146

def port(val)
  modify do |c|
    c.port = val
  end
end

#query(val) ⇒ Object

Replace the query part of the URI.



167
168
169
170
171
# File 'lib/iri.rb', line 167

def query(val)
  modify do |c|
    c.query = val
  end
end

#scheme(val) ⇒ Object

Replace the scheme.



132
133
134
135
136
# File 'lib/iri.rb', line 132

def scheme(val)
  modify do |c|
    c.scheme = val
  end
end

#to_sObject

Convert it to a string.



67
68
69
# File 'lib/iri.rb', line 67

def to_s
  @uri.to_s
end

#to_uriObject

Convert it to an object of class URI.



77
78
79
# File 'lib/iri.rb', line 77

def to_uri
  the_uri.clone
end