In Files
- uri/generic.rb
Parent
Object
Methods
- ::build
- ::build2
- ::component
- ::default_port
- ::new
- #+
- #-
- #==
- #absolute
- #absolute?
- #coerce
- #component
- #component_ary
- #default_port
- #eql?
- #find_proxy
- #fragment=
- #hash
- #hierarchical?
- #host=
- #hostname
- #hostname=
- #inspect
- #merge
- #merge!
- #normalize
- #normalize!
- #opaque=
- #parser
- #password
- #password=
- #path=
- #port=
- #query=
- #registry=
- #relative?
- #route_from
- #route_to
- #scheme=
- #select
- #set_host
- #set_opaque
- #set_password
- #set_path
- #set_port
- #set_scheme
- #set_user
- #set_userinfo
- #to_s
- #user
- #user=
- #userinfo
- #userinfo=
Included Modules
URI::Generic
Constants
- COMPONENT
An Array of the available components for URI::Generic
- DEFAULT_PORT
A Default port of nil for URI::Generic
Attributes
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"
Public Class Methods
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 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
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 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) 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
Components of the URI in the order.
# File uri/generic.rb, line 56 def self.component self::COMPONENT end
Returns default port
# File uri/generic.rb, line 31 def self.default_port self::DEFAULT_PORT end
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 uri/generic.rb, line 168 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.userinfo = userinfo self.hostname = host self.port = port self.path = path self.query = query self.opaque = opaque 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.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 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
Public Instance Methods
Compares to URI’s
# File uri/generic.rb, line 1383 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 960 def absolute? if @scheme true else false end end
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 uri/generic.rb, line 1473 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 311 def component self.class.component end
Returns default port
# File uri/generic.rb, line 38 def default_port self.class.default_port end
# File uri/generic.rb, line 1395 def eql?(oth) self.class == oth.class && parser == oth.parser && self.component_ary.eql?(oth.component_ary) end
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 uri/generic.rb, line 1497 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
check 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" # => "time=1305212086" uri #=> #<URI::HTTP:0x000000007a81f8 URL:http://my.example.com/?id=25#time=1305212086>
# File uri/generic.rb, line 933 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
Checks if URI has a path
# File uri/generic.rb, line 949 def hierarchical? if @path true else false end end
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 uri/generic.rb, line 635 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 (and future IP) addresses are removed.
u = URI(“http://[::1]/bar”) p u.hostname #=> “::1” p u.host #=> “[::1]”
# File uri/generic.rb, line 650 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 argument seems IPv6 address, it is wrapped by brackets.
# File uri/generic.rb, line 668 def hostname=(v) v = "[#{v}]" if /\A\[.*\]\z/ !~ v && /:/ =~ v self.host = v end
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 1098 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.fragment=(rel.fragment) if rel.fragment return base end base.query = nil base.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.query = rel.query if rel.query base.fragment=(rel.fragment) if rel.fragment return base end
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 1070 def merge!(oth) t = merge(oth) if self == t nil else replace!(t) self end end
Returns normalized URI
# File uri/generic.rb, line 1319 def normalize uri = dup uri.normalize! uri end
Destructive version of normalize
# File uri/generic.rb, line 1328 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
returns the parser to be used.
Unless a URI::Parser is defined, then DEFAULT_PARSER is used.
# File uri/generic.rb, line 288 def parser if !defined?(@parser) || !@parser DEFAULT_PARSER else @parser || DEFAULT_PARSER end end
returns the password component
# File uri/generic.rb, line 577 def password @password end
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 uri/generic.rb, line 502 def password=(password) check_password(password) set_password(password) # returns password end
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 uri/generic.rb, line 816 def path=(v) check_path(v) set_path(v) v end
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 uri/generic.rb, line 728 def port=(v) check_port(v) set_port(v) port end
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" # => "id=1" uri #=> #<URI::HTTP:0x000000008e89e8 URL:http://my.example.com/?id=1>
# File uri/generic.rb, line 842 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) v.gsub!(/(?!%\h\h|[!$-&(-;=?-_a-~])./n.freeze){'%%%02X' % $&.ord} v.force_encoding(Encoding::US_ASCII) @query = v end
# File uri/generic.rb, line 744 def registry=(v) raise InvalidURIError, "can not set registry" end
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 1272 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
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 1312 def route_to(oth) parser.send(:convert_to_uri, oth).route_from(self) end
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 uri/generic.rb, line 360 def scheme=(v) check_scheme(v) set_scheme(v) v end
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 1439 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 1343 def to_s str = ''.dup if @scheme str << @scheme str << ':' end if @opaque str << @opaque 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 str << @path if @query str << '?' str << @query end end if @fragment str << '#' str << @fragment end str end
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 uri/generic.rb, line 473 def user=(user) check_user(user) set_user(user) # returns user end
Protected Instance Methods
returns an Array of the components defined from the COMPONENT Array
# File uri/generic.rb, line 1415 def component_ary component.collect do |x| self.send(x) end end
protected setter for the host component v
see also #host=
# File uri/generic.rb, line 607 def set_host(v) @host = v end
protected setter for the opaque component v
see also #opaque=
# File uri/generic.rb, line 885 def set_opaque(v) @opaque = v end
protected setter for the password component v
see also #password=
# File uri/generic.rb, line 538 def set_password(v) @password = v # returns v end
protected setter for the path component v
see also #path=
# File uri/generic.rb, line 788 def set_path(v) @path = v end
protected setter for the port component v
see also #port=
# File uri/generic.rb, line 699 def set_port(v) v = v.empty? ? nil : v.to_i unless !v || v.kind_of?(Fixnum) @port = v end
protected setter for the scheme component v
see also #scheme=
# File uri/generic.rb, line 332 def set_scheme(v) @scheme = v ? v.downcase : v end
protected setter for the user component v
see also #user=
# File uri/generic.rb, line 528 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 513 def set_userinfo(user, password = nil) unless password user, password = split_userinfo(user) end @user = user @password = password if password [@user, @password] end