iri 0.9.0 → 0.11.0

data/lib/iri.rb

@@ -1,121 +1,145 @@
 # frozen_string_literal: true
 
-# (The MIT License)
-#
-# Copyright (c) 2019-2025 Yegor Bugayenko
-#
-# Permission is hereby granted, free of charge, to any person obtaining a copy
-# of this software and associated documentation files (the 'Software'), to deal
-# in the Software without restriction, including without limitation the rights
-# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-# copies of the Software, and to permit persons to whom the Software is
-# furnished to do so, subject to the following conditions:
-#
-# The above copyright notice and this permission notice shall be included in all
-# copies or substantial portions of the Software.
-#
-# THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-# SOFTWARE.
+# SPDX-FileCopyrightText: Copyright (c) 2019-2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
 
 require 'uri'
 require 'cgi'
 
-# It is a simple URI builder.
+# Iri is a simple, immutable URI builder with a fluent interface.
+#
+# The Iri class provides methods to manipulate different parts of a URI,
+# including the scheme, host, port, path, query parameters, and fragment.
+# Each method returns a new Iri instance, maintaining immutability.
 #
-#  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
+# @example Creating and manipulating a URI
+#   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
+# @example Using the local option
+#   Iri.new('/path?foo=bar', local: true).to_s # => "/path?foo=bar"
+#
+# @example Using the safe mode
+#   Iri.new('invalid://uri', safe: true).to_s # => "/" (no exception thrown)
+#   Iri.new('invalid://uri', safe: false) # => raises Iri::InvalidURI
+#
+# For more information read the
 # {README}[https://github.com/yegor256/iri/blob/master/README.md] file.
 #
 # Author:: Yegor Bugayenko (yegor256@gmail.com)
 # Copyright:: Copyright (c) 2019-2025 Yegor Bugayenko
 # License:: MIT
 class Iri
-  # When URI is not valid.
+  # Exception raised when a URI is not valid and safe mode is disabled.
   class InvalidURI < StandardError; end
 
-  # When .add(), .over(), or .del() arguments are not valid.
+  # Exception raised when arguments to .add(), .over(), or .del() are not valid Hashes.
   class InvalidArguments < StandardError; end
 
-  # Makes a new object.
+  # Creates a new Iri object for URI manipulation.
   #
-  # You can even ignore the argument, which will produce an empty URI.
+  # 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.
+  # is not valid. It will just assume that the URI is "/". However,
+  # you can turn this safe mode off by specifying safe as FALSE, which will
+  # cause InvalidURI to be raised if the URI is malformed.
   #
-  # @param [String] uri URI
-  # @param [Boolean] safe SHould it safe?
-  def initialize(uri = '', safe: true)
+  # The local parameter can be used if you only want to work with the path,
+  # query, and fragment portions of a URI, without the scheme, host, and port.
+  #
+  # @param [String] uri URI string to parse
+  # @param [Boolean] local When true, ignores scheme, host and port parts
+  # @param [Boolean] safe When true, prevents InvalidURI exceptions
+  # @raise [InvalidURI] If the URI is malformed and safe is false
+  def initialize(uri = '', local: false, safe: true)
+    raise ArgumentError, "The uri can't be nil" if uri.nil?
     @uri = uri
+    @local = local
     @safe = safe
   end
 
-  # Convert it to a string.
+  # Converts the Iri object to a string representation of the URI.
+  #
+  # When local mode is enabled, only the path, query, and fragment parts are included.
+  # Otherwise, the full URI including scheme, host, and port is returned.
   #
-  # @return [String] New URI
+  # @return [String] String representation of the URI
   def to_s
-    @uri.to_s
+    u = the_uri
+    if @local
+      [
+        u.path,
+        u.query ? "?#{u.query}" : '',
+        u.fragment ? "##{u.fragment}" : ''
+      ].join
+    else
+      u.to_s
+    end
   end
 
-  # Inspect it, like a string can be inspected.
+  # Returns a string representation of the Iri object for inspection purposes.
   #
-  # @return [String] Details of it
+  # This method is used when the object is displayed in irb/console or with puts/p.
+  #
+  # @return [String] String representation for inspection
   def inspect
     @uri.to_s.inspect
   end
 
-  # Convert it to an object of class +URI+.
+  # Converts the Iri object to a Ruby standard library URI object.
   #
-  # @return [String] New URI
+  # @return [URI] A cloned URI object from the underlying URI
   def to_uri
     the_uri.clone
   end
 
-  # Removes the host, the port, and the scheme and returns
-  # only the local address, for example, converting "https://google.com/foo"
-  # into "/foo".
+  # Creates a new Iri object with only the local parts of the URI.
+  #
+  # Removes the host, the port, and the scheme, returning only the local address.
+  # For example, converting "https://google.com/foo" into "/foo".
+  # The path, query string, and fragment are preserved.
   #
-  # @return [String] Local part of the URI
+  # @return [Iri] A new Iri object with local:true and the same URI
+  # @see #initialize
   def to_local
-    u = the_uri
-    [
-      u.path,
-      u.query ? "?#{u.query}" : '',
-      u.fragment ? "##{u.fragment}" : ''
-    ].join
+    Iri.new(@uri, local: true, safe: @safe)
   end
 
-  # Add a few query arguments.
+  # Adds query parameters to the URI.
+  #
+  # This method appends query parameters to existing ones. If a parameter with the same
+  # name already exists, both values will be present in the resulting URI.
   #
-  # For example:
+  # @example Adding query parameters
+  #   Iri.new('https://google.com').add(q: 'test', limit: 10)
+  #   # => "https://google.com?q=test&limit=10"
   #
-  #  Iri.new('https://google.com').add(q: 'test', limit: 10)
+  # @example Adding parameters with the same name
+  #   Iri.new('https://google.com?q=foo').add(q: 'bar')
+  #   # => "https://google.com?q=foo&q=bar"
   #
-  # 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:
+  # You can ensure only one instance of a parameter by using +del+ first:
   #
-  #  Iri.new('https://google.com').del(:q).add(q: 'test')
+  # @example Replacing a parameter by deleting it first
+  #   Iri.new('https://google.com?q=foo').del(:q).add(q: 'test')
+  #   # => "https://google.com?q=test"
   #
-  # @param [Hash] hash Hash of names/values to set into the query part
-  # @return [Iri] A new iri
+  # @param [Hash] hash Hash of parameter names/values to add to the query part
+  # @return [Iri] A new Iri instance
+  # @raise [InvalidArguments] If the argument is not a Hash
+  # @see #del
+  # @see #over
   def add(hash)
+    raise ArgumentError, "The hash can't be nil" if hash.nil?
     raise InvalidArguments unless hash.is_a?(Hash)
     modify_query do |params|
       hash.each do |k, v|
@@ -124,15 +148,24 @@ class Iri
       end
     end
   end
+  alias with add
 
-  # Delete a few query arguments.
+  # Deletes query parameters from the URI.
   #
-  # For example:
+  # This method removes all instances of the specified parameters from the query string.
   #
-  #  Iri.new('https://google.com?q=test').del(:q)
+  # @example Deleting a query parameter
+  #   Iri.new('https://google.com?q=test&limit=10').del(:q)
+  #   # => "https://google.com?limit=10"
   #
-  # @param [Array] keys List of keys to delete
-  # @return [Iri] A new iri
+  # @example Deleting multiple parameters
+  #   Iri.new('https://google.com?q=test&limit=10&sort=asc').del(:q, :limit)
+  #   # => "https://google.com?sort=asc"
+  #
+  # @param [Array<Symbol, String>] keys List of parameter names to delete
+  # @return [Iri] A new Iri instance
+  # @see #add
+  # @see #over
   def del(*keys)
     modify_query do |params|
       keys.each do |k|
@@ -140,94 +173,164 @@ class Iri
       end
     end
   end
+  alias without del
 
-  # Replace query argument(s).
+  # Replaces query parameters in the URI.
+  #
+  # Unlike #add, this method replaces any existing parameters with the same name
+  # rather than adding additional instances. If a parameter doesn't exist,
+  # it will be added.
   #
-  #  Iri.new('https://google.com?q=test').over(q: 'hey you!')
+  # @example Replacing a query parameter
+  #   Iri.new('https://google.com?q=test').over(q: 'hey you!')
+  #   # => "https://google.com?q=hey+you%21"
   #
-  # @param [Hash] hash Hash of names/values to set into the query part
-  # @return [Iri] A new iri
+  # @example Replacing multiple parameters
+  #   Iri.new('https://google.com?q=test&limit=5').over(q: 'books', limit: 10)
+  #   # => "https://google.com?q=books&limit=10"
+  #
+  # @param [Hash] hash Hash of parameter names/values to replace in the query part
+  # @return [Iri] A new Iri instance
+  # @raise [InvalidArguments] If the argument is not a Hash
+  # @see #add
+  # @see #del
   def over(hash)
+    raise ArgumentError, "The hash can't be nil" if hash.nil?
     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] = [] unless params[k.to_s]
         params[k.to_s] = [v]
       end
     end
   end
 
-  # Replace the scheme.
+  # Replaces the scheme part of the URI.
+  #
+  # @example Changing the scheme
+  #   Iri.new('http://google.com').scheme('https')
+  #   # => "https://google.com"
   #
   # @param [String] val New scheme to set, like "https" or "http"
-  # @return [Iri] A new iri
+  # @return [Iri] A new Iri instance
+  # @see #host
+  # @see #port
   def scheme(val)
+    raise ArgumentError, "The scheme can't be nil" if val.nil?
     modify do |c|
       c.scheme = val
     end
   end
 
-  # Replace the host.
+  # Replaces the host part of the URI.
+  #
+  # @example Changing the host
+  #   Iri.new('https://google.com').host('example.com')
+  #   # => "https://example.com"
   #
-  # @param [String] val New host to set, like "google.com" or "192.168.0.1"
-  # @return [Iri] A new iri
+  # @param [String] val New host to set, like "example.com" or "192.168.0.1"
+  # @return [Iri] A new Iri instance
+  # @see #scheme
+  # @see #port
   def host(val)
+    raise ArgumentError, "The host can't be nil" if val.nil?
     modify do |c|
       c.host = val
     end
   end
 
-  # Replace the port.
+  # Replaces the port part of the URI.
+  #
+  # @example Changing the port
+  #   Iri.new('https://example.com').port('8443')
+  #   # => "https://example.com:8443"
   #
   # @param [String] val New TCP port to set, like "8080" or "443"
-  # @return [Iri] A new iri
+  # @return [Iri] A new Iri instance
+  # @see #scheme
+  # @see #host
   def port(val)
+    raise ArgumentError, "The port can't be nil" if val.nil?
     modify do |c|
       c.port = val
     end
   end
 
-  # Replace the path part of the URI.
+  # Replaces the path part of the URI.
+  #
+  # @example Changing the path
+  #   Iri.new('https://example.com/foo').path('/bar/baz')
+  #   # => "https://example.com/bar/baz"
   #
   # @param [String] val New path to set, like "/foo/bar"
-  # @return [Iri] A new iri
+  # @return [Iri] A new Iri instance
+  # @see #query
+  # @see #fragment
   def path(val)
+    raise ArgumentError, "The path can't be nil" if val.nil?
     modify do |c|
       c.path = val
     end
   end
 
-  # Replace the fragment part of the URI.
+  # Replaces the fragment part of the URI (the part after #).
   #
-  # @param [String] val New fragment to set, like "hello"
-  # @return [Iri] A new iri
+  # @example Setting a fragment
+  #   Iri.new('https://example.com/page').fragment('section2')
+  #   # => "https://example.com/page#section2"
+  #
+  # @param [String] val New fragment to set, like "section2"
+  # @return [Iri] A new Iri instance
+  # @see #path
+  # @see #query
   def fragment(val)
+    raise ArgumentError, "The fragment can't be nil" if val.nil?
     modify do |c|
       c.fragment = val.to_s
     end
   end
 
-  # Replace the query part of the URI.
+  # Replaces the entire query part of the URI.
+  #
+  # Use this method to completely replace the query string. For modifying
+  # individual parameters, see #add, #del, and #over.
   #
-  # @param [String] val New query to set, like "a=1&b=2"
-  # @return [Iri] A new iri
+  # @example Setting a query string
+  #   Iri.new('https://example.com/search').query('q=ruby&limit=10')
+  #   # => "https://example.com/search?q=ruby&limit=10"
+  #
+  # @param [String] val New query string to set, like "a=1&b=2"
+  # @return [Iri] A new Iri instance
+  # @see #add
+  # @see #del
+  # @see #over
   def query(val)
+    raise ArgumentError, "The query can't be nil" if val.nil?
     modify do |c|
       c.query = val
     end
   end
 
-  # Remove the entire path+query+fragment part.
+  # Removes the entire path, query, and fragment parts and sets a new path.
   #
-  # For example:
+  # This method is useful for "cutting off" everything after the host:port
+  # and setting a new path, effectively removing query string and fragment.
   #
-  #  Iri.new('https://google.com/a/b?q=test').cut('/hello')
+  # @example Cutting off path/query/fragment and setting a new path
+  #   Iri.new('https://google.com/a/b?q=test').cut('/hello')
+  #   # => "https://google.com/hello"
   #
-  # The result will contain "https://google.com/hello".
+  # @example Resetting to root path
+  #   Iri.new('https://google.com/a/b?q=test#section2').cut()
+  #   # => "https://google.com/"
   #
-  # @param [String] path New path to set, like "/foo"
-  # @return [Iri] A new iri
+  # @param [String] path New path to set, defaults to "/"
+  # @return [Iri] A new Iri instance
+  # @see #path
+  # @see #query
+  # @see #fragment
   def cut(path = '/')
+    raise ArgumentError, "The path can't be nil" if path.nil?
     modify do |c|
       c.query = nil
       c.path = path
@@ -235,17 +338,28 @@ class Iri
     end
   end
 
-  # Append something new to the path.
+  # Appends a new segment to the existing path.
+  #
+  # This method adds a new segment to the existing path, automatically handling
+  # the slash between segments and URL encoding the new segment.
   #
-  # For example:
+  # @example Appending a path segment
+  #   Iri.new('https://example.com/a/b?q=test').append('hello')
+  #   # => "https://example.com/a/b/hello?q=test"
   #
-  #  Iri.new('https://google.com/a/b?q=test').append('/hello')
+  # @example Appending to a path with a trailing slash
+  #   Iri.new('https://example.com/a/').append('hello')
+  #   # => "https://example.com/a/hello?q=test"
   #
-  # The result will contain "https://google.com/a/b/hello?q=test".
+  # @example Appending a segment that needs URL encoding
+  #   Iri.new('https://example.com/docs').append('section 1')
+  #   # => "https://example.com/docs/section%201"
   #
-  # @param [String] part New segment to add to existing path
-  # @return [Iri] A new iri
+  # @param [String, #to_s] part New segment to add to the existing path
+  # @return [Iri] A new Iri instance
+  # @see #path
   def append(part)
+    raise ArgumentError, "The part can't be nil" if part.nil?
     modify do |c|
       tail = (c.path.end_with?('/') ? '' : '/') + CGI.escape(part.to_s)
       c.path = c.path + tail
@@ -254,6 +368,14 @@ class Iri
 
   private
 
+  # Parses the URI string into a URI object.
+  #
+  # This method handles the safe mode by catching and handling invalid URI errors.
+  # When safe mode is enabled (default), invalid URIs will return the root path URI "/"
+  # instead of raising an exception.
+  #
+  # @return [URI] The parsed URI object
+  # @raise [InvalidURI] If the URI is invalid and safe mode is disabled
   def the_uri
     @the_uri ||= URI(@uri)
   rescue URI::InvalidURIError => e
@@ -261,12 +383,27 @@ class Iri
     @the_uri = URI('/')
   end
 
+  # Creates a new Iri object after modifying the underlying URI.
+  #
+  # This helper method clones the current URI, yields it to a block for modification,
+  # and then creates a new Iri object with the modified URI, preserving the local and safe flags.
+  #
+  # @yield [URI] The cloned URI object for modification
+  # @return [Iri] A new Iri instance with the modified URI
   def modify
     c = the_uri.clone
     yield c
-    Iri.new(c)
+    Iri.new(c, local: @local, safe: @safe)
   end
 
+  # Creates a new Iri object after modifying the query parameters.
+  #
+  # This helper method parses the current query string into a hash of parameter names
+  # to arrays of values, yields this hash for modification, and then encodes it back
+  # into a query string. It uses the modify method to create a new Iri object.
+  #
+  # @yield [Hash] The parsed query parameters for modification
+  # @return [Iri] A new Iri instance with the modified query string
   def modify_query
     modify do |c|
       params = CGI.parse(the_uri.query || '').map do |p, a|

data/test/test__helper.rb

@@ -1,26 +1,31 @@
 # frozen_string_literal: true
 
-# Copyright (c) 2019-2025 Yegor Bugayenko
-#
-# Permission is hereby granted, free of charge, to any person obtaining a copy
-# of this software and associated documentation files (the 'Software'), to deal
-# in the Software without restriction, including without limitation the rights
-# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-# copies of the Software, and to permit persons to whom the Software is
-# furnished to do so, subject to the following conditions:
-#
-# The above copyright notice and this permission notice shall be included in all
-# copies or substantial portions of the Software.
-#
-# THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-# FITNESS FOR A PARTICULAR PURPOSE AND NONINFINGEMENT. IN NO EVENT SHALL THE
-# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-# SOFTWARE.
+# SPDX-FileCopyrightText: Copyright (c) 2019-2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
 
 $stdout.sync = true
 
 require 'simplecov'
-SimpleCov.start
+require 'simplecov-cobertura'
+unless SimpleCov.running
+  SimpleCov.command_name('test')
+  SimpleCov.formatter = SimpleCov::Formatter::MultiFormatter.new(
+    [
+      SimpleCov::Formatter::HTMLFormatter,
+      SimpleCov::Formatter::CoberturaFormatter
+    ]
+  )
+  SimpleCov.minimum_coverage 100
+  SimpleCov.minimum_coverage_by_file 100
+  SimpleCov.start do
+    add_filter 'test/'
+    add_filter 'vendor/'
+    add_filter 'target/'
+    track_files 'lib/**/*.rb'
+    track_files '*.rb'
+  end
+end
+
+require 'minitest/autorun'
+require 'minitest/reporters'
+Minitest::Reporters.use! [Minitest::Reporters::SpecReporter.new]