Class | Addressable::URI |
In: |
lib/addressable/uri.rb
|
Parent: | Object |
This is an implementation of a URI parser based on <a href="RFC">www.ietf.org/rfc/rfc3986.txt">RFC 3986</a>, <a href="RFC">www.ietf.org/rfc/rfc3987.txt">RFC 3987</a>.
encode_component | -> | encode_component |
unencode | -> | unescape |
unencode | -> | unencode_component |
unencode | -> | unescape_component |
encode | -> | escape |
Converts a path to a file scheme URI. If the path supplied is relative, it will be returned as a relative URI. If the path supplied is actually a non-file URI, it will parse the URI as if it had been parsed with Addressable::URI.parse. Handles all of the various Microsoft-specific formats for specifying paths.
@param [String, Addressable::URI, to_str] path
Typically a <tt>String</tt> path to a file or directory, but will return a sensible return value if an absolute URI is supplied instead.
@return [Addressable::URI]
The parsed file scheme URI or the original URI if some other URI scheme was provided.
@example
base = Addressable::URI.convert_path("/absolute/path/") uri = Addressable::URI.convert_path("relative/path") (base + uri).to_s #=> "file:///absolute/path/relative/path" Addressable::URI.convert_path( "c:\\windows\\My Documents 100%20\\foo.txt" ).to_s #=> "file:///c:/windows/My%20Documents%20100%20/foo.txt" Addressable::URI.convert_path("http://example.com/").to_s #=> "http://example.com/"
Percent encodes any special characters in the URI.
@param [String, Addressable::URI, to_str] uri
The URI to encode.
@param [Class] returning
The type of object to return. This value may only be set to <tt>String</tt> or <tt>Addressable::URI</tt>. All other values are invalid. Defaults to <tt>String</tt>.
@return [String, Addressable::URI]
The encoded URI. The return type is determined by the <tt>returning</tt> parameter.
Percent encodes a URI component.
@param [String, to_str] component The URI component to encode.
@param [String, Regexp] character_class
The characters which are not percent encoded. If a <tt>String</tt> is passed, the <tt>String</tt> must be formatted as a regular expression character class. (Do not include the surrounding square brackets.) For example, <tt>"b-zB-Z0-9"</tt> would cause everything but the letters 'b' through 'z' and the numbers '0' through '9' to be percent encoded. If a <tt>Regexp</tt> is passed, the value <tt>/[^b-zB-Z0-9]/</tt> would have the same effect. A set of useful <tt>String</tt> values may be found in the <tt>Addressable::URI::CharacterClasses</tt> module. The default value is the reserved plus unreserved character classes specified in <a href="http://www.ietf.org/rfc/rfc3986.txt">RFC 3986</a>.
@return [String] The encoded component.
@example
Addressable::URI.encode_component("simple/example", "b-zB-Z0-9") => "simple%2Fex%61mple" Addressable::URI.encode_component("simple/example", /[^b-zB-Z0-9]/) => "simple%2Fex%61mple" Addressable::URI.encode_component( "simple/example", Addressable::URI::CharacterClasses::UNRESERVED ) => "simple%2Fexample"
Converts an input to a URI. The input does not have to be a valid URI — the method will use heuristics to guess what URI was intended. This is not standards-compliant, merely user-friendly.
@param [String, Addressable::URI, to_str] uri
The URI string to parse. No parsing is performed if the object is already an <tt>Addressable::URI</tt>.
@param [Hash] hints
A <tt>Hash</tt> of hints to the heuristic parser. Defaults to <tt>{:scheme => "http"}</tt>.
@return [Addressable::URI] The parsed URI.
Joins several URIs together.
@param [String, Addressable::URI, to_str] *uris
The URIs to join.
@return [Addressable::URI] The joined URI.
@example
base = "http://example.com/" uri = Addressable::URI.parse("relative/path") Addressable::URI.join(base, uri) #=> #<Addressable::URI:0xcab390 URI:http://example.com/relative/path>
Creates a new uri object from component parts.
@option [String, to_str] scheme The scheme component. @option [String, to_str] user The user component. @option [String, to_str] password The password component. @option [String, to_str] userinfo
The userinfo component. If this is supplied, the user and password components must be omitted.
@option [String, to_str] host The host component. @option [String, to_str] port The port component. @option [String, to_str] authority
The authority component. If this is supplied, the user, password, userinfo, host, and port components must be omitted.
@option [String, to_str] path The path component. @option [String, to_str] query The query component. @option [String, to_str] fragment The fragment component.
@return [Addressable::URI] The constructed URI object.
Normalizes the encoding of a URI. Characters within a hostname are not percent encoded to allow for internationalized domain names.
@param [String, Addressable::URI, to_str] uri
The URI to encode.
@param [Class] returning
The type of object to return. This value may only be set to <tt>String</tt> or <tt>Addressable::URI</tt>. All other values are invalid. Defaults to <tt>String</tt>.
@return [String, Addressable::URI]
The encoded URI. The return type is determined by the <tt>returning</tt> parameter.
Returns a URI object based on the parsed string.
@param [String, Addressable::URI, to_str] uri
The URI string to parse. No parsing is performed if the object is already an <tt>Addressable::URI</tt>.
@return [Addressable::URI] The parsed URI.
Unencodes any percent encoded characters within a URI component. This method may be used for unencoding either components or full URIs, however, it is recommended to use the unencode_component alias when unencoding components.
@param [String, Addressable::URI, to_str] uri
The URI or component to unencode.
@param [Class] returning
The type of object to return. This value may only be set to <tt>String</tt> or <tt>Addressable::URI</tt>. All other values are invalid. Defaults to <tt>String</tt>.
@return [String, Addressable::URI]
The unencoded component or URI. The return type is determined by the <tt>returning</tt> parameter.
Determines if the URI is absolute.
@return [TrueClass, FalseClass]
<tt>true</tt> if the URI is absolute. <tt>false</tt> otherwise.
Creates a URI suitable for display to users. If semantic attacks are likely, the application should try to detect these and warn the user. See <a href="RFC">www.ietf.org/rfc/rfc3986.txt">RFC 3986</a>, section 7.6 for more information.
@return [Addressable::URI] A URI suitable for display purposes.
Determines if the URI is frozen.
@return [TrueClass, FalseClass]
True if the URI is frozen, false otherwise.
Determines if the scheme indicates an IP-based protocol.
@return [TrueClass, FalseClass]
<tt>true</tt> if the scheme indicates an IP-based protocol. <tt>false</tt> otherwise.
Joins two URIs together.
@param [String, Addressable::URI, to_str] The URI to join with.
@return [Addressable::URI] The joined URI.
Destructive form of join.
@param [String, Addressable::URI, to_str] The URI to join with.
@return [Addressable::URI] The joined URI.
Merges a URI with a Hash of components. This method has different behavior from join. Any components present in the hash parameter will override the original components. The path component is not treated specially.
@param [Hash, Addressable::URI, to_hash] The components to merge with.
@return [Addressable::URI] The merged URI.
@see Hash#merge
Destructive form of merge.
@param [Hash, Addressable::URI, to_hash] The components to merge with.
@return [Addressable::URI] The merged URI.
Returns a normalized URI object.
NOTE: This method does not attempt to fully conform to specifications. It exists largely to correct other people‘s failures to read the specifications, and also to deal with caching issues since several different URIs may represent the same resource and should not be cached multiple times.
@return [Addressable::URI] The normalized URI.
Destructively normalizes this URI object.
@return [Addressable::URI] The normalized URI.
Omits components from a URI.
@param [Symbol] *components The components to be omitted.
@return [Addressable::URI] The URI with components omitted.
@example
uri = Addressable::URI.parse("http://example.com/path?query") #=> #<Addressable::URI:0xcc5e7a URI:http://example.com/path?query> uri.omit(:scheme, :authority) #=> #<Addressable::URI:0xcc4d86 URI:/path?query>
Destructive form of omit.
@param [Symbol] *components The components to be omitted.
@return [Addressable::URI] The URI with components omitted.
Converts the query component to a Hash value.
@option [Symbol] notation
May be one of <tt>:flat</tt>, <tt>:dot</tt>, or <tt>:subscript</tt>. The <tt>:dot</tt> notation is not supported for assignment. Default value is <tt>:subscript</tt>.
@return [Hash] The query string parsed as a Hash object.
@example
Addressable::URI.parse("?one=1&two=2&three=3").query_values #=> {"one" => "1", "two" => "2", "three" => "3"} Addressable::URI.parse("?one[two][three]=four").query_values #=> {"one" => {"two" => {"three" => "four"}}} Addressable::URI.parse("?one.two.three=four").query_values( :notation => :dot ) #=> {"one" => {"two" => {"three" => "four"}}} Addressable::URI.parse("?one[two][three]=four").query_values( :notation => :flat ) #=> {"one[two][three]" => "four"} Addressable::URI.parse("?one.two.three=four").query_values( :notation => :flat ) #=> {"one.two.three" => "four"} Addressable::URI.parse( "?one[two][three][]=four&one[two][three][]=five" ).query_values #=> {"one" => {"two" => {"three" => ["four", "five"]}}}
Determines if the URI is relative.
@return [TrueClass, FalseClass]
<tt>true</tt> if the URI is relative. <tt>false</tt> otherwise.
Returns the shortest normalized relative form of this URI that uses the supplied URI as a base for resolution. Returns an absolute URI if necessary. This is effectively the opposite of route_to.
@param [String, Addressable::URI, to_str] uri The URI to route from.
@return [Addressable::URI]
The normalized relative URI that is equivalent to the original URI.
Returns the shortest normalized relative form of the supplied URI that uses this URI as a base for resolution. Returns an absolute URI if necessary. This is effectively the opposite of route_from.
@param [String, Addressable::URI, to_str] uri The URI to route to.
@return [Addressable::URI]
The normalized relative URI that is equivalent to the supplied URI.
If URI validation needs to be disabled, this can be set to true.
@return [TrueClass, FalseClass]
<tt>true</tt> if validation has been deferred, <tt>false</tt> otherwise.
If URI validation needs to be disabled, this can be set to true.
@param [TrueClass, FalseClass] new_validation_deferred
<tt>true</tt> if validation will be deferred, <tt>false</tt> otherwise.