Class: URI::Generic

Relationships & Source Files
Extension / Inclusion / Inheritance Descendants
Subclasses: FTP, File, HTTP, HTTPS, LDAP, LDAPS, MailTo, WS, WSS
Super Chains via Extension / Inclusion / Inheritance
Instance Chain: self, `::URI`
Inherits:	Object
Defined in:	lib/uri/generic.rb

Overview

Base class for all ::URI classes. Implements generic ::URI syntax as per RFC 2396.

Constant Summary

COMPONENT =

An Array of the available components for Generic.

# File 'lib/uri/generic.rb', line 46

[
  :scheme,
  :userinfo, :host, :port, :registry,
  :path, :opaque,
  :query,
  :fragment
].freeze

DEFAULT_PORT =

A Default port of nil for Generic.

# File 'lib/uri/generic.rb', line 27
```
nil
```
USE_REGISTRY = Internal use only
# File 'lib/uri/generic.rb', line 61
```
false
```

`::URI` - Included

DEFAULT_PARSER, INITIAL_SCHEMES, RFC2396_PARSER, RFC3986_PARSER, TBLDECWWWCOMP_, TBLENCURICOMP_, TBLENCWWWCOMP_, VERSION, VERSION_CODE, WEB_ENCODINGS_

Class Method Summary

.build(args)

Synopsis.
.build2(args)

Synopsis.
.component

Components of the ::URI in the order.
.default_port

Returns default port.
.new(scheme, userinfo, host, port, registry, path, opaque, query, fragment, parser = DEFAULT_PARSER, arg_check = false) ⇒ Generic constructor

Args.
.use_proxy?(hostname, addr, port, no_proxy) ⇒ Boolean Internal use only
.use_registry Internal use only

Instance Attribute Summary

#absolute readonly

Alias for #absolute?.
#fragment rw

Returns the fragment component of the ::URI.
#fragment=(v) rw

Checks the fragment v component against the URI::Parser Regexp for :FRAGMENT.
#hierarchical? ⇒ Boolean readonly

Returns true if ::URI is hierarchical.
#host rw

Returns the host component of the ::URI.
#host=(v) rw

Args.
#hostname rw

Extract the host part of the ::URI and unwrap brackets for IPv6 addresses.
#hostname=(v) rw

Sets the host part of the ::URI as the argument with brackets for IPv6 addresses.
#opaque rw

Returns the opaque part of the ::URI.
#opaque=(v) rw

Args.
#password rw

Returns the password component (without ::URI decoding).
#password=(password) rw

Args.
#path rw

Returns the path component of the ::URI.
#path=(v) rw

Args.
#port rw

Returns the port component of the ::URI.
#port=(v) rw

Args.
#query rw

Returns the query component of the ::URI.
#query=(v) rw

Args.
#relative? ⇒ Boolean readonly

Returns true if ::URI does not have a scheme (e.g.
#scheme rw

Returns the scheme component of the ::URI.
#scheme=(v) rw

Args.
#user rw

Returns the user component (without ::URI decoding).
#user=(user) rw

Args.
#userinfo rw

Returns the userinfo, either as ‘user’ or ‘user:password’.
#userinfo=(userinfo) rw

Sets userinfo, argument is string like ‘name:pass’.
#registry rw Internal use only
#registry=(v) rw Internal use only

Instance Method Summary

#+(oth)

Alias for #merge.
#-(oth)

Alias for #route_from.
#==(oth)

Compares two URIs.
#absolute? ⇒ Boolean (also: #absolute) readonly

Returns true if ::URI has a scheme (e.g.
#authority

Returns the authority info (array of user, password, host and port), if any is set.
#coerce(oth)

Args.
#component

Components of the ::URI in the order.
#decoded_password

Returns the password component after ::URI decoding.
#decoded_user

Returns the user component after ::URI decoding.
#default_port

Returns default port.
#eql?(oth) ⇒ Boolean

Compares with oth for Hash.
#find_proxy(env = ENV)

Returns a proxy ::URI.
#hash

Returns the hash value.
#merge(oth) (also: #+)

Args.
#merge!(oth)

Args.
#normalize

Returns normalized ::URI.
#normalize!

Destructive version of #normalize.
#parser

Returns the parser to be used.
#route_from(oth) (also: #-)

Args.
#route_to(oth)

Args.
#select(*components)

Args.
#to_s (also: #to_str)

Constructs String from ::URI.
#to_str

Alias for #to_s.
#component_ary protected

Returns an Array of the components defined from the COMPONENT Array.
#set_authority(user, password, host, port = nil) protected

Protected setter for the authority info (#user, #password, #host and #port).
#set_host(v) protected

Protected setter for the host component v.
#set_opaque(v) protected

Protected setter for the opaque component v.
#set_password(v) protected

Protected setter for the password component v.
#set_path(v) protected

Protected setter for the path component v.
#set_port(v) protected

Protected setter for the port component v.
#set_scheme(v) protected

Protected setter for the scheme component v.
#set_user(v) protected

Protected setter for the user component v.
#set_userinfo(user, password = nil) protected

Protected setter for the #user component, and #password if available (with validation).
#check_host(v) private

Checks the host v component for RFC2396 compliance and against the URI::Parser Regexp for :HOST.
#check_opaque(v) private

Checks the opaque v component for RFC2396 compliance and against the URI::Parser Regexp for :OPAQUE.
#check_password(v, user = @user) private

Checks the password v component for RFC2396 compliance and against the URI::Parser Regexp for :USERINFO.
#check_path(v) private

Checks the path v component for RFC2396 compliance and against the URI::Parser Regexp for :ABS_PATH and :REL_PATH.
#check_port(v) private

Checks the port v component for RFC2396 compliance and against the URI::Parser Regexp for :PORT.
#check_scheme(v) private

Checks the scheme v component against the URI::Parser Regexp for :SCHEME.
#check_user(v) private

Checks the user v component for RFC2396 compliance and against the URI::Parser Regexp for :USERINFO.
#check_userinfo(user, password = nil) private

Checks the #user and #password.
#escape_userpass(v) private

Escapes ‘user:password’ v based on RFC 1738 section 3.1.
#merge_path(base, rel) private

Merges a base path base, with relative path rel, returns a modified base path.
#replace!(oth) private

Replaces self by other ::URI object.
#route_from0(oth) private
#split_path(path) private

Returns an Array of the path split on ‘/’.
#split_userinfo(ui) private

Returns the userinfo ui as [user, password] if properly formatted as ‘user:password’.
#inspect Internal use only
#set_registry(v) protected Internal use only
#check_registry(v) private Internal use only
#route_from_path(src, dst) private Internal use only

Constructor Details

.new(scheme, userinfo, host, port, registry, path, opaque, query, fragment, parser = DEFAULT_PARSER, arg_check = false) ⇒ `Generic`

Args

#scheme: Protocol scheme, i.e. ‘http’,‘ftp’,‘mailto’ and so on.
#userinfo: User name and password, i.e. ‘sdmitry:bla’.
#host: Server host name.
#port: Server port.
#registry: Registry of naming authorities.
#path: Path on server.
#opaque: Opaque part.
#query: Query data.
#fragment: Part of the URI after ‘#’ character.
#parser: Parser for internal use [URI::DEFAULT_PARSER by default].
arg_check: Check arguments [false by default].

Description

Creates a new Generic instance from “generic” components without check.

[ GitHub ]

# File 'lib/uri/generic.rb', line 169


def initialize(scheme,
               userinfo, host, port, registry,
               path, opaque,
               query,
               fragment,
               parser = DEFAULT_PARSER,
               arg_check = false)
  @scheme = nil
  @user = nil
  @password = nil
  @host = nil
  @port = nil
  @path = nil
  @query = nil
  @opaque = nil
  @fragment = nil
  @parser = parser == DEFAULT_PARSER ? nil : parser

  if arg_check
    self.scheme = scheme
    self.hostname = host
    self.port = port
    self.userinfo = userinfo
    self.path = path
    self.query = query
    self.opaque = opaque
    self.fragment = fragment
  else
    self.set_scheme(scheme)
    self.set_host(host)
    self.set_port(port)
    self.set_userinfo(userinfo)
    self.set_path(path)
    self.query = query
    self.set_opaque(opaque)
    self.fragment=(fragment)
  end
  if registry
    raise InvalidURIError,
      "the scheme #{@scheme} does not accept registry part: #{registry} (or bad hostname?)"
  end

  @scheme&.freeze
  self.set_path('') if !@path && !@opaque # (see RFC2396 Section 5.2)
  self.set_port(self.default_port) if self.default_port && !@port
end

Class Method Details

.build(args)

Synopsis

See .new.

Description

Creates a new Generic instance from components of Generic with check. Components are: scheme, userinfo, host, port, registry, path, opaque, query, and fragment. You can provide arguments either by an Array or a Hash. See .new for hash keys to use or for order of array items.

[ GitHub ]

# File 'lib/uri/generic.rb', line 116


def self.build(args)
  if args.kind_of?(Array) &&
      args.size == ::URI::Generic::COMPONENT.size
    tmp = args.dup
  elsif args.kind_of?(Hash)
    tmp = ::URI::Generic::COMPONENT.collect do |c|
      if args.include?(c)
        args[c]
      else
        nil
      end
    end
  else
    component = self.class.component rescue ::URI::Generic::COMPONENT
    raise ArgumentError,
    "expected Array of or Hash of components of #{self.class} (#{component.join(', ')})"
  end

  tmp << nil
  tmp << true
  return self.new(*tmp)
end

.build2(args)

Synopsis

See .new.

Description

At first, tries to create a new Generic instance using .build. But, if exception InvalidComponentError is raised, then it does URI::Escape.escape all ::URI components and tries again.

[ GitHub ]

# File 'lib/uri/generic.rb', line 78


def self.build2(args)
  begin
    return self.build(args)
  rescue InvalidComponentError
    if args.kind_of?(Array)
      return self.build(args.collect{|x|
        if x.is_a?(String)
          URI::RFC2396_PARSER.escape(x)
        else
          x
        end
      })
    elsif args.kind_of?(Hash)
      tmp = {}
      args.each do |key, value|
        tmp[key] = if value
            URI::RFC2396_PARSER.escape(value)
          else
            value
          end
      end
      return self.build(tmp)
    end
  end
end

.component

Components of the ::URI in the order.

[ GitHub ]

# File 'lib/uri/generic.rb', line 57


def self.component
  self::COMPONENT
end

.default_port

Returns default port.

[ GitHub ]

# File 'lib/uri/generic.rb', line 32


def self.default_port
  self::DEFAULT_PORT
end

.use_proxy?(hostname, addr, port, no_proxy) ⇒ `Boolean`

This method is for internal use only.

[ GitHub ]

# File 'lib/uri/generic.rb', line 1570


def self.use_proxy?(hostname, addr, port, no_proxy) # :nodoc:
  hostname = hostname.downcase
  dothostname = ".#{hostname}"
  no_proxy.scan(/([^:,\s])(?::(\d))?/) {|p_host, p_port|
    if !p_port || port == p_port.to_i
      if p_host.start_with?('.')
        return false if hostname.end_with?(p_host.downcase)
      else
        return false if dothostname.end_with?(".#{p_host.downcase}")
      end
      if addr
        begin
          return false if IPAddr.new(p_host).include?(addr)
        rescue IPAddr::InvalidAddressError
          next
        end
      end
    end
  }
  true
end

.use_registry

This method is for internal use only.

[ GitHub ]

# File 'lib/uri/generic.rb', line 63


def self.use_registry # :nodoc:
  self::USE_REGISTRY
end

Instance Attribute Details

#absolute (readonly)

Alias for #absolute?.

[ GitHub ]

# File 'lib/uri/generic.rb', line 994


alias absolute absolute?

#fragment (rw)

Returns the fragment component of the ::URI.

URI("http://foo/bar/baz?search=FooBar#ponies").fragment #=> "ponies"

[ GitHub ]

# File 'lib/uri/generic.rb', line 283


attr_reader :fragment

#fragment=(v) (rw)

Checks the fragment v component against the URI::Parser Regexp for :FRAGMENT.

Args

v: String

Description

Public setter for the fragment component v (with validation).

Usage

require 'uri'

uri = URI.parse("http://my.example.com/?id=25#time=1305212049")
uri.fragment = "time=1305212086"
uri.to_s  #=> "http://my.example.com/?id=25#time=1305212086"

[ GitHub ]

# File 'lib/uri/generic.rb', line 944


def fragment=(v)
  return @fragment = nil unless v

  x = v.to_str
  v = x.dup if x.equal? v
  v.encode!(Encoding::UTF_8) rescue nil
  v.delete!("\t\r\n")
  v.force_encoding(Encoding::ASCII_8BIT)
  v.gsub!(/(?!%\h\h|[!-~])./n){'%%%02X' % $&.ord}
  v.force_encoding(Encoding::US_ASCII)
  @fragment = v
end

#hierarchical? ⇒ `Boolean` (readonly)

Returns true if ::URI is hierarchical.

Description

::URI has components listed in order of decreasing significance from left to right, see RFC3986 www.rfc-editor.org/rfc/rfc3986 1.2.3.

Usage

require 'uri'

uri = URI.parse("http://my.example.com/")
uri.hierarchical?
#=> true
uri = URI.parse("mailto:joe@example.com")
uri.hierarchical?
#=> false

[ GitHub ]

# File 'lib/uri/generic.rb', line 976


def hierarchical?
  if @path
    true
  else
    false
  end
end

#host (rw)

Returns the host component of the ::URI.

URI("http://foo/bar/baz").host #=> "foo"

It returns nil if no host component exists.

URI("mailto:foo@example.org").host #=> nil

The component does not contain the port number.

URI("http://foo:8080/bar/baz").host #=> "foo"

Since IPv6 addresses are wrapped with brackets in URIs, this method returns IPv6 addresses wrapped with brackets. This form is not appropriate to pass to socket methods such as TCPSocket.open. If unwrapped host names are required, use the #hostname method.

URI("http://[::1]/bar/baz").host     #=> "[::1]"
URI("http://[::1]/bar/baz").hostname #=> "::1"

[ GitHub ]

# File 'lib/uri/generic.rb', line 243


attr_reader :host

#host=(v) (rw)

Args

v: String

Description

Public setter for the host component v (with validation).

Usage

require 'uri'

uri = URI.parse("http://my.example.com")
uri.host = "foo.com"
uri.to_s  #=> "http://foo.com"

[ GitHub ]

# File 'lib/uri/generic.rb', line 652


def host=(v)
  check_host(v)
  set_host(v)
  set_userinfo(nil)
  v
end

#hostname (rw)

Extract the host part of the ::URI and unwrap brackets for IPv6 addresses.

This method is the same as #host except brackets for IPv6 (and future IP) addresses are removed.

uri = URI("http://[::1]/bar")
uri.hostname      #=> "::1"
uri.host          #=> "[::1]"

[ GitHub ]

# File 'lib/uri/generic.rb', line 668


def hostname
  v = self.host
  v&.start_with?('[') && v.end_with?(']') ? v[1..-2] : v
end

#hostname=(v) (rw)

Sets the host part of the ::URI as the argument with brackets for IPv6 addresses.

This method is the same as #host= except the argument can be a bare IPv6 address.

uri = URI("http://foo/bar")
uri.hostname = "::1"
uri.to_s  #=> "http://[::1]/bar"

If the argument seems to be an IPv6 address, it is wrapped with brackets.

[ GitHub ]

# File 'lib/uri/generic.rb', line 685


def hostname=(v)
  v = "[#{v}]" if !(v&.start_with?('[') && v&.end_with?(']')) && v&.index(':')
  self.host = v
end

#opaque (rw)

Returns the opaque part of the ::URI.

URI("mailto:foo@example.org").opaque #=> "foo@example.org"
URI("http://foo/bar/baz").opaque     #=> nil

The portion of the path that does not make use of the slash ‘/’. The path typically refers to an absolute path or an opaque part. (See RFC2396 Section 3 and 5.2.)

[ GitHub ]

# File 'lib/uri/generic.rb', line 277


attr_reader :opaque

#opaque=(v) (rw)

Args

v: String

Description

Public setter for the opaque component v (with validation).

#password (rw)

Returns the password component (without ::URI decoding).

[ GitHub ]

# File 'lib/uri/generic.rb', line 573


def password
  @password
end

#password=(password) (rw)

Args

v: String

Description

Public setter for the #password component (with validation).

Usage

require 'uri'

uri = URI.parse("http://john:S3nsit1ve@my.example.com")
uri.password = "V3ry_S3nsit1ve"
uri.to_s  #=> "http://john:V3ry_S3nsit1ve@my.example.com"

[ GitHub ]

# File 'lib/uri/generic.rb', line 498


def password=(password)
  check_password(password)
  set_password(password)
  # returns password
end

#path (rw)

Returns the path component of the ::URI.

URI("http://foo/bar/baz").path #=> "/bar/baz"

[ GitHub ]

# File 'lib/uri/generic.rb', line 260


attr_reader :path

#path=(v) (rw)

Args

v: String

Description

Public setter for the path component v (with validation).

Usage

require 'uri'

uri = URI.parse("http://my.example.com/pub/files")
uri.path = "/faq/"
uri.to_s  #=> "http://my.example.com/faq/"

[ GitHub ]

# File 'lib/uri/generic.rb', line 830


def path=(v)
  check_path(v)
  set_path(v)
  v
end

#port (rw)

Returns the port component of the ::URI.

URI("http://foo/bar/baz").port      #=> 80
URI("http://foo:8080/bar/baz").port #=> 8080

[ GitHub ]

# File 'lib/uri/generic.rb', line 250


attr_reader :port

#port=(v) (rw)

Args

v: String

Description

Public setter for the port component v (with validation).

Usage

require 'uri'

uri = URI.parse("http://my.example.com")
uri.port = 8080
uri.to_s  #=> "http://my.example.com:8080"

[ GitHub ]

# File 'lib/uri/generic.rb', line 743


def port=(v)
  check_port(v)
  set_port(v)
  set_userinfo(nil)
  port
end

#query (rw)

Returns the query component of the ::URI.

URI("http://foo/bar/baz?search=FooBar").query #=> "search=FooBar"

[ GitHub ]

# File 'lib/uri/generic.rb', line 266


attr_reader :query

#query=(v) (rw)

Args

v: String

Description

Public setter for the query component v.

Usage

require 'uri'

uri = URI.parse("http://my.example.com/?id=25")
uri.query = "id=1"
uri.to_s  #=> "http://my.example.com/?id=1"

Raises:

(InvalidURIError)

[ GitHub ]

# File 'lib/uri/generic.rb', line 854


def query=(v)
  return @query = nil unless v
  raise InvalidURIError, "query conflicts with opaque" if @opaque

  x = v.to_str
  v = x.dup if x.equal? v
  v.encode!(Encoding::UTF_8) rescue nil
  v.delete!("\t\r\n")
  v.force_encoding(Encoding::ASCII_8BIT)
  raise InvalidURIError, "invalid percent escape: #{$1}" if /(%\H\H)/n.match(v)
  v.gsub!(/(?!%\h\h|[!$-&(-;=?-_a-~])./n.freeze){'%%%02X' % $&.ord}
  v.force_encoding(Encoding::US_ASCII)
  @query = v
end

#registry (rw)

This method is for internal use only.

[ GitHub ]

# File 'lib/uri/generic.rb', line 252


def registry # :nodoc:
  nil
end

#registry=(v) (rw)

This method is for internal use only.

Raises:

(InvalidURIError)

[ GitHub ]

# File 'lib/uri/generic.rb', line 760


def registry=(v) # :nodoc:
  raise InvalidURIError, "cannot set registry"
end

#relative? ⇒ `Boolean` (readonly)

Returns true if ::URI does not have a scheme (e.g. http:// or https://) specified.

[ GitHub ]

# File 'lib/uri/generic.rb', line 999


def relative?
  !absolute?
end

#scheme (rw)

Returns the scheme component of the ::URI.

URI("http://foo/bar/baz").scheme #=> "http"

[ GitHub ]

# File 'lib/uri/generic.rb', line 221


attr_reader :scheme

#scheme=(v) (rw)

Args

v: String

Description

Public setter for the scheme component v (with validation).

Usage

require 'uri'

uri = URI.parse("http://my.example.com")
uri.scheme = "https"
uri.to_s  #=> "https://my.example.com"

[ GitHub ]

# File 'lib/uri/generic.rb', line 360


def scheme=(v)
  check_scheme(v)
  set_scheme(v)
  v
end

#user (rw)

Returns the user component (without ::URI decoding).

[ GitHub ]

# File 'lib/uri/generic.rb', line 568


def user
  @user
end

#user=(user) (rw)

Args

v: String

Description

Public setter for the #user component (with validation).

Usage

require 'uri'

uri = URI.parse("http://john:S3nsit1ve@my.example.com")
uri.user = "sam"
uri.to_s  #=> "http://sam:V3ry_S3nsit1ve@my.example.com"

[ GitHub ]

# File 'lib/uri/generic.rb', line 471


def user=(user)
  check_user(user)
  set_user(user)
  # returns user
end

#userinfo (rw)

Returns the userinfo, either as ‘user’ or ‘user:password’.

[ GitHub ]

# File 'lib/uri/generic.rb', line 557


def userinfo
  if @user.nil?
    nil
  elsif @password.nil?
    @user
  else
    @user + ':' + @password
  end
end

#userinfo=(userinfo) (rw)

Sets userinfo, argument is string like ‘name:pass’.

[ GitHub ]

# File 'lib/uri/generic.rb', line 441


def userinfo=(userinfo)
  if userinfo.nil?
    return nil
  end
  check_userinfo(*userinfo)
  set_userinfo(*userinfo)
  # returns userinfo
end

Instance Method Details

#+(oth)

Alias for #merge.

[ GitHub ]

# File 'lib/uri/generic.rb', line 1164


alias + merge

#-(oth)

Alias for #route_from.

[ GitHub ]

# File 'lib/uri/generic.rb', line 1294


alias - route_from

#==(oth)

Compares two URIs.

[ GitHub ]

# File 'lib/uri/generic.rb', line 1399


def ==(oth)
  if self.class == oth.class
    self.normalize.component_ary == oth.normalize.component_ary
  else
    false
  end
end

#absolute? ⇒ `Boolean` (readonly) Also known as: #absolute

Returns true if ::URI has a scheme (e.g. http:// or https://) specified.

[ GitHub ]

# File 'lib/uri/generic.rb', line 987


def absolute?
  if @scheme
    true
  else
    false
  end
end

#authority

Returns the authority info (array of user, password, host and port), if any is set. Or returns nil.

[ GitHub ]

# File 'lib/uri/generic.rb', line 579


def authority
  return @user, @password, @host, @port if @user || @password || @host || @port
end

#check_host(v) (private)

Checks the host v component for RFC2396 compliance and against the URI::Parser Regexp for :HOST.

Can not have a registry or opaque component defined, with a host component defined.

[ GitHub ]

# File 'lib/uri/generic.rb', line 600


def check_host(v)
  return v unless v

  if @opaque
    raise InvalidURIError,
      "cannot set host with registry or opaque"
  elsif parser.regexp[:HOST] !~ v
    raise InvalidComponentError,
      "bad component(expected host component): #{v}"
  end

  return true
end

#check_opaque(v) (private)

Checks the opaque v component for RFC2396 compliance and against the URI::Parser Regexp for :OPAQUE.

Can not have a host, port, user, or path component defined, with an opaque component defined.

[ GitHub ]

# File 'lib/uri/generic.rb', line 876


def check_opaque(v)
  return v unless v

  # raise if both hier and opaque are not nil, because:
  # absoluteURI   = scheme ":" ( hier_part | opaque_part )
  # hier_part     = ( net_path | abs_path ) [ "?" query ]
  if @host || @port || @user || @path  # userinfo = @user + ':' + @password
    raise InvalidURIError,
      "cannot set opaque with host, port, userinfo or path"
  elsif v && parser.regexp[:OPAQUE] !~ v
    raise InvalidComponentError,
      "bad component(expected opaque component): #{v}"
  end

  return true
end

#check_password(v, user = @user) (private)

Checks the password v component for RFC2396 compliance and against the URI::Parser Regexp for :USERINFO.

Can not have a registry or opaque component defined, with a user component defined.

[ GitHub ]

# File 'lib/uri/generic.rb', line 417


def check_password(v, user = @user)
  if @opaque
    raise InvalidURIError,
      "cannot set password with opaque"
  end
  return v unless v

  if !user
    raise InvalidURIError,
      "password component depends user component"
  end

  if parser.regexp[:USERINFO] !~ v
    raise InvalidComponentError,
      "bad password component"
  end

  return true
end

#check_path(v) (private)

Checks the path v component for RFC2396 compliance and against the URI::Parser Regexp for :ABS_PATH and :REL_PATH.

Can not have a opaque component defined, with a path component defined.

[ GitHub ]

# File 'lib/uri/generic.rb', line 772


def check_path(v)
  # raise if both hier and opaque are not nil, because:
  # absoluteURI   = scheme ":" ( hier_part | opaque_part )
  # hier_part     = ( net_path | abs_path ) [ "?" query ]
  if v && @opaque
    raise InvalidURIError,
      "path conflicts with opaque"
  end

  # If scheme is ftp, path may be relative.
  # See RFC 1738 section 3.2.2, and RFC 2396.
  if @scheme && @scheme != "ftp"
    if v && v != '' && parser.regexp[:ABS_PATH] !~ v
      raise InvalidComponentError,
        "bad component(expected absolute path component): #{v}"
    end
  else
    if v && v != '' && parser.regexp[:ABS_PATH] !~ v &&
       parser.regexp[:REL_PATH] !~ v
      raise InvalidComponentError,
        "bad component(expected relative path component): #{v}"
    end
  end

  return true
end

#check_port(v) (private)

Checks the port v component for RFC2396 compliance and against the URI::Parser Regexp for :PORT.

Can not have a registry or opaque component defined, with a port component defined.

[ GitHub ]

# File 'lib/uri/generic.rb', line 697


def check_port(v)
  return v unless v

  if @opaque
    raise InvalidURIError,
      "cannot set port with registry or opaque"
  elsif !v.kind_of?(Integer) && parser.regexp[:PORT] !~ v
    raise InvalidComponentError,
      "bad component(expected port component): #{v.inspect}"
  end

  return true
end

#check_registry(v) (private)

This method is for internal use only.

Raises:

(InvalidURIError)

[ GitHub ]

# File 'lib/uri/generic.rb', line 750


def check_registry(v) # :nodoc:
  raise InvalidURIError, "cannot set registry"
end

#check_scheme(v) (private)

Checks the scheme v component against the URI::Parser Regexp for :SCHEME.

[ GitHub ]

# File 'lib/uri/generic.rb', line 320


def check_scheme(v)
  if v && parser.regexp[:SCHEME] !~ v
    raise InvalidComponentError,
      "bad component(expected scheme component): #{v}"
  end

  return true
end

#check_user(v) (private)

Checks the user v component for RFC2396 compliance and against the URI::Parser Regexp for :USERINFO.

Can not have a registry or opaque component defined, with a user component defined.

[ GitHub ]

# File 'lib/uri/generic.rb', line 393


def check_user(v)
  if @opaque
    raise InvalidURIError,
      "cannot set user with opaque"
  end

  return v unless v

  if parser.regexp[:USERINFO] !~ v
    raise InvalidComponentError,
      "bad component(expected userinfo component or user component): #{v}"
  end

  return true
end

#check_userinfo(user, password = nil) (private)

Checks the #user and #password.

If #password is not provided, then #user is split, using #split_userinfo, to pull #user and +password.

#coerce(oth)

Args

v: URI or String

Description

Attempts to parse other ::URI oth, returns [parsed_oth, self].

Usage

require 'uri'

uri = URI.parse("http://my.example.com")
uri.coerce("http://foo.com")
#=> [#<URI::HTTP http://foo.com>, #<URI::HTTP http://my.example.com>]

[ GitHub ]

# File 'lib/uri/generic.rb', line 1478


def coerce(oth)
  case oth
  when String
    oth = parser.parse(oth)
  else
    super
  end

  return oth, self
end

#component

Components of the ::URI in the order.

[ GitHub ]

# File 'lib/uri/generic.rb', line 313


def component
  self.class.component
end

#component_ary (protected)

Returns an Array of the components defined from the COMPONENT Array.

[ GitHub ]

# File 'lib/uri/generic.rb', line 1420


def component_ary
  component.collect do |x|
    self.__send__(x)
  end
end

#decoded_password

Returns the password component after ::URI decoding.

[ GitHub ]

# File 'lib/uri/generic.rb', line 589


def decoded_password
  URI.decode_uri_component(@password) if @password
end

#decoded_user

Returns the user component after ::URI decoding.

[ GitHub ]

# File 'lib/uri/generic.rb', line 584


def decoded_user
  URI.decode_uri_component(@user) if @user
end

#default_port

Returns default port.

[ GitHub ]

# File 'lib/uri/generic.rb', line 39


def default_port
  self.class.default_port
end

#eql?(oth) ⇒ `Boolean`

Compares with oth for Hash.

[ GitHub ]

# File 'lib/uri/generic.rb', line 1413


def eql?(oth)
  self.class == oth.class &&
  parser == oth.parser &&
  self.component_ary.eql?(oth.component_ary)
end

#escape_userpass(v) (private)

Escapes ‘user:password’ v based on RFC 1738 section 3.1.

[ GitHub ]

# File 'lib/uri/generic.rb', line 551


def escape_userpass(v)
  parser.escape(v, /[@:\/]/o) # RFC 1738 section 3.1 #/
end

#find_proxy(env = ENV)

Returns a proxy ::URI. The proxy ::URI is obtained from environment variables such as http_proxy, ftp_proxy, no_proxy, etc. If there is no proper proxy, nil is returned.

If the optional parameter env is specified, it is used instead of ENV.

Note that capitalized variables (HTTP_PROXY, FTP_PROXY, NO_PROXY, etc.) are examined, too.

But http_proxy and HTTP_PROXY is treated specially under CGI environment. It’s because HTTP_PROXY may be set by Proxy: header. So HTTP_PROXY is not used. http_proxy is not used too if the variable is case insensitive. CGI_HTTP_PROXY can be used instead.

Raises:

(BadURIError)

[ GitHub ]

# File 'lib/uri/generic.rb', line 1504


def find_proxy(env=ENV)
  raise BadURIError, "relative URI: #{self}" if self.relative?
  name = self.scheme.downcase + '_proxy'
  proxy_uri = nil
  if name == 'http_proxy' && env.include?('REQUEST_METHOD') # CGI?
    # HTTP_PROXY conflicts with *_proxy for proxy settings and
    # HTTP_* for header information in CGI.
    # So it should be careful to use it.
    pairs = env.reject {|k, v| /\Ahttp_proxy\z/i !~ k }
    case pairs.length
    when 0 # no proxy setting anyway.
      proxy_uri = nil
    when 1
      k, _ = pairs.shift
      if k == 'http_proxy' && env[k.upcase] == nil
        # http_proxy is safe to use because ENV is case sensitive.
        proxy_uri = env[name]
      else
        proxy_uri = nil
      end
    else # http_proxy is safe to use because ENV is case sensitive.
      proxy_uri = env.to_hash[name]
    end
    if !proxy_uri
      # Use CGI_HTTP_PROXY.  cf. libwww-perl.
      proxy_uri = env["CGI_#{name.upcase}"]
    end
  elsif name == 'http_proxy'
    if RUBY_ENGINE == 'jruby' && p_addr = ENV_JAVA['http.proxyHost']
      p_port = ENV_JAVA['http.proxyPort']
      if p_user = ENV_JAVA['http.proxyUser']
        p_pass = ENV_JAVA['http.proxyPass']
        proxy_uri = "http://#{p_user}:#{p_pass}@#{p_addr}:#{p_port}"
      else
        proxy_uri = "http://#{p_addr}:#{p_port}"
      end
    else
      unless proxy_uri = env[name]
        if proxy_uri = env[name.upcase]
          warn 'The environment variable HTTP_PROXY is discouraged.  Use http_proxy.', uplevel: 1
        end
      end
    end
  else
    proxy_uri = env[name] || env[name.upcase]
  end

  if proxy_uri.nil? || proxy_uri.empty?
    return nil
  end

  if self.hostname
    begin
      addr = IPSocket.getaddress(self.hostname)
      return nil if /\A127\.|\A::1\z/ =~ addr
    rescue SocketError
    end
  end

  name = 'no_proxy'
  if no_proxy = env[name] || env[name.upcase]
    return nil unless URI::Generic.use_proxy?(self.hostname, addr, self.port, no_proxy)
  end
  URI.parse(proxy_uri)
end

#hash

Returns the hash value.

[ GitHub ]

# File 'lib/uri/generic.rb', line 1408


def hash
  self.component_ary.hash
end

#inspect

This method is for internal use only.

[ GitHub ]

# File 'lib/uri/generic.rb', line 1455


def inspect # :nodoc:
  "#<#{self.class} #{self}>"
end

#merge(oth) Also known as: #+

Args

oth: URI or String

Description

Merges two URIs.

Usage

require 'uri'

uri = URI.parse("http://my.example.com")
uri.merge("/main.rbx?page=1")
# => "http://my.example.com/main.rbx?page=1"

[ GitHub ]

# File 'lib/uri/generic.rb', line 1124


def merge(oth)
  rel = parser.__send__(:convert_to_uri, oth)

  if rel.absolute?
    #raise BadURIError, "both URI are absolute" if absolute?
    # hmm... should return oth for usability?
    return rel
  end

  unless self.absolute?
    raise BadURIError, "both URI are relative"
  end

  base = self.dup

  authority = rel.authority

  # RFC2396, Section 5.2, 2)
  if (rel.path.nil? || rel.path.empty?) && !authority && !rel.query
    base.fragment=(rel.fragment) if rel.fragment
    return base
  end

  base.query = nil
  base.fragment=(nil)

  # RFC2396, Section 5.2, 4)
  if authority
    base.set_authority(*authority)
    base.set_path(rel.path)
  elsif base.path && rel.path
    base.set_path(merge_path(base.path, rel.path))
  end

  # RFC2396, Section 5.2, 7)
  base.query = rel.query       if rel.query
  base.fragment=(rel.fragment) if rel.fragment

  return base
end

#merge!(oth)

Args

oth: URI or String

Description

Destructive form of #merge.

Usage

require 'uri'

uri = URI.parse("http://my.example.com")
uri.merge!("/main.rbx?page=1")
uri.to_s  # => "http://my.example.com/main.rbx?page=1"

[ GitHub ]

# File 'lib/uri/generic.rb', line 1096


def merge!(oth)
  t = merge(oth)
  if self == t
    nil
  else
    replace!(t)
    self
  end
end

#merge_path(base, rel) (private)

Merges a base path base, with relative path rel, returns a modified base path.

[ GitHub ]

# File 'lib/uri/generic.rb', line 1015


def merge_path(base, rel)

  # RFC2396, Section 5.2, 5)
  # RFC2396, Section 5.2, 6)
  base_path = split_path(base)
  rel_path  = split_path(rel)

  # RFC2396, Section 5.2, 6), a)
  base_path << '' if base_path.last == '..'
  while i = base_path.index('..')
    base_path.slice!(i - 1, 2)
  end

  if (first = rel_path.first) and first.empty?
    base_path.clear
    rel_path.shift
  end

  # RFC2396, Section 5.2, 6), c)
  # RFC2396, Section 5.2, 6), d)
  rel_path.push('') if rel_path.last == '.' || rel_path.last == '..'
  rel_path.delete('.')

  # RFC2396, Section 5.2, 6), e)
  tmp = []
  rel_path.each do |x|
    if x == '..' &&
        !(tmp.empty? || tmp.last == '..')
      tmp.pop
    else
      tmp << x
    end
  end

  add_trailer_slash = !tmp.empty?
  if base_path.empty?
    base_path = [''] # keep '/' for root directory
  elsif add_trailer_slash
    base_path.pop
  end
  while x = tmp.shift
    if x == '..'
      # RFC2396, Section 4
      # a .. or . in an absolute path has no special meaning
      base_path.pop if base_path.size > 1
    else
      # if x == '..'
      #   valid absolute (but abnormal) path "/../..."
      # else
      #   valid absolute path
      # end
      base_path << x
      tmp.each {|t| base_path << t}
      add_trailer_slash = false
      break
    end
  end
  base_path.push('') if add_trailer_slash

  return base_path.join('/')
end

#normalize

Returns normalized ::URI.

require 'uri'

URI("HTTP://my.EXAMPLE.com").normalize
#=> #<URI::HTTP http://my.example.com/>

Normalization here means:

scheme and host are converted to lowercase,
an empty path component is set to “/”.

[ GitHub ]

# File 'lib/uri/generic.rb', line 1331


def normalize
  uri = dup
  uri.normalize!
  uri
end

#normalize!

Destructive version of #normalize.

[ GitHub ]

# File 'lib/uri/generic.rb', line 1340


def normalize!
  if path&.empty?
    set_path('/')
  end
  if scheme && scheme != scheme.downcase
    set_scheme(self.scheme.downcase)
  end
  if host && host != host.downcase
    set_host(self.host.downcase)
  end
end

#parser

Returns the parser to be used.

Unless a URI::Parser is defined, DEFAULT_PARSER is used.

[ GitHub ]

# File 'lib/uri/generic.rb', line 289


def parser
  if !defined?(@parser) || !@parser
    DEFAULT_PARSER
  else
    @parser || DEFAULT_PARSER
  end
end

#replace!(oth) (private)

Replaces self by other ::URI object.

[ GitHub ]

# File 'lib/uri/generic.rb', line 299


def replace!(oth)
  if self.class != oth.class
    raise ArgumentError, "expected #{self.class} object"
  end

  component.each do |c|
    self.__send__("#{c}=", oth.__send__(c))
  end
end

#route_from(oth) Also known as: #-

Args

oth: URI or String

Description

Calculates relative path from oth to self.

Usage

require 'uri'

uri = URI.parse('http://my.example.com/main.rbx?page=1')
uri.route_from('http://my.example.com')
#=> #<URI::Generic /main.rbx?page=1>

[ GitHub ]

# File 'lib/uri/generic.rb', line 1274


def route_from(oth)
  # you can modify `rel', but cannot `oth'.
  begin
    oth, rel = route_from0(oth)
  rescue
    raise $!.class, $!.message
  end
  if oth == rel
    return rel
  end

  rel.set_path(route_from_path(oth.path, self.path))
  if rel.path == './' && self.query
    # "./?foo" -> "?foo"
    rel.set_path('')
  end

  return rel
end

#route_from0(oth) (private)

[ GitHub ]

# File 'lib/uri/generic.rb', line 1206


def route_from0(oth)
  oth = parser.__send__(:convert_to_uri, oth)
  if self.relative?
    raise BadURIError,
      "relative URI: #{self}"
  end
  if oth.relative?
    raise BadURIError,
      "relative URI: #{oth}"
  end

  if self.scheme != oth.scheme
    return self, self.dup
  end
  rel = URI::Generic.new(nil, # it is relative URI
                         self.userinfo, self.host, self.port,
                         nil, self.path, self.opaque,
                         self.query, self.fragment, parser)

  if rel.userinfo != oth.userinfo ||
      rel.host.to_s.downcase != oth.host.to_s.downcase ||
      rel.port != oth.port

    if self.userinfo.nil? && self.host.nil?
      return self, self.dup
    end

    rel.set_port(nil) if rel.port == oth.default_port
    return rel, rel
  end
  rel.set_userinfo(nil)
  rel.set_host(nil)
  rel.set_port(nil)

  if rel.path && rel.path == oth.path
    rel.set_path('')
    rel.query = nil if rel.query == oth.query
    return rel, rel
  elsif rel.opaque && rel.opaque == oth.opaque
    rel.set_opaque('')
    rel.query = nil if rel.query == oth.query
    return rel, rel
  end

  # you can modify `rel', but cannot `oth'.
  return oth, rel
end

#route_from_path(src, dst) (private)

This method is for internal use only.

[ GitHub ]

# File 'lib/uri/generic.rb', line 1167


def route_from_path(src, dst)
  case dst
  when src
    # RFC2396, Section 4.2
    return ''
  when %r{(?:\A|/)\.\.?(?:/|\z)}
    # dst has abnormal absolute path,
    # like "/./", "/../", "/x/../", ...
    return dst.dup
  end

  src_path = src.scan(%r{[^/]*/})
  dst_path = dst.scan(%r{[^/]*/?})

  # discard same parts
  while !dst_path.empty? && dst_path.first == src_path.first
    src_path.shift
    dst_path.shift
  end

  tmp = dst_path.join

  # calculate
  if src_path.empty?
    if tmp.empty?
      return './'
    elsif dst_path.first.include?(':') # (see RFC2396 Section 5)
      return './' + tmp
    else
      return tmp
    end
  end

  return '../' * src_path.size + tmp
end

#route_to(oth)

Args

oth: URI or String

Description

Calculates relative path to oth from self.

Usage

require 'uri'

uri = URI.parse('http://my.example.com')
uri.route_to('http://my.example.com/main.rbx?page=1')
#=> #<URI::Generic /main.rbx?page=1>

[ GitHub ]

# File 'lib/uri/generic.rb', line 1314


def route_to(oth)
  parser.__send__(:convert_to_uri, oth).route_from(self)
end

#select(*components)

Args

components: Multiple Symbol arguments defined in URI::HTTP.

Description

Selects specified components from ::URI.

Usage

require 'uri'

uri = URI.parse('http://myuser:mypass@my.example.com/test.rbx')
uri.select(:userinfo, :host, :path)
# => ["myuser:mypass", "my.example.com", "/test.rbx"]

[ GitHub ]

# File 'lib/uri/generic.rb', line 1444


def select(*components)
  components.collect do |c|
    if component.include?(c)
      self.__send__(c)
    else
      raise ArgumentError,
        "expected of components of #{self.class} (#{self.class.component.join(', ')})"
    end
  end
end

#set_authority(user, password, host, port = nil) (protected)

Protected setter for the authority info (#user, #password, #host and #port). If #port is nil, .default_port will be set.

[ GitHub ]

# File 'lib/uri/generic.rb', line 627


protected def set_authority(user, password, host, port = nil)
  @user, @password, @host, @port = user, password, host, port || self.default_port
end

#set_host(v) (protected)

Protected setter for the host component v.

#set_opaque(v) (protected)

Protected setter for the opaque component v.

#set_password(v) (protected)

Protected setter for the password component v.

#set_path(v) (protected)

Protected setter for the path component v.

#set_port(v) (protected)

Protected setter for the port component v.

#set_registry(v) (protected)

This method is for internal use only.

Raises:

(InvalidURIError)

[ GitHub ]

# File 'lib/uri/generic.rb', line 755


def set_registry(v) # :nodoc:
  raise InvalidURIError, "cannot set registry"
end

#set_scheme(v) (protected)

Protected setter for the scheme component v.

#set_user(v) (protected)

Protected setter for the user component v.

#set_userinfo(user, password = nil) (protected)

Protected setter for the #user component, and #password if available (with validation).

#split_path(path) (private)

Returns an Array of the path split on ‘/’.

[ GitHub ]

# File 'lib/uri/generic.rb', line 1006


def split_path(path)
  path.split("/", -1)
end

#split_userinfo(ui) (private)

Returns the userinfo ui as [user, password] if properly formatted as ‘user:password’.

[ GitHub ]

# File 'lib/uri/generic.rb', line 542


def split_userinfo(ui)
  return nil, nil unless ui
  user, password = ui.split(':', 2)

  return user, password
end

#to_s Also known as: #to_str

Constructs String from ::URI.

[ GitHub ]

# File 'lib/uri/generic.rb', line 1355


def to_s
  str = ''.dup
  if @scheme
    str << @scheme
    str << ':'
  end

  if @opaque
    str << @opaque
  else
    if @host || %w[file postgres].include?(@scheme)
      str << '//'
    end
    if self.userinfo
      str << self.userinfo
      str << '@'
    end
    if @host
      str << @host
    end
    if @port && @port != self.default_port
      str << ':'
      str << @port.to_s
    end
    if (@host || @port) && !@path.empty? && !@path.start_with?('/')
      str << '/'
    end
    str << @path
    if @query
      str << '?'
      str << @query
    end
  end
  if @fragment
    str << '#'
    str << @fragment
  end
  str
end

#to_str

Alias for #to_s.

[ GitHub ]

# File 'lib/uri/generic.rb', line 1394


alias to_str to_s

Class: URI::Generic

Overview

Constant Summary

::URI - Included

Class Method Summary

Instance Attribute Summary

Instance Method Summary

Constructor Details

.new(scheme, userinfo, host, port, registry, path, opaque, query, fragment, parser = DEFAULT_PARSER, arg_check = false) ⇒ Generic

Args

Description

Class Method Details

.build(args)

Synopsis

Description

.build2(args)

Synopsis

Description

.component

.default_port

.use_proxy?(hostname, addr, port, no_proxy) ⇒ Boolean

.use_registry

Instance Attribute Details

#absolute (readonly)

#fragment (rw)

#fragment=(v) (rw)

Args

Description

Usage

#hierarchical? ⇒ Boolean (readonly)

Description

Usage

#host (rw)

#host=(v) (rw)

Args

Description

Usage

#hostname (rw)

#hostname=(v) (rw)

#opaque (rw)

#opaque=(v) (rw)

Args

Description

#password (rw)

#password=(password) (rw)

Args

Description

Usage

#path (rw)

#path=(v) (rw)

Args

Description

Usage

#port (rw)

#port=(v) (rw)

Args

Description

Usage

#query (rw)

#query=(v) (rw)

Args

Description

Usage

#registry (rw)

#registry=(v) (rw)

#relative? ⇒ Boolean (readonly)

#scheme (rw)

#scheme=(v) (rw)

Args

Description

Usage

#user (rw)

#user=(user) (rw)

Args

Description

Usage

#userinfo (rw)

#userinfo=(userinfo) (rw)

Instance Method Details

#+(oth)

`::URI` - Included

.new(scheme, userinfo, host, port, registry, path, opaque, query, fragment, parser = DEFAULT_PARSER, arg_check = false) ⇒ `Generic`

.use_proxy?(hostname, addr, port, no_proxy) ⇒ `Boolean`

#hierarchical? ⇒ `Boolean` (readonly)

#relative? ⇒ `Boolean` (readonly)

#absolute? ⇒ `Boolean` (readonly) Also known as: #absolute

#eql?(oth) ⇒ `Boolean`