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 (yegor256@gmail.com)

Copyright

Copyright © 2019-2025 Yegor Bugayenko

License

MIT

Defined Under Namespace

Classes: InvalidArguments, InvalidURI

Instance Method Summary collapse

Constructor Details

#initialize(uri = '', local: false, 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.

Parameters:

  • uri (String) (defaults to: '') —

    URI

  • local (Boolean) (defaults to: false) —

    Is it local (no host, port, and scheme)?

  • safe (Boolean) (defaults to: true) —

    Should it safe?

[View source] [View on GitHub]

46
47
48
49
50
 
# File 'lib/iri.rb', line 46

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

Instance Method Details

#add(hash) ⇒ Iri

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')

Parameters:

  • hash (Hash) —

    Hash of names/values to set into the query part

Returns:

  • (Iri) —

    A new iri

Raises:

[View source] [View on GitHub]

105
106
107
108
109
110
111
112
113
 
# File 'lib/iri.rb', line 105

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) ⇒ Iri

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”.

Parameters:

  • part (String) —

    New segment to add to existing path

Returns:

  • (Iri) —

    A new iri

[View source] [View on GitHub]

235
236
237
238
239
240
 
# File 'lib/iri.rb', line 235

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 = '/') ⇒ Iri

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”.

Parameters:

  • path (String) (defaults to: '/') —

    New path to set, like “/foo”

Returns:

  • (Iri) —

    A new iri

[View source] [View on GitHub]

217
218
219
220
221
222
223
 
# File 'lib/iri.rb', line 217

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

#del(*keys) ⇒ Iri

Delete a few query arguments.

For example:

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

Parameters:

  • keys (Array) —

    List of keys to delete

Returns:

  • (Iri) —

    A new iri

[View source] [View on GitHub]

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

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

#fragment(val) ⇒ Iri

Replace the fragment part of the URI.

Parameters:

  • val (String) —

    New fragment to set, like “hello”

Returns:

  • (Iri) —

    A new iri

[View source] [View on GitHub]

191
192
193
194
195
 
# File 'lib/iri.rb', line 191

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

#host(val) ⇒ Iri

Replace the host.

Parameters:

  • val (String) —

    New host to set, like “google.com” or “192.168.0.1”

Returns:

  • (Iri) —

    A new iri

[View source] [View on GitHub]

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

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

#inspect ⇒ String

Inspect it, like a string can be inspected.

Returns:

  • (String) —

    Details of it

[View source] [View on GitHub]

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

def inspect
  @uri.to_s.inspect
end

#over(hash) ⇒ Iri

Replace query argument(s).

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

Parameters:

  • hash (Hash) —

    Hash of names/values to set into the query part

Returns:

  • (Iri) —

    A new iri

Raises:

[View source] [View on GitHub]

137
138
139
140
141
142
143
144
145
 
# File 'lib/iri.rb', line 137

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) ⇒ Iri

Replace the path part of the URI.

Parameters:

  • val (String) —

    New path to set, like “/foo/bar”

Returns:

  • (Iri) —

    A new iri

[View source] [View on GitHub]

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

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

#port(val) ⇒ Iri

Replace the port.

Parameters:

  • val (String) —

    New TCP port to set, like “8080” or “443”

Returns:

  • (Iri) —

    A new iri

[View source] [View on GitHub]

171
172
173
174
175
 
# File 'lib/iri.rb', line 171

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

#query(val) ⇒ Iri

Replace the query part of the URI.

Parameters:

  • val (String) —

    New query to set, like “a=1&b=2”

Returns:

  • (Iri) —

    A new iri

[View source] [View on GitHub]

201
202
203
204
205
 
# File 'lib/iri.rb', line 201

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

#scheme(val) ⇒ Iri

Replace the scheme.

Parameters:

  • val (String) —

    New scheme to set, like “https” or “http”

Returns:

  • (Iri) —

    A new iri

[View source] [View on GitHub]

151
152
153
154
155
 
# File 'lib/iri.rb', line 151

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

#to_local ⇒ Iri

Removes the host, the port, and the scheme and returns only the local address, for example, converting “google.com/foo” into “/foo”.

Returns:

  • (Iri) —

    Iri with no host/port/scheme

[View source] [View on GitHub]

87
88
89
 
# File 'lib/iri.rb', line 87

def to_local
  Iri.new(@uri, local: true, safe: @safe)
end

#to_s ⇒ String

Convert it to a string.

Returns:

  • (String) —

    New URI

[View source] [View on GitHub]

55
56
57
58
59
60
61
62
63
64
65
66
 
# File 'lib/iri.rb', line 55

def to_s
  u = the_uri
  if @local
    [
      u.path,
      u.query ? "?#{u.query}" : '',
      u.fragment ? "##{u.fragment}" : ''
    ].join
  else
    u.to_s
  end
end

#to_uri ⇒ String

Convert it to an object of class URI.

Returns:

  • (String) —

    New URI

[View source] [View on GitHub]

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

def to_uri
  the_uri.clone
end