Extended maintenance of Ruby 1.9.3 ended on February 23, 2015. Read more
Object
An Array of the available components for URI::Generic
A Default port of nil for URI::Generic
Default to not use the registry for a URI::Generic
returns the fragment component of the URI.
URI("http://foo/bar/baz?search=FooBar#ponies").fragment #=> "ponies"
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 TCPSocket.open. If unwrapped host names are required, use “hostname” method.
URI("http://[::1]/bar/baz").host #=> "[::1]" URI("http://[::1]/bar/baz").hostname #=> "::1"
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)
returns the port component of the URI.
URI("http://foo/bar/baz").port #=> "80" URI("http://foo:8080/bar/baz").port #=> "8080"
returns the query component of the URI.
URI("http://foo/bar/baz?search=FooBar").query #=> "search=FooBar"
See new
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 121 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
See new
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 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 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
Components of the URI in the order.
# File uri/generic.rb, line 54 def self.component self::COMPONENT end
Returns default port
# File uri/generic.rb, line 29 def self.default_port self::DEFAULT_PORT end
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]
Creates a new URI::Generic instance from “generic” components without check.
# File uri/generic.rb, line 172 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
Compares to URI’s
# File uri/generic.rb, line 1497 def ==(oth) if self.class == oth.class self.normalize.component_ary == oth.normalize.component_ary else false end end
Checks if URI is an absolute one
# File uri/generic.rb, line 1060 def absolute? if @scheme true else false end end
v
URI or String
attempt to parse other URI +oth+ return [parsed_oth, self]
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 uri/generic.rb, line 1588 def coerce(oth) case oth when String oth = parser.parse(oth) else super end return oth, self end
Components of the URI in the order.
# File uri/generic.rb, line 320 def component self.class.component end
Returns default port
# File uri/generic.rb, line 36 def default_port self.class.default_port end
# File uri/generic.rb, line 1509 def eql?(oth) self.class == oth.class && parser == oth.parser && self.component_ary.eql?(oth.component_ary) end
v
String
public setter for the fragment component v
. (with validation)
see also URI::Generic.check_fragment
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 uri/generic.rb, line 1040 def fragment=(v) check_fragment(v) set_fragment(v) v end
Checks if URI has a path
# File uri/generic.rb, line 1049 def hierarchical? if @path true else false end end
v
String
public setter for the host component v
. (with validation)
see also URI::Generic.check_host
require 'uri' uri = URI.parse("http://my.example.com") uri.host = "foo.com" # => "foo.com" uri #=> #<URI::HTTP:0x000000008e89e8 URL:http://foo.com>
# File uri/generic.rb, line 644 def host=(v) check_host(v) set_host(v) v end
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 uri/generic.rb, line 659 def hostname v = self.host /\A\[(.*)\]\z/ =~ v ? $1 : v end
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 uri/generic.rb, line 677 def hostname=(v) v = "[#{v}]" if /\A\[.*\]\z/ !~ v && /:/ =~ v self.host = v end
# File uri/generic.rb, line 1565 def inspect @@to_s.bind(self).call.sub!(/>\z/) {" URL:#{self}>"} end
oth
URI or String
Merges two URI’s.
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 1198 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
oth
URI or String
Destructive form of merge
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 1170 def merge!(oth) t = merge(oth) if self == t nil else replace!(t) self end end
Returns normalized URI
# File uri/generic.rb, line 1419 def normalize uri = dup uri.normalize! uri end
Destructive version of normalize
# File uri/generic.rb, line 1428 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
returns the parser to be used.
Unless a URI::Parser is defined, then DEFAULT_PARSER is used.
# File uri/generic.rb, line 297 def parser if !defined?(@parser) || !@parser DEFAULT_PARSER else @parser || DEFAULT_PARSER end end
returns the password component
# File uri/generic.rb, line 586 def password @password end
v
String
public setter for the password
component. (with validation)
see also URI::Generic.check_password
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 uri/generic.rb, line 511 def password=(password) check_password(password) set_password(password) # returns password end
v
String
public setter for the path component v
. (with validation)
see also URI::Generic.check_path
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 uri/generic.rb, line 869 def path=(v) check_path(v) set_path(v) v end
v
String
public setter for the port component v
. (with validation)
see also URI::Generic.check_port
require 'uri' uri = URI.parse("http://my.example.com") uri.port = 8080 # => 8080 uri #=> #<URI::HTTP:0x000000008e89e8 URL:http://my.example.com:8080>
# File uri/generic.rb, line 743 def port=(v) check_port(v) set_port(v) port end
v
String
public setter for the query component v
. (with validation)
see also URI::Generic.check_query
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 uri/generic.rb, line 934 def query=(v) check_query(v) set_query(v) v end
Checks if URI is relative
# File uri/generic.rb, line 1072 def relative? !absolute? end
oth
URI or String
Calculates relative path from oth to self
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 1372 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
oth
URI or String
Calculates relative path to oth from self
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 1412 def route_to(oth) parser.send(:convert_to_uri, oth).route_from(self) end
v
String
public setter for the scheme component v
. (with validation)
see also URI::Generic.check_scheme
require 'uri' uri = URI.parse("http://my.example.com") uri.scheme = "https" # => "https" uri #=> #<URI::HTTP:0x000000008e89e8 URL:https://my.example.com>
# File uri/generic.rb, line 369 def scheme=(v) check_scheme(v) set_scheme(v) v end
components
Multiple Symbol arguments defined in URI::HTTP
Selects specified components from URI
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 1553 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
Constructs String from URI
# File uri/generic.rb, line 1453 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
returns the user component
# File uri/generic.rb, line 581 def user @user end
v
String
public setter for the user
component. (with validation)
see also URI::Generic.check_user
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 uri/generic.rb, line 482 def user=(user) check_user(user) set_user(user) # returns user end
returns an Array of the components defined from the COMPONENT Array
# File uri/generic.rb, line 1529 def component_ary component.collect do |x| self.send(x) end end
protected setter for the fragment component v
see also #fragment=
# File uri/generic.rb, line 1012 def set_fragment(v) @fragment = v end
protected setter for the host component v
see also #host=
# File uri/generic.rb, line 616 def set_host(v) @host = v end
protected setter for the opaque component v
see also #opaque=
# File uri/generic.rb, line 969 def set_opaque(v) @opaque = v end
protected setter for the password component v
see also #password=
# File uri/generic.rb, line 547 def set_password(v) @password = v # returns v end
protected setter for the path component v
see also #path=
# File uri/generic.rb, line 841 def set_path(v) @path = v end
protected setter for the port component v
see also #port=
# File uri/generic.rb, line 708 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
protected setter for the query component v
see also #query=
# File uri/generic.rb, line 906 def set_query(v) @query = v end
protected setter for the registry component v
see also #registry=
# File uri/generic.rb, line 778 def set_registry(v) @registry = v end
protected setter for the scheme component v
see also #scheme=
# File uri/generic.rb, line 341 def set_scheme(v) @scheme = v end
protected setter for the user component v
see also #user=
# File uri/generic.rb, line 537 def set_user(v) set_userinfo(v, @password) v end
protect setter for the user
component, and
password
if available. (with validation)
see also #userinfo=
# File uri/generic.rb, line 522 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.