Namespace goog.uri.utils
code »Enumerations
|
Type Definitions
An array representing a set of query parameters with alternating keys
and values.
Keys are assumed to be URI encoded already and live at even indices. See
goog.uri.utils.QueryValue for details on how parameter values are encoded.
Example:
var data = [
// Simple param: ?name=BobBarker
'name', 'BobBarker',
// Conditional param -- may be omitted entirely.
'specialDietaryNeeds', hasDietaryNeeds() ? getDietaryNeeds() : null,
// Multi-valued param: &house=LosAngeles&house=NewYork&house=null
'house', ['LosAngeles', 'NewYork', null]
];
var data = [ // Simple param: ?name=BobBarker 'name', 'BobBarker', // Conditional param -- may be omitted entirely. 'specialDietaryNeeds', hasDietaryNeeds() ? getDietaryNeeds() : null, // Multi-valued param: &house=LosAngeles&house=NewYork&house=null 'house', ['LosAngeles', 'NewYork', null] ];
Supported query parameter values by the parameter serializing utilities.
If a value is null or undefined, the key-value pair is skipped, as an easy
way to omit parameters conditionally. Non-array parameters are converted
to a string and URI encoded. Array values are expanded into multiple
&key=value pairs, with each element stringized and URI-encoded.
Global Functions
code »goog.uri.utils.appendKeyValuePairs_ ( key, value, pairs )Appends key=value pairs to an array, supporting multi-valued objects.
Parameters |
---|
|
code »goog.uri.utils.appendParam ( uri, key, opt_value ) ⇒ string
Appends a single URI parameter.
Repeated calls to this can exhibit quadratic behavior in IE6 due to the
way string append works, though it should be limited given the 2kb limit.
string
Parameters |
---|
Returns |
|
code »goog.uri.utils.appendParams ( uri, var_args ) ⇒ string
Appends URI parameters to an existing URI.
The variable arguments may contain alternating keys and values. Keys are
assumed to be already URI encoded. The values should not be URI-encoded,
and will instead be encoded by this function.
appendParams('http://www.foo.com?existing=true',
'key1', 'value1',
'key2', 'value?willBeEncoded',
'key3', ['valueA', 'valueB', 'valueC'],
'key4', null);
result: 'http://www.foo.com?existing=true&' +
'key1=value1&' +
'key2=value%3FwillBeEncoded&' +
'key3=valueA&key3=valueB&key3=valueC'
A single call to this function will not exhibit quadratic behavior in IE,
whereas multiple repeated calls may, although the effect is limited by
fact that URL's generally can't exceed 2kb.
string
Parameters |
---|
|
Returns |
|
code »goog.uri.utils.appendParamsFromMap ( uri, map ) ⇒ string
Appends query parameters from a map.
string
code »goog.uri.utils.appendPath ( baseUri, path ) ⇒ string
Generates a URI path using a given URI and a path with checks to
prevent consecutive "//". The baseUri passed in must not contain
query or fragment identifiers. The path to append may not contain query or
fragment identifiers.
string
code »goog.uri.utils.appendQueryData_ ( buffer ) ⇒ string
Appends a URI and query data in a string buffer with special preconditions.
Internal implementation utility, performing very few object allocations.
string
Parameters |
---|
|
Returns |
|
Asserts that there are no fragment or query identifiers, only in uncompiled
mode.
Parameters |
---|
|
code »goog.uri.utils.buildFromEncodedParts ( opt_scheme, opt_userInfo, opt_domain, opt_port, opt_path, opt_queryData, opt_fragment ) ⇒ string
Builds a URI string from already-encoded parts.
No encoding is performed. Any component may be omitted as either null or
undefined.
string
Parameters |
---|
|
Returns |
|
code »goog.uri.utils.buildQueryData ( keysAndValues, opt_startIndex ) ⇒ string
Builds a query data string from a sequence of alternating keys and values.
Currently generates "&key&" for empty args.
string
Parameters |
---|
|
Returns |
|
code »goog.uri.utils.buildQueryDataBufferFromMap_ ( buffer, map ) ⇒ !Array
Builds a buffer of query data from a map.
!Array
Parameters |
---|
|
Returns |
|
code »goog.uri.utils.buildQueryDataBuffer_ ( buffer, keysAndValues, opt_startIndex ) ⇒ !Array
Builds a buffer of query data from a sequence of alternating keys and values.
!Array
Parameters |
---|
|
Returns |
|
Builds a query data string from a map.
Currently generates "&key&" for empty args.
Parameters |
---|
|
Returns |
|
code »goog.uri.utils.decodeIfPossible_ ( uri, opt_preserveReserved ) ⇒ ?string
?string
code »goog.uri.utils.findParam_ ( uri, startIndex, keyEncoded, hashOrEndIndex ) ⇒ number
Finds the next instance of a query parameter with the specified name.
Does not instantiate any objects.
number
Parameters |
---|
|
Returns |
|
code »goog.uri.utils.getComponentByIndex_ ( componentIndex, uri ) ⇒ ?string
Gets a URI component by index.
It is preferred to use the getPathEncoded() variety of functions ahead,
since they are more readable.
?string
Parameters |
---|
|
Returns |
|
code »goog.uri.utils.getDomain ( uri ) ⇒ ?string
?string
Parameters |
---|
|
Returns |
|
code »goog.uri.utils.getDomainEncoded ( uri ) ⇒ ?string
?string
Parameters |
---|
|
Returns |
|
Gets the effective scheme for the URL. If the URL is relative then the
scheme is derived from the page's location.
Parameters |
---|
|
Returns |
|
code »goog.uri.utils.getFragment ( uri ) ⇒ ?string
?string
Parameters |
---|
|
Returns |
|
code »goog.uri.utils.getFragmentEncoded ( uri ) ⇒ ?string
?string
Parameters |
---|
|
Returns |
|
code »goog.uri.utils.getHost ( uri ) ⇒ string
Extracts everything up to the port of the URI.
string
Parameters |
---|
|
Returns |
|
code »goog.uri.utils.getParamValue ( uri, keyEncoded ) ⇒ ?string
Gets the first value of a query parameter.
?string
code »goog.uri.utils.getParamValues ( uri, keyEncoded ) ⇒ !Array.<string>
Gets all values of a query parameter.
!Array.<string>
code »goog.uri.utils.getPath ( uri ) ⇒ ?string
?string
Parameters |
---|
|
Returns |
|
code »goog.uri.utils.getPathAndAfter ( uri ) ⇒ string
Extracts the path of the URL and everything after.
string
Parameters |
---|
|
Returns |
|
code »goog.uri.utils.getPathEncoded ( uri ) ⇒ ?string
?string
Parameters |
---|
|
Returns |
|
code »goog.uri.utils.getPort ( uri ) ⇒ ?number
?number
Parameters |
---|
|
Returns |
|
code »goog.uri.utils.getQueryData ( uri ) ⇒ ?string
?string
Parameters |
---|
|
Returns |
|
code »goog.uri.utils.getScheme ( uri ) ⇒ ?string
?string
Parameters |
---|
|
Returns |
|
code »goog.uri.utils.getUserInfo ( uri ) ⇒ ?string
?string
Parameters |
---|
|
Returns |
|
code »goog.uri.utils.getUserInfoEncoded ( uri ) ⇒ ?string
?string
Parameters |
---|
|
Returns |
|
code »goog.uri.utils.hasParam ( uri, keyEncoded ) ⇒ boolean
Determines if the URI contains a specific key.
Performs no object instantiations.
boolean
code »goog.uri.utils.haveSameDomain ( uri1, uri2 ) ⇒ boolean
Ensures that two URI's have the exact same domain, scheme, and port.
Unlike the version in goog.Uri, this checks protocol, and therefore is
suitable for checking against the browser's same-origin policy.
boolean
code »goog.uri.utils.makeUnique ( uri ) ⇒ string
Sets the zx parameter of a URI to a random value.
string
Parameters |
---|
|
Returns |
|
Check to see if the user is being phished.
code »goog.uri.utils.removeFragment ( uri ) ⇒ string
Gets the URI with the fragment identifier removed.
string
Parameters |
---|
|
Returns |
|
code »goog.uri.utils.removeParam ( uri, keyEncoded ) ⇒ string
Removes all instances of a query parameter.
string
code »goog.uri.utils.setFragmentEncoded ( uri, fragment ) ⇒ string
string
code »goog.uri.utils.setParam ( uri, keyEncoded, value ) ⇒ string
Replaces all existing definitions of a parameter with a single definition.
Repeated calls to this can exhibit quadratic behavior due to the need to
find existing instances and reconstruct the string, though it should be
limited given the 2kb limit. Consider using appendParams to append multiple
parameters in bulk.
string
code »goog.uri.utils.setPath ( uri, path ) ⇒ string
Replaces the path.
string
code »goog.uri.utils.split ( uri ) ⇒ !Array
Splits a URI into its component parts.
Each component can be accessed via the component indices; for example:
goog.uri.utils.split(someStr)[goog.uri.utils.CompontentIndex.QUERY_DATA];
!Array
Parameters |
---|
|
Returns |
|
Global Properties
Regular expression for finding a hash mark or end of string.
Safari has a nasty bug where if you have an http URL with a username, e.g.,
http://evil.com%2F@google.com/
Safari will report that window.location.href is
http://evil.com/google.com/
so that anyone who tries to parse the domain of that URL will get
the wrong domain. We've seen exploits where people use this to trick
Safari into loading resources from evil domains.
To work around this, we run a little "Safari phishing check", and throw
an exception if we see this happening.
There is no convenient place to put this check. We apply it to
anyone doing URI parsing on Webkit. We're not happy about this, but
it fixes the problem.
This should be removed once Safari fixes their bug.
Exploit reported by Masato Kinugawa.
A regular expression for breaking a URI into its component parts.
http://www.ietf.org/rfc/rfc3986.txt
says in Appendix B
As the "first-match-wins" algorithm is identical to the "greedy"
disambiguation method used by POSIX regular expressions, it is natural and
commonplace to use a regular expression for parsing the potential five
components of a URI reference.
The following line is the regular expression for breaking-down a
well-formed URI reference into its components.
^(([^:/?#]+):)?(//([^/?#]*))?([^?#]*)(\?([^#]*))?(#(.*))?
12 3 4 5 6 7 8 9
The numbers in the second line above are only to assist readability; they
indicate the reference points for each subexpression (i.e., each paired
parenthesis). We refer to the value matched for subexpression as $.
For example, matching the above expression to
http://www.ics.uci.edu/pub/ietf/uri/#Related
results in the following subexpression matches:
$1 = http:
$2 = http
$3 = //www.ics.uci.edu
$4 = www.ics.uci.edu
$5 = /pub/ietf/uri/
$6 =
$7 =
$8 = #Related
$9 = Related
where indicates that the component is not present, as is the
case for the query component in the above example. Therefore, we can
determine the value of the five components as
scheme = $2
authority = $4
path = $5
query = $7
fragment = $9
The regular expression has been modified slightly to expose the
userInfo, domain, and port separately from the authority.
The modified version yields
$1 = http scheme
$2 = userInfo -\
$3 = www.ics.uci.edu domain | authority
$4 = port -/
$5 = /pub/ietf/uri/ path
$6 = query without ?
$7 = Related fragment without #
http://www.ietf.org/rfc/rfc3986.txt
says in Appendix B
As the "first-match-wins" algorithm is identical to the "greedy"
disambiguation method used by POSIX regular expressions, it is natural and
commonplace to use a regular expression for parsing the potential five
components of a URI reference.
The following line is the regular expression for breaking-down a
well-formed URI reference into its components.
http://www.ics.uci.edu/pub/ietf/uri/#Relatedresults in the following subexpression matches:
$1 = http: $2 = http $3 = //www.ics.uci.edu $4 = www.ics.uci.edu $5 = /pub/ietf/uri/ $6 =where$7 = $8 = #Related $9 = Related
scheme = $2 authority = $4 path = $5 query = $7 fragment = $9The regular expression has been modified slightly to expose the userInfo, domain, and port separately from the authority. The modified version yields
$1 = http scheme $2 =userInfo -\ $3 = www.ics.uci.edu domain | authority $4 = port -/ $5 = /pub/ietf/uri/ path $6 = query without ? $7 = Related fragment without #