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

Methods
#
A
B
C
D
E
F
H
I
M
N
O
P
Q
R
S
T
U
Included Modules
Constants
DEFAULT_PORT = nil
 

A Default port of nil for URI::Generic

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

An Array of the available components for URI::Generic

USE_REGISTRY = false
 

Default to not use the registry for a URI::Generic

Attributes
[R] fragment

returns the fragment component of the URI.

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

returns the host component of the URI.

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

It returns nil if no host component.

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

The component doesn't contains the port number.

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

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

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

returns the opaque part of the URI.

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

Portion of the path that does make use of the slash '/'. The path typically refers to the absolute path and the opaque part.

(see RFC2396 Section 3 and 5.2)
[R] path

returns the path component of the URI.

URI("http://foo/bar/baz").path #=> "/bar/baz"
[R] port

returns the port component of the URI.

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

URI("http://foo:8080/bar/baz").port #=> "8080"
[R] query

returns the query component of the URI.

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

returns the registry component of the URI.

(see RFC2396 Section 3.2)
[R] scheme

returns the scheme component of the URI.

URI("http://foo/bar/baz").scheme #=> "http"
Class Public methods
build(args)

Synopsis

See new

Description

Creates a new URI::Generic instance from components of URI::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.

# File lib/uri/generic.rb, line 121
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 URI::Generic instance using ::build. But, if exception URI::InvalidComponentError is raised, then it URI::Escape#escape all URI components and tries again.

# File lib/uri/generic.rb, line 83
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)
          DEFAULT_PARSER.escape(x)
        else
          x
        end
      })
    elsif args.kind_of?(Hash)
      tmp = {}
      args.each do |key, value|
        tmp[key] = if value
            DEFAULT_PARSER.escape(value)
          else
            value
          end
      end
      return self.build(tmp)
    end
  end
end
component()

Components of the URI in the order.

# File lib/uri/generic.rb, line 54
def self.component
  self::COMPONENT
end
default_port()

Returns default port

# File lib/uri/generic.rb, line 29
def self.default_port
  self::DEFAULT_PORT
end
new(scheme, userinfo, host, port, registry, path, opaque, query, fragment, parser = DEFAULT_PARSER, arg_check = false)

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

A part of URI after '#' sign

parser

Parser for internal use [URI::DEFAULT_PARSER by default]

arg_check

Check arguments [false by default]

Description

Creates a new URI::Generic instance from “generic'' components without check.

# File lib/uri/generic.rb, line 173
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
  @registry = nil
  @fragment = nil
  @parser = parser == DEFAULT_PARSER ? nil : parser

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

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

Returns whether a registry of naming authorities are being used.

# File lib/uri/generic.rb, line 67
def self.use_registry
  self::USE_REGISTRY
end
Instance Public methods
+(oth)
Alias for: merge
-(oth)
Alias for: route_from
==(oth)

Compares to URI's

# File lib/uri/generic.rb, line 1498
def ==(oth)
  if self.class == oth.class
    self.normalize.component_ary == oth.normalize.component_ary
  else
    false
  end
end
absolute()
Alias for: absolute?
absolute?()

Checks if URI is an absolute one

Also aliased as: absolute
# File lib/uri/generic.rb, line 1061
def absolute?
  if @scheme
    true
  else
    false
  end
end
coerce(oth)

Args

v

URI or String

Description

attempt to parse other URI +oth+
return [parsed_oth, self]

Usage

require 'uri'

uri = URI.parse("http://my.example.com")
uri.coerce("http://foo.com")
#=> [#<URI::HTTP:0x00000000bcb028 URL:http://foo.com/>, #<URI::HTTP:0x00000000d92178 URL:http://my.example.com>]
# File lib/uri/generic.rb, line 1589
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.

# File lib/uri/generic.rb, line 321
def component
  self.class.component
end
default_port()

Returns default port

# File lib/uri/generic.rb, line 36
def default_port
  self.class.default_port
end
eql?(oth)
# File lib/uri/generic.rb, line 1510
def eql?(oth)
  self.class == oth.class &&
  parser == oth.parser &&
  self.component_ary.eql?(oth.component_ary)
end
find_proxy()

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.

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.

# File lib/uri/generic.rb, line 1613
def find_proxy
  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'
    unless proxy_uri = ENV[name]
      if proxy_uri = ENV[name.upcase]
        warn 'The environment variable HTTP_PROXY is discouraged.  Use http_proxy.'
      end
    end
  else
    proxy_uri = ENV[name] || ENV[name.upcase]
  end

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

  if self.hostname
    require 'socket'
    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]
    no_proxy.scan(/([^:,]*)(?::(\d+))?/) {|host, port|
      if /(\A|\.)#{Regexp.quote host}\z/i =~ self.host &&
        (!port || self.port == port.to_i)
        return nil
      end
    }
  end
  URI.parse(proxy_uri)
end
fragment=(v)

Args

v

String

Description

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

see also URI::Generic.check_fragment

Usage

require 'uri'

uri = URI.parse("http://my.example.com/?id=25#time=1305212049")
uri.fragment = "time=1305212086"
# =>  "time=1305212086"
uri
#=> #<URI::HTTP:0x000000007a81f8 URL:http://my.example.com/?id=25#time=1305212086>
# File lib/uri/generic.rb, line 1041
def fragment=(v)
  check_fragment(v)
  set_fragment(v)
  v
end
hash()
# File lib/uri/generic.rb, line 1506
def hash
  self.component_ary.hash
end
hierarchical?()

Checks if URI has a path

# File lib/uri/generic.rb, line 1050
def hierarchical?
  if @path
    true
  else
    false
  end
end
host=(v)

Args

v

String

Description

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

see also URI::Generic.check_host

Usage

require 'uri'

uri = URI.parse("http://my.example.com")
uri.host = "foo.com"
# =>  "foo.com"
uri
#=> #<URI::HTTP:0x000000008e89e8 URL:http://foo.com>
# File lib/uri/generic.rb, line 645
def host=(v)
  check_host(v)
  set_host(v)
  v
end
hostname()

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

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

u = URI(“http://[::1]/bar”) p u.hostname #=> “::1” p u.host #=> “[::1]”

# File lib/uri/generic.rb, line 660
def hostname
  v = self.host
  /\A\[(.*)\]\z/ =~ v ? $1 : v
end
hostname=(v)

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

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

u = URI(“foo/bar”) p u.to_s #=> “foo/bar” u.hostname = “::1” p u.to_s #=> “[::1]/bar

If the arugument seems IPv6 address, it is wrapped by brackets.

# File lib/uri/generic.rb, line 678
def hostname=(v)
  v = "[#{v}]" if /\A\[.*\]\z/ !~ v && /:/ =~ v
  self.host = v
end
inspect()
# File lib/uri/generic.rb, line 1566
def inspect
  @@to_s.bind(self).call.sub!(/>\z/) {" URL:#{self}>"}
end
merge(oth)

Args

oth

URI or String

Description

Merges two URI's.

Usage

require 'uri'

uri = URI.parse("http://my.example.com")
p uri.merge("/main.rbx?page=1")
# =>  #<URI::HTTP:0x2021f3b0 URL:http://my.example.com/main.rbx?page=1>
Also aliased as: +
# File lib/uri/generic.rb, line 1199
def merge(oth)
  begin
    base, rel = merge0(oth)
  rescue
    raise $!.class, $!.message
  end

  if base == rel
    return base
  end

  authority = rel.userinfo || rel.host || rel.port

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

  base.set_query(nil)
  base.set_fragment(nil)

  # RFC2396, Section 5.2, 4)
  if !authority
    base.set_path(merge_path(base.path, rel.path)) if base.path && rel.path
  else
    # RFC2396, Section 5.2, 4)
    base.set_path(rel.path) if rel.path
  end

  # RFC2396, Section 5.2, 7)
  base.set_userinfo(rel.userinfo) if rel.userinfo
  base.set_host(rel.host)         if rel.host
  base.set_port(rel.port)         if rel.port
  base.set_query(rel.query)       if rel.query
  base.set_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")
p uri
# =>  #<URI::HTTP:0x2021f3b0 URL:http://my.example.com/main.rbx?page=1>
# File lib/uri/generic.rb, line 1171
def merge!(oth)
  t = merge(oth)
  if self == t
    nil
  else
    replace!(t)
    self
  end
end
normalize()

Returns normalized URI

# File lib/uri/generic.rb, line 1420
def normalize
  uri = dup
  uri.normalize!
  uri
end
normalize!()

Destructive version of normalize

# File lib/uri/generic.rb, line 1429
def normalize!
  if path && path == ''
    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
opaque=(v)

Args

v

String

Description

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

see also URI::Generic.check_opaque

# File lib/uri/generic.rb, line 988
def opaque=(v)
  check_opaque(v)
  set_opaque(v)
  v
end
parser()

returns the parser to be used.

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

# File lib/uri/generic.rb, line 298
def parser
  if !defined?(@parser) || !@parser
    DEFAULT_PARSER
  else
    @parser || DEFAULT_PARSER
  end
end
password()

returns the password component

# File lib/uri/generic.rb, line 587
def password
  @password
end
password=(password)

Args

v

String

Description

public setter for the password component. (with validation)

see also URI::Generic.check_password

Usage

require 'uri'

uri = URI.parse("http://john:S3nsit1ve@my.example.com")
uri.password = "V3ry_S3nsit1ve"
# =>  "V3ry_S3nsit1ve"
uri
#=> #<URI::HTTP:0x00000000881d90 URL:http://john:V3ry_S3nsit1ve@my.example.com>
# File lib/uri/generic.rb, line 512
def password=(password)
  check_password(password)
  set_password(password)
  # returns password
end
path=(v)

Args

v

String

Description

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

see also URI::Generic.check_path

Usage

require 'uri'

uri = URI.parse("http://my.example.com/pub/files")
uri.path = "/faq/"
# =>  "/faq/"
uri
#=> #<URI::HTTP:0x000000008e89e8 URL:http://my.example.com/faq/>
# File lib/uri/generic.rb, line 870
def path=(v)
  check_path(v)
  set_path(v)
  v
end
port=(v)

Args

v

String

Description

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

see also URI::Generic.check_port

Usage

require 'uri'

uri = URI.parse("http://my.example.com")
uri.port = 8080
# =>  8080
uri
#=> #<URI::HTTP:0x000000008e89e8 URL:http://my.example.com:8080>
# File lib/uri/generic.rb, line 744
def port=(v)
  check_port(v)
  set_port(v)
  port
end
query=(v)

Args

v

String

Description

public setter for the query component v. (with validation)

see also URI::Generic.check_query

Usage

require 'uri'

uri = URI.parse("http://my.example.com/?id=25")
uri.query = "id=1"
# =>  "id=1"
uri
#=> #<URI::HTTP:0x000000008e89e8 URL:http://my.example.com/?id=1>
# File lib/uri/generic.rb, line 935
def query=(v)
  check_query(v)
  set_query(v)
  v
end
registry=(v)

Args

v

String

Description

public setter for the registry component v. (with validation)

see also URI::Generic.check_registry

# File lib/uri/generic.rb, line 797
def registry=(v)
  check_registry(v)
  set_registry(v)
  v
end
relative?()

Checks if URI is relative

# File lib/uri/generic.rb, line 1073
def relative?
  !absolute?
end
route_from(oth)

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')
p uri.route_from('http://my.example.com')
#=> #<URI::Generic:0x20218858 URL:/main.rbx?page=1>
Also aliased as: -
# File lib/uri/generic.rb, line 1373
def route_from(oth)
  # you can modify `rel', but can not `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_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')
p uri.route_to('http://my.example.com/main.rbx?page=1')
#=> #<URI::Generic:0x2020c2f6 URL:/main.rbx?page=1>
# File lib/uri/generic.rb, line 1413
def route_to(oth)
  parser.send(:convert_to_uri, oth).route_from(self)
end
scheme=(v)

Args

v

String

Description

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

see also URI::Generic.check_scheme

Usage

require 'uri'

uri = URI.parse("http://my.example.com")
uri.scheme = "https"
# =>  "https"
uri
#=> #<URI::HTTP:0x000000008e89e8 URL:https://my.example.com>
# File lib/uri/generic.rb, line 370
def scheme=(v)
  check_scheme(v)
  set_scheme(v)
  v
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')
p uri.select(:userinfo, :host, :path)
# => ["myuser:mypass", "my.example.com", "/test.rbx"]
# File lib/uri/generic.rb, line 1554
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
to_s()

Constructs String from URI

# File lib/uri/generic.rb, line 1454
def to_s
  str = ''
  if @scheme
    str << @scheme
    str << ':'
  end

  if @opaque
    str << @opaque

  else
    if @registry
      str << @registry
    else
      if @host
        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
    end

    str << path_query
  end

  if @fragment
    str << '#'
    str << @fragment
  end

  str
end
user()

returns the user component

# File lib/uri/generic.rb, line 582
def user
  @user
end
user=(user)

Args

v

String

Description

public setter for the user component. (with validation)

see also URI::Generic.check_user

Usage

require 'uri'

uri = URI.parse("http://john:S3nsit1ve@my.example.com")
uri.user = "sam"
# =>  "sam"
uri
#=> #<URI::HTTP:0x00000000881d90 URL:http://sam:V3ry_S3nsit1ve@my.example.com>
# File lib/uri/generic.rb, line 483
def user=(user)
  check_user(user)
  set_user(user)
  # returns user
end
userinfo()

returns the userinfo, either as 'user' or 'user:password'

# File lib/uri/generic.rb, line 571
def userinfo
  if @user.nil?
    nil
  elsif @password.nil?
    @user
  else
    @user + ':' + @password
  end
end
userinfo=(userinfo)

Sets userinfo, argument is string like 'name:pass'

# File lib/uri/generic.rb, line 451
def userinfo=(userinfo)
  if userinfo.nil?
    return nil
  end
  check_userinfo(*userinfo)
  set_userinfo(*userinfo)
  # returns userinfo
end
Instance Protected methods
component_ary()

returns an Array of the components defined from the COMPONENT Array

# File lib/uri/generic.rb, line 1530
def component_ary
  component.collect do |x|
    self.send(x)
  end
end
set_fragment(v)

protected setter for the fragment component v

see also #fragment=

# File lib/uri/generic.rb, line 1013
def set_fragment(v)
  @fragment = v
end
set_host(v)

protected setter for the host component v

see also #host=

# File lib/uri/generic.rb, line 617
def set_host(v)
  @host = v
end
set_opaque(v)

protected setter for the opaque component v

see also #opaque=

# File lib/uri/generic.rb, line 970
def set_opaque(v)
  @opaque = v
end
set_password(v)

protected setter for the password component v

see also #password=

# File lib/uri/generic.rb, line 548
def set_password(v)
  @password = v
  # returns v
end
set_path(v)

protected setter for the path component v

see also #path=

# File lib/uri/generic.rb, line 842
def set_path(v)
  @path = v
end
set_port(v)

protected setter for the port component v

see also #port=

# File lib/uri/generic.rb, line 709
def set_port(v)
  unless !v || v.kind_of?(Fixnum)
    if v.empty?
      v = nil
    else
      v = v.to_i
    end
  end
  @port = v
end
set_query(v)

protected setter for the query component v

see also #query=

# File lib/uri/generic.rb, line 907
def set_query(v)
  @query = v
end
set_registry(v)

protected setter for the registry component v

see also #registry=

# File lib/uri/generic.rb, line 779
def set_registry(v)
  @registry = v
end
set_scheme(v)

protected setter for the scheme component v

see also #scheme=

# File lib/uri/generic.rb, line 342
def set_scheme(v)
  @scheme = v ? v.downcase : v
end
set_user(v)

protected setter for the user component v

see also #user=

# File lib/uri/generic.rb, line 538
def set_user(v)
  set_userinfo(v, @password)
  v
end
set_userinfo(user, password = nil)

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

see also #userinfo=

# File lib/uri/generic.rb, line 523
def set_userinfo(user, password = nil)
  unless password
    user, password = split_userinfo(user)
  end
  @user     = user
  @password = password if password

  [@user, @password]
end