class Iri

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-2021 Yegor Bugayenko
License: MIT

Public Class Methods

new(uri = '', safe: true) click to toggle source

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.

# File lib/iri.rb, line 58
def initialize(uri = '', safe: true)
  @uri = uri
  @safe = safe
end

Public Instance Methods

add(hash) click to toggle source

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

# File lib/iri.rb, line 85
def add(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) click to toggle source

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

# File lib/iri.rb, line 185
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 = '/') click to toggle source

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

# File lib/iri.rb, line 170
def cut(path = '/')
  modify do |c|
    c.query = nil
    c.path = path
    c.fragment = nil
  end
end

del(*keys) click to toggle source

Delete a few query arguments.

For example:

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

# File lib/iri.rb, line 100
def del(*keys)
  modify_query do |params|
    keys.each do |k|
      params.delete(k.to_s)
    end
  end
end

fragment(val) click to toggle source

Replace the fragment part of the URI.

# File lib/iri.rb, line 150
def fragment(val)
  modify do |c|
    c.fragment = val.to_s
  end
end

host(val) click to toggle source

Replace the host.

# File lib/iri.rb, line 129
def host(val)
  modify do |c|
    c.host = val
  end
end

over(hash) click to toggle source

Replace query argument(s).

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

# File lib/iri.rb, line 112
def over(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) click to toggle source

Replace the path part of the URI.

# File lib/iri.rb, line 143
def path(val)
  modify do |c|
    c.path = val
  end
end

port(val) click to toggle source

Replace the port.

# File lib/iri.rb, line 136
def port(val)
  modify do |c|
    c.port = val
  end
end

query(val) click to toggle source

Replace the query part of the URI.

# File lib/iri.rb, line 157
def query(val)
  modify do |c|
    c.query = val
  end
end

scheme(val) click to toggle source

Replace the scheme.

# File lib/iri.rb, line 122
def scheme(val)
  modify do |c|
    c.scheme = val
  end
end

to_s() click to toggle source

Convert it to a string.

# File lib/iri.rb, line 64
def to_s
  @uri.to_s
end

to_uri() click to toggle source

Convert it to an object of class URI.

# File lib/iri.rb, line 69
def to_uri
  the_uri.clone
end

Private Instance Methods

modify() { |c| ... } click to toggle source

# File lib/iri.rb, line 201
def modify
  c = the_uri.clone
  yield c
  Iri.new(c)
end

modify_query() { |params| ... } click to toggle source

# File lib/iri.rb, line 207
def modify_query
  modify do |c|
    params = CGI.parse(the_uri.query || '').map do |p, a|
      [p.to_s, a.clone]
    end.to_h
    yield(params)
    c.query = URI.encode_www_form(params)
  end
end

the_uri() click to toggle source

# File lib/iri.rb, line 194
def the_uri
  @the_uri ||= URI(@uri)
rescue URI::InvalidURIError => e
  raise InvalidURI, e.message unless @safe
  @the_uri = URI('/')
end