# # Base class for all URI exceptions. # class URI::Error < StandardError end # # Not a URI. # class URI::InvalidURIError < URI::Error end # # Not a URI component. # class URI::InvalidComponentError < URI::Error end # # URI is valid, bad usage is not. # class URI::BadURIError < URI::Error end # # URI is a module providing classes to handle Uniform Resource Identifiers # ([RFC2396](http://tools.ietf.org/html/rfc2396)). # # ## Features # # * Uniform way of handling URIs. # * Flexibility to introduce custom URI schemes. # * Flexibility to have an alternate URI::Parser (or just different patterns # and regexp's). # # # ## Basic example # # require 'uri' # # uri = URI("http://foo.com/posts?id=30&limit=5#time=1305298413") # #=> # # # uri.scheme #=> "http" # uri.host #=> "foo.com" # uri.path #=> "/posts" # uri.query #=> "id=30&limit=5" # uri.fragment #=> "time=1305298413" # # uri.to_s #=> "http://foo.com/posts?id=30&limit=5#time=1305298413" # # ## Adding custom URIs # # module URI # class RSYNC < Generic # DEFAULT_PORT = 873 # end # register_scheme 'RSYNC', RSYNC # end # #=> URI::RSYNC # # URI.scheme_list # #=> {"FILE"=>URI::File, "FTP"=>URI::FTP, "HTTP"=>URI::HTTP, # # "HTTPS"=>URI::HTTPS, "LDAP"=>URI::LDAP, "LDAPS"=>URI::LDAPS, # # "MAILTO"=>URI::MailTo, "RSYNC"=>URI::RSYNC} # # uri = URI("rsync://rsync.foo.com") # #=> # # # ## RFC References # # A good place to view an RFC spec is http://www.ietf.org/rfc.html. # # Here is a list of all related RFC's: # * [RFC822](http://tools.ietf.org/html/rfc822) # * [RFC1738](http://tools.ietf.org/html/rfc1738) # * [RFC2255](http://tools.ietf.org/html/rfc2255) # * [RFC2368](http://tools.ietf.org/html/rfc2368) # * [RFC2373](http://tools.ietf.org/html/rfc2373) # * [RFC2396](http://tools.ietf.org/html/rfc2396) # * [RFC2732](http://tools.ietf.org/html/rfc2732) # * [RFC3986](http://tools.ietf.org/html/rfc3986) # # # ## Class tree # # * URI::Generic (in uri/generic.rb) # * URI::File - (in uri/file.rb) # * URI::FTP - (in uri/ftp.rb) # * URI::HTTP - (in uri/http.rb) # * URI::HTTPS - (in uri/https.rb) # # * URI::LDAP - (in uri/ldap.rb) # * URI::LDAPS - (in uri/ldaps.rb) # # * URI::MailTo - (in uri/mailto.rb) # # * URI::Parser - (in uri/common.rb) # * URI::REGEXP - (in uri/common.rb) # * URI::REGEXP::PATTERN - (in uri/common.rb) # # * URI::Util - (in uri/common.rb) # * URI::Error - (in uri/common.rb) # * URI::InvalidURIError - (in uri/common.rb) # * URI::InvalidComponentError - (in uri/common.rb) # * URI::BadURIError - (in uri/common.rb) # # # # ## Copyright Info # # Author # : Akira Yamada # Documentation # : Akira Yamada Dmitry V. Sabanin # Vincent Batts # License # : Copyright (c) 2001 akira yamada You can redistribute # it and/or modify it under the same term as Ruby. # module URI include URI::RFC2396_REGEXP # # Returns name/value pairs derived from the given string `str`, which must be an # ASCII string. # # The method may be used to decode the body of Net::HTTPResponse object `res` # for which `res['Content-Type']` is `'application/x-www-form-urlencoded'`. # # The returned data is an array of 2-element subarrays; each subarray is a # name/value pair (both are strings). Each returned string has encoding `enc`, # and has had invalid characters removed via # [String#scrub](rdoc-ref:String#scrub). # # A simple example: # # URI.decode_www_form('foo=0&bar=1&baz') # # => [["foo", "0"], ["bar", "1"], ["baz", ""]] # # The returned strings have certain conversions, similar to those performed in # URI.decode_www_form_component: # # URI.decode_www_form('f%23o=%2F&b-r=%24&b+z=%40') # # => [["f#o", "/"], ["b-r", "$"], ["b z", "@"]] # # The given string may contain consecutive separators: # # URI.decode_www_form('foo=0&&bar=1&&baz=2') # # => [["foo", "0"], ["", ""], ["bar", "1"], ["", ""], ["baz", "2"]] # # A different separator may be specified: # # URI.decode_www_form('foo=0--bar=1--baz', separator: '--') # # => [["foo", "0"], ["bar", "1"], ["baz", ""]] # def self.decode_www_form: (String str, ?encoding enc, ?isindex: boolish, ?use__charset_: boolish, ?separator: String) -> Array[[ String, String ]] # # Returns a string decoded from the given URL-encoded string `str`. # # The given string is first encoded as Encoding::ASCII-8BIT (using String#b), # then decoded (as below), and finally force-encoded to the given encoding # `enc`. # # The returned string: # # * Preserves: # # * Characters `'*'`, `'.'`, `'-'`, and `'_'`. # * Character in ranges `'a'..'z'`, `'A'..'Z'`, and `'0'..'9'`. # # # Example: # # URI.decode_www_form_component('*.-_azAZ09') # # => "*.-_azAZ09" # # * Converts: # # * Character `'+'` to character `' '`. # * Each "percent notation" to an ASCII character. # # # Example: # # URI.decode_www_form_component('Here+are+some+punctuation+characters%3A+%2C%3B%3F%3A') # # => "Here are some punctuation characters: ,;?:" # # # Related: URI.decode_uri_component (preserves `'+'`). # def self.decode_www_form_component: (String str, ?encoding enc) -> String # # Returns a URL-encoded string derived from the given # [Enumerable](rdoc-ref:Enumerable@Enumerable+in+Ruby+Classes) `enum`. # # The result is suitable for use as form data for an HTTP request whose # `Content-Type` is `'application/x-www-form-urlencoded'`. # # The returned string consists of the elements of `enum`, each converted to one # or more URL-encoded strings, and all joined with character `'&'`. # # Simple examples: # # URI.encode_www_form([['foo', 0], ['bar', 1], ['baz', 2]]) # # => "foo=0&bar=1&baz=2" # URI.encode_www_form({foo: 0, bar: 1, baz: 2}) # # => "foo=0&bar=1&baz=2" # # The returned string is formed using method URI.encode_www_form_component, # which converts certain characters: # # URI.encode_www_form('f#o': '/', 'b-r': '$', 'b z': '@') # # => "f%23o=%2F&b-r=%24&b+z=%40" # # When `enum` is Array-like, each element `ele` is converted to a field: # # * If `ele` is an array of two or more elements, the field is formed from its # first two elements (and any additional elements are ignored): # # name = URI.encode_www_form_component(ele[0], enc) # value = URI.encode_www_form_component(ele[1], enc) # "#{name}=#{value}" # # Examples: # # URI.encode_www_form([%w[foo bar], %w[baz bat bah]]) # # => "foo=bar&baz=bat" # URI.encode_www_form([['foo', 0], ['bar', :baz, 'bat']]) # # => "foo=0&bar=baz" # # * If `ele` is an array of one element, the field is formed from `ele[0]`: # # URI.encode_www_form_component(ele[0]) # # Example: # # URI.encode_www_form([['foo'], [:bar], [0]]) # # => "foo&bar&0" # # * Otherwise the field is formed from `ele`: # # URI.encode_www_form_component(ele) # # Example: # # URI.encode_www_form(['foo', :bar, 0]) # # => "foo&bar&0" # # # The elements of an Array-like `enum` may be mixture: # # URI.encode_www_form([['foo', 0], ['bar', 1, 2], ['baz'], :bat]) # # => "foo=0&bar=1&baz&bat" # # When `enum` is Hash-like, each `key`/`value` pair is converted to one or more # fields: # # * If `value` is # [Array-convertible](rdoc-ref:implicit_conversion.rdoc@Array-Convertible+Ob # jects), each element `ele` in `value` is paired with `key` to form a # field: # # name = URI.encode_www_form_component(key, enc) # value = URI.encode_www_form_component(ele, enc) # "#{name}=#{value}" # # Example: # # URI.encode_www_form({foo: [:bar, 1], baz: [:bat, :bam, 2]}) # # => "foo=bar&foo=1&baz=bat&baz=bam&baz=2" # # * Otherwise, `key` and `value` are paired to form a field: # # name = URI.encode_www_form_component(key, enc) # value = URI.encode_www_form_component(value, enc) # "#{name}=#{value}" # # Example: # # URI.encode_www_form({foo: 0, bar: 1, baz: 2}) # # => "foo=0&bar=1&baz=2" # # # The elements of a Hash-like `enum` may be mixture: # # URI.encode_www_form({foo: [0, 1], bar: 2}) # # => "foo=0&foo=1&bar=2" # def self.encode_www_form: (Enumerable[[ _ToS, _ToS ]] enum, ?encoding? enc) -> String # # Returns a URL-encoded string derived from the given string `str`. # # The returned string: # # * Preserves: # # * Characters `'*'`, `'.'`, `'-'`, and `'_'`. # * Character in ranges `'a'..'z'`, `'A'..'Z'`, and `'0'..'9'`. # # # Example: # # URI.encode_www_form_component('*.-_azAZ09') # # => "*.-_azAZ09" # # * Converts: # # * Character `' '` to character `'+'`. # * Any other character to "percent notation"; the percent notation for # character *c* is `'%%%X' % c.ord`. # # # Example: # # URI.encode_www_form_component('Here are some punctuation characters: ,;?:') # # => "Here+are+some+punctuation+characters%3A+%2C%3B%3F%3A" # # # Encoding: # # * If `str` has encoding Encoding::ASCII_8BIT, argument `enc` is ignored. # * Otherwise `str` is converted first to Encoding::UTF_8 (with suitable # character replacements), and then to encoding `enc`. # # # In either case, the returned string has forced encoding Encoding::US_ASCII. # # Related: URI.encode_uri_component (encodes `' '` as `'%20'`). # def self.encode_www_form_component: (_ToS str, ?encoding? enc) -> String # # ## Synopsis # # URI::extract(str[, schemes][,&blk]) # # ## Args # # `str` # : String to extract URIs from. # `schemes` # : Limit URI matching to specific schemes. # # # ## Description # # Extracts URIs from a string. If block given, iterates through all matched # URIs. Returns nil if block given or array with matches. # # ## Usage # # require "uri" # # URI.extract("text here http://foo.example.org/bla and here mailto:test@example.com and here also.") # # => ["http://foo.example.com/bla", "mailto:test@example.com"] # def self.extract: (String str, ?Array[String] schemes) -> Array[String] | (String str, ?Array[String] schemes) { (String) -> void } -> nil def self.get_encoding: (String label) -> Encoding? # # Merges the given URI strings `str` per [RFC # 2396](https://www.rfc-editor.org/rfc/rfc2396.html). # # Each string in `str` is converted to an [RFC3986 # URI](https://www.rfc-editor.org/rfc/rfc3986.html) before being merged. # # Examples: # # URI.join("http://example.com/","main.rbx") # # => # # # URI.join('http://example.com', 'foo') # # => # # # URI.join('http://example.com', '/foo', '/bar') # # => # # # URI.join('http://example.com', '/foo', 'bar') # # => # # # URI.join('http://example.com', '/foo/', 'bar') # # => # # def self.join: (_ToStr | URI::Generic str, *_ToStr | URI::Generic strs) -> URI::Generic # # Returns a new URI object constructed from the given string `uri`: # # URI.parse('https://john.doe@www.example.com:123/forum/questions/?tag=networking&order=newest#top') # # => # # URI.parse('http://john.doe@www.example.com:123/forum/questions/?tag=networking&order=newest#top') # # => # # # It's recommended to first ::escape string `uri` if it may contain invalid URI # characters. # def self.parse: (_ToStr uri) -> (File | FTP | HTTP | HTTPS | LDAP | LDAPS | MailTo | WS | WSS | Generic) # # ## Synopsis # # URI::regexp([match_schemes]) # # ## Args # # `match_schemes` # : Array of schemes. If given, resulting regexp matches to URIs whose scheme # is one of the match_schemes. # # # ## Description # # Returns a Regexp object which matches to URI-like strings. The Regexp object # returned by this method includes arbitrary number of capture group # (parentheses). Never rely on its number. # # ## Usage # # require 'uri' # # # extract first URI from html_string # html_string.slice(URI.regexp) # # # remove ftp URIs # html_string.sub(URI.regexp(['ftp']), '') # # # You should not rely on the number of parentheses # html_string.scan(URI.regexp) do |*matches| # p $& # end # def self.regexp: (?Array[String]? schemes) -> Regexp # # Returns a hash of the defined schemes: # # URI.scheme_list # # => # {"MAILTO"=>URI::MailTo, # "LDAPS"=>URI::LDAPS, # "WS"=>URI::WS, # "HTTP"=>URI::HTTP, # "HTTPS"=>URI::HTTPS, # "LDAP"=>URI::LDAP, # "FILE"=>URI::File, # "FTP"=>URI::FTP} # # Related: URI.register_scheme. # def self.scheme_list: () -> Hash[String, Class] # # Returns a new object constructed from the given `scheme`, `arguments`, and # `default`: # # * The new object is an instance of `URI.scheme_list[scheme.upcase]`. # * The object is initialized by calling the class initializer using `scheme` # and `arguments`. See URI::Generic.new. # # # Examples: # # values = ['john.doe', 'www.example.com', '123', nil, '/forum/questions/', nil, 'tag=networking&order=newest', 'top'] # URI.for('https', *values) # # => # # URI.for('foo', *values, default: URI::HTTP) # # => # # def self.for: (String scheme, *untyped arguments, ?default: Class) -> (File | FTP | HTTP | HTTPS | LDAP | LDAPS | MailTo | WS | WSS | Generic) # # Returns a 9-element array representing the parts of the URI formed from the # string `uri`; each array element is a string or `nil`: # # names = %w[scheme userinfo host port registry path opaque query fragment] # values = URI.split('https://john.doe@www.example.com:123/forum/questions/?tag=networking&order=newest#top') # names.zip(values) # # => # [["scheme", "https"], # ["userinfo", "john.doe"], # ["host", "www.example.com"], # ["port", "123"], # ["registry", nil], # ["path", "/forum/questions/"], # ["opaque", nil], # ["query", "tag=networking&order=newest"], # ["fragment", "top"]] # def self.split: (_ToStr uri) -> [ String?, String?, String?, String?, nil, String?, String?, String?, String? ] end URI::ABS_PATH: Regexp URI::ABS_URI: Regexp URI::ABS_URI_REF: Regexp # # URI::Parser.new # URI::DEFAULT_PARSER: URI::RFC2396_Parser URI::ESCAPED: Regexp URI::FRAGMENT: Regexp URI::HOST: Regexp URI::OPAQUE: Regexp URI::PORT: Regexp URI::QUERY: Regexp URI::REGISTRY: Regexp URI::REL_PATH: Regexp URI::REL_URI: Regexp URI::REL_URI_REF: Regexp URI::RFC3986_PARSER: URI::RFC3986_Parser URI::SCHEME: Regexp URI::TBLDECWWWCOMP_: Hash[String, String] URI::TBLENCWWWCOMP_: Hash[String, String] URI::UNSAFE: Regexp URI::URI_REF: Regexp URI::USERINFO: Regexp URI::VERSION: String URI::VERSION_CODE: String URI::WEB_ENCODINGS_: Hash[String, String] %a{annotate:rdoc:skip} module Kernel private # # Returns a URI object derived from the given `uri`, which may be a URI string # or an existing URI object: # # # Returns a new URI. # uri = URI('http://github.com/ruby/ruby') # # => # # # Returns the given URI. # URI(uri) # # => # # def self?.URI: (URI::Generic | String uri) -> URI::Generic end