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"
Expands a URI template into a full URI.
@param [String, to_str] pattern The URI template pattern. @param [Hash] mapping The mapping that corresponds to the pattern. @param [validate, transform] processor
An optional processor object may be supplied. The object should respond to either the <tt>validate</tt> or <tt>transform</tt> messages or both. Both the <tt>validate</tt> and <tt>transform</tt> methods should take two parameters: <tt>name</tt> and <tt>value</tt>. The <tt>validate</tt> method should return <tt>true</tt> or <tt>false</tt>; <tt>true</tt> if the value of the variable is valid, <tt>false</tt> otherwise. An <tt>InvalidTemplateValueError</tt> exception will be raised if the value is invalid. The <tt>transform</tt> method should return the transformed variable value as a <tt>String</tt>. If a <tt>transform</tt> method is used, the value will not be percent encoded automatically. Unicode normalization will be performed both before and after sending the value to the transform method.
@return [Addressable::URI] The expanded URI template.
@example
class ExampleProcessor def self.validate(name, value) return !!(value =~ /^[\w ]+$/) if name == "query" return true end def self.transform(name, value) return value.gsub(/ /, "+") if name == "query" return value end end Addressable::URI.expand_template( "http://example.com/search/{query}/", {"query" => "an example search query"}, ExampleProcessor ).to_s #=> "http://example.com/search/an+example+search+query/" Addressable::URI.expand_template( "http://example.com/search/{-list|+|query}/", {"query" => "an example search query".split(" ")} ).to_s #=> "http://example.com/search/an+example+search+query/" Addressable::URI.expand_template( "http://example.com/search/{query}/", {"query" => "bogus!"}, ExampleProcessor ).to_s #=> Addressable::URI::InvalidTemplateValueError
Extracts uris from an arbitrary body of text.
@param [String, to_str] text
The body of text to extract URIs from.
@option [String, Addressable::URI, to_str] base
Causes any relative URIs to be resolved against the base URI.
@option [TrueClass, FalseClass] parse
If parse is true, all extracted URIs will be parsed. If parse is false, the return value with be an <tt>Array</tt> of <tt>Strings</aa>. Defaults to false.
@return [Array] The extracted URIs.
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.
Extracts a mapping from the URI using a URI Template pattern.
@param [String] pattern
A URI template pattern.
@param [restore, match] processor
A template processor object may optionally be supplied. The object should respond to either the <tt>restore</tt> or <tt>match</tt> messages or both. The <tt>restore</tt> method should take two parameters: [String] name and [String] value. The <tt>restore</tt> method should reverse any transformations that have been performed on the value to ensure a valid URI. The <tt>match</tt> method should take a single parameter: [String] name. The <tt>match</tt> method should return a <tt>String</tt> containing a regular expression capture group for matching on that particular variable. The default value is ".*?". The <tt>match</tt> method has no effect on multivariate operator expansions.
@return [Hash, NilClass]
The <tt>Hash</tt> mapping that was extracted from the URI, or <tt>nil</tt> if the URI didn't match the template.
@example
class ExampleProcessor def self.restore(name, value) return value.gsub(/\+/, " ") if name == "query" return value end def self.match(name) return ".*?" if name == "first" return ".*" end end uri = Addressable::URI.parse( "http://example.com/search/an+example+search+query/" ) uri.extract_mapping( "http://example.com/search/{query}/", ExampleProcessor ) #=> {"query" => "an example search query"} uri = Addressable::URI.parse("http://example.com/a/b/c/") uri.extract_mapping( "http://example.com/{first}/{second}/", ExampleProcessor ) #=> {"first" => "a", "second" => "b/c"} uri = Addressable::URI.parse("http://example.com/a/b/c/") uri.extract_mapping( "http://example.com/{first}/{-list|/|second}/" ) #=> {"first" => "a", "second" => ["b", "c"]}
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.