URI::Generic

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

Constants

COMPONENT
DEFAULT_PORT
USE_REGISTRY

Attributes

fragment[R]

host[R]

opaque[R]

parser[R]

path[R]

port[R]

query[R]

registry[R]

scheme[R]

Public Class Methods

build(args) click to toggle source

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 uri/generic.rb, line 107
def self.build(args)
  if args.kind_of?(Array) &&
      args.size == ::URI::Generic::COMPONENT.size
    tmp = args
  elsif args.kind_of?(Hash)
    tmp = ::URI::Generic::COMPONENT.collect do |c|
      if args.include?(c)
        args[c]
      else
        nil
      end
    end
  else
    raise ArgumentError, 
    "expected Array of or Hash of components of #{self.class} (#{self.class.component.join(', ')})"
  end

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

build2(args) click to toggle source

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 uri/generic.rb, line 69
def self.build2(args)
  begin
    return self.build(args)
  rescue InvalidComponentError
    if args.kind_of?(Array)
      return self.build(args.collect{|x| 
        if x
          @parser.escape(x)
        else
          x
        end
      })
    elsif args.kind_of?(Hash)
      tmp = {}
      args.each do |key, value|
        tmp[key] = if value
            @parser.escape(value)
          else
            value
          end
      end
      return self.build(tmp)
    end
  end
end

component() click to toggle source

Components of the URI in the order.

 
               # File uri/generic.rb, line 44
def self.component
  self::COMPONENT
end

default_port() click to toggle source

Returns default port

 
               # File uri/generic.rb, line 25
def self.default_port
  self::DEFAULT_PORT
end

new(scheme, userinfo, host, port, registry, path, opaque, query, fragment, parser = DEFAULT_PARSER, arg_check = false) click to toggle source

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: DOC: FIXME!
path: Path on server
opaque: DOC: FIXME!
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 uri/generic.rb, line 158
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

  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() click to toggle source

DOC: FIXME!

 
               # File uri/generic.rb, line 53
def self.use_registry
  self::USE_REGISTRY
end

Public Instance Methods

+(oth) click to toggle source

Alias for: merge

-(oth) click to toggle source

Alias for: route_from

==(oth) click to toggle source

Compares to URI’s

 
               # File uri/generic.rb, line 1049
def ==(oth)
  if self.class == oth.class
    self.normalize.component_ary == oth.normalize.component_ary
  else
    false
  end
end

absolute() click to toggle source

Alias for: absolute?

absolute?() click to toggle source

Checks if URI is an absolute one

 
               # File uri/generic.rb, line 602
def absolute?
  if @scheme
    true
  else
    false
  end
end

Also aliased as: absolute

coerce(oth) click to toggle source

 
               # File uri/generic.rb, line 1117
def coerce(oth)
  case oth
  when String
    oth = @parser.parse(oth)
  else
    super
  end

  return oth, self
end

component() click to toggle source

 
               # File uri/generic.rb, line 229
def component
  self.class.component
end

default_port() click to toggle source

 
               # File uri/generic.rb, line 29
def default_port
  self.class.default_port
end

eql?(oth) click to toggle source

 
               # File uri/generic.rb, line 1061
def eql?(oth)
  @parser == oth.parser &&
  self.component_ary.eql?(oth.component_ary)
end

fragment=(v) click to toggle source

 
               # File uri/generic.rb, line 582
def fragment=(v)
  check_fragment(v)
  set_fragment(v)
  v
end

hash() click to toggle source

 
               # File uri/generic.rb, line 1057
def hash
  self.component_ary.hash
end

hierarchical?() click to toggle source

Checks if URI has a path

 
               # File uri/generic.rb, line 591
def hierarchical?
  if @path
    true
  else
    false
  end
end

host=(v) click to toggle source

 
               # File uri/generic.rb, line 401
def host=(v)
  check_host(v)
  set_host(v)
  v
end

inspect() click to toggle source

 
               # File uri/generic.rb, line 1113
def inspect
  @@to_s.bind(self).call.sub!(/>\z/) {" URL:#{self}>"}
end

merge(oth) click to toggle source

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>

 
               # File uri/generic.rb, line 733
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

Also aliased as: +

merge!(oth) click to toggle source

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 uri/generic.rb, line 705
def merge!(oth)
  t = merge(oth)
  if self == t
    nil
  else
    replace!(t)
    self
  end
end

normalize() click to toggle source

Returns normalized URI

 
               # File uri/generic.rb, line 975
def normalize
  uri = dup
  uri.normalize!
  uri
end

normalize!() click to toggle source

Destructive version of normalize

 
               # File uri/generic.rb, line 984
def normalize!
  if path && path == ''
    set_path('/')
  end
  if host && host != host.downcase
    set_host(self.host.downcase)
  end        
end

opaque=(v) click to toggle source

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

password() click to toggle source

 
               # File uri/generic.rb, line 377
def password
  @password
end

password=(password) click to toggle source

 
               # File uri/generic.rb, line 321
def password=(password)
  check_password(password)
  set_password(password)
  # returns password
end

path=(v) click to toggle source

 
               # File uri/generic.rb, line 499
def path=(v)
  check_path(v)
  set_path(v)
  v
end

port=(v) click to toggle source

 
               # File uri/generic.rb, line 434
def port=(v)
  check_port(v)
  set_port(v)
  port
end

query=(v) click to toggle source

 
               # File uri/generic.rb, line 530
def query=(v)
  check_query(v)
  set_query(v)
  v
end

registry=(v) click to toggle source

 
               # File uri/generic.rb, line 463
def registry=(v)
  check_registry(v)
  set_registry(v)
  v
end

relative?() click to toggle source

Checks if URI is relative

 
               # File uri/generic.rb, line 614
def relative?
  !absolute?
end

route_from(oth) click to toggle source

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>

 
               # File uri/generic.rb, line 919
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

Also aliased as: -

route_to(oth) click to toggle source

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 uri/generic.rb, line 959
def route_to(oth)
  case oth
  when Generic
  when String
    oth = @parser.parse(oth)
  else
    raise ArgumentError,
      "bad argument(expected URI object or URI string)"
  end

  oth.route_from(self)
end

scheme=(v) click to toggle source

 
               # File uri/generic.rb, line 248
def scheme=(v)
  check_scheme(v)
  set_scheme(v)
  v
end

select(*components) click to toggle source

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 uri/generic.rb, line 1101
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() click to toggle source

Constructs String from URI

 
               # File uri/generic.rb, line 1005
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() click to toggle source

 
               # File uri/generic.rb, line 373
def user
  @user
end

user=(user) click to toggle source

 
               # File uri/generic.rb, line 315
def user=(user)
  check_user(user)
  set_user(user)
  # returns user
end

userinfo() click to toggle source

 
               # File uri/generic.rb, line 363
def userinfo
  if @user.nil?
    nil
  elsif @password.nil?
    @user
  else
    @user + ':' + @password
  end
end

userinfo=(userinfo) click to toggle source

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

 
               # File uri/generic.rb, line 306
def userinfo=(userinfo)
  if userinfo.nil?
    return nil
  end
  check_userinfo(*userinfo)
  set_userinfo(*userinfo)
  # returns userinfo
end

Protected Instance Methods

component_ary() click to toggle source

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

set_fragment(v) click to toggle source

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

set_host(v) click to toggle source

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

set_opaque(v) click to toggle source

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

set_password(v) click to toggle source

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

set_path(v) click to toggle source

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

set_port(v) click to toggle source

 
               # File uri/generic.rb, line 422
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) click to toggle source

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

set_registry(v) click to toggle source

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

set_scheme(v) click to toggle source

 
               # File uri/generic.rb, line 243
def set_scheme(v)
  @scheme = v
end

set_user(v) click to toggle source

 
               # File uri/generic.rb, line 338
def set_user(v)
  set_userinfo(v, @password)
  v
end

set_userinfo(user, password = nil) click to toggle source

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

  [@user, @password]
end

Commenting is here to help enhance the documentation. For example, code samples, or clarification of the documentation.

If you have questions about Ruby or the documentation, please post to one of the Ruby mailing lists. You will get better, faster, help that way.

If you wish to post a correction of the docs, please do so, but also file bug report so that it can be corrected for the next release. Thank you.

If you want to help improve the Ruby documentation, please visit Documenting-ruby.org.

Home Classes Methods

In Files

Parent

Methods

Included Modules

Class/Module Index

URI::Generic

Constants

Attributes

Public Class Methods

Synopsis¶ ↑

Description¶ ↑

Synopsis¶ ↑

Description¶ ↑

Args¶ ↑

Description¶ ↑

Public Instance Methods

Args¶ ↑

Description¶ ↑

Usage¶ ↑

Args¶ ↑

Description¶ ↑

Usage¶ ↑

Args¶ ↑

Description¶ ↑

Usage¶ ↑

Args¶ ↑

Description¶ ↑

Usage¶ ↑

Args¶ ↑

Description¶ ↑

Usage¶ ↑

Protected Instance Methods