Extended maintenance of Ruby versions 1.8.7 and 1.9.2 will end on July 31, 2014. Read more

In Files

  • uri/generic.rb

URI::Generic

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

Attributes

fragment[R]
host[R]
opaque[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 << nil
  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 == 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() 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 1057
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 611
def absolute?
  if @scheme
    true
  else
    false
  end
end
            
Also aliased as: absolute
coerce(oth) click to toggle source
 
               # File uri/generic.rb, line 1126
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 236
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 1069
def eql?(oth)
  self.class == oth.class &&
  parser == oth.parser &&
  self.component_ary.eql?(oth.component_ary)
end
            
fragment=(v) click to toggle source
 
               # File uri/generic.rb, line 591
def fragment=(v)
  check_fragment(v)
  set_fragment(v)
  v
end
            
hash() click to toggle source
 
               # File uri/generic.rb, line 1065
def hash
  self.component_ary.hash
end
            
hierarchical?() click to toggle source

Checks if URI has a path

 
               # File uri/generic.rb, line 600
def hierarchical?
  if @path
    true
  else
    false
  end
end
            
host=(v) click to toggle source
 
               # File uri/generic.rb, line 408
def host=(v)
  check_host(v)
  set_host(v)
  v
end
            
inspect() click to toggle source
 
               # File uri/generic.rb, line 1122
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 742
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 714
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 980
def normalize
  uri = dup
  uri.normalize!
  uri
end
            
normalize!() click to toggle source

Destructive version of normalize

 
               # File uri/generic.rb, line 989
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) click to toggle source
 
               # File uri/generic.rb, line 568
def opaque=(v)
  check_opaque(v)
  set_opaque(v)
  v
end
            
parser() click to toggle source
 
               # File uri/generic.rb, line 216
def parser
  if !defined?(@parser) || !@parser
    DEFAULT_PARSER
  else
    @parser || DEFAULT_PARSER
  end
end
            
password() click to toggle source
 
               # File uri/generic.rb, line 384
def password
  @password
end
            
password=(password) click to toggle source
 
               # File uri/generic.rb, line 328
def password=(password)
  check_password(password)
  set_password(password)
  # returns password
end
            
path=(v) click to toggle source
 
               # File uri/generic.rb, line 508
def path=(v)
  check_path(v)
  set_path(v)
  v
end
            
port=(v) click to toggle source
 
               # File uri/generic.rb, line 441
def port=(v)
  check_port(v)
  set_port(v)
  port
end
            
query=(v) click to toggle source
 
               # File uri/generic.rb, line 539
def query=(v)
  check_query(v)
  set_query(v)
  v
end
            
registry=(v) click to toggle source
 
               # File uri/generic.rb, line 470
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 623
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 924
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 964
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 255
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 1110
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 1013
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 380
def user
  @user
end
            
user=(user) click to toggle source
 
               # File uri/generic.rb, line 322
def user=(user)
  check_user(user)
  set_user(user)
  # returns user
end
            
userinfo() click to toggle source
 
               # File uri/generic.rb, line 370
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 313
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 1086
def component_ary
  component.collect do |x|
    self.send(x)
  end
end
            
set_fragment(v) click to toggle source
 
               # File uri/generic.rb, line 586
def set_fragment(v)
  @fragment = v
end
            
set_host(v) click to toggle source
 
               # File uri/generic.rb, line 403
def set_host(v)
  @host = v
end
            
set_opaque(v) click to toggle source
 
               # File uri/generic.rb, line 563
def set_opaque(v)
  @opaque = v
end
            
set_password(v) click to toggle source
 
               # File uri/generic.rb, line 351
def set_password(v)
  @password = v
  # returns v
end
            
set_path(v) click to toggle source
 
               # File uri/generic.rb, line 503
def set_path(v)
  @path = v
end
            
set_port(v) click to toggle source
 
               # File uri/generic.rb, line 429
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 534
def set_query(v)
  @query = v
end
            
set_registry(v) click to toggle source
 
               # File uri/generic.rb, line 465
def set_registry(v)
  @registry = v
end
            
set_scheme(v) click to toggle source
 
               # File uri/generic.rb, line 250
def set_scheme(v)
  @scheme = v
end
            
set_user(v) click to toggle source
 
               # File uri/generic.rb, line 345
def set_user(v)
  set_userinfo(v, @password)
  v
end
            
set_userinfo(user, password = nil) click to toggle source
 
               # File uri/generic.rb, line 334
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.

blog comments powered by Disqus